Skip to main content

CI/CD Integration

Integrating Dochia into your CI/CD pipeline allows you to automate API testing, catch regressions early, and ensure the quality of your services with every code change.

Core Concepts​

Exit Codes​

Dochia uses exit codes to signal the outcome of a test run, which CI/CD platforms use to determine if a job should pass or fail:

  • 0: Success (no errors found).
  • 1: One or more test errors found during execution.
  • 2: Usage error or internal error (invalid arguments, missing files, internal fault).

Your CI job will automatically fail if the exit code is non-zero.

Quality Gates​

For fine-grained control over what constitutes a failure in CI, use --fail-on and --quality-gate:

# Fail the pipeline on any error or warning
dochia test -c api.yml -s "$API_URL" --fail-on error,warn

# Tolerate up to 4 errors and 19 warnings before failing
dochia test -c api.yml -s "$API_URL" --quality-gate "errors<5,warns<20"

# Combine: fail on any warning AND fail if errors reach 5
dochia test -c api.yml -s "$API_URL" \
  --fail-on warn \
  --quality-gate "errors<5"

Run Profiles​

Profiles let you select the right test suite for each stage of your pipeline without manually listing playbooks:

# Fast smoke test on every commit
dochia test -c api.yml -s "$API_URL" --profile quick

# Balanced CI suite (recommended for most pipelines)
dochia test -c api.yml -s "$API_URL" --profile ci

# Security-focused scan on nightly schedule
dochia test -c api.yml -s "$API_URL" --profile security

# Deployment health check (HappyPath only)
dochia test -c api.yml -s "$API_URL" --health-check

See dochia list --profiles for a full list of built-in profiles.

Installation in CI​

It's recommended to download and cache the Dochia binary in your CI pipeline to ensure consistent and fast execution.

# Example script to download and install Dochia
VERSION="v1.0.0"
OS="linux"
ARCH="amd64"

wget "https://github.com/dochia-dev/dochia-cli/releases/download/${VERSION}/dochia-cli-${OS}-${ARCH}.tar.gz"
tar -xzf dochia-cli-${OS}-${ARCH}.tar.gz
chmod +x dochia
./dochia --version

Authentication​

Use your CI/CD platform's secret management system to handle API keys, tokens, and other credentials securely. Expose them to your test script as environment variables.

Reporting​

Use the --output flag to save HTML reports. Your CI platform can then archive these reports as build artifacts, making them accessible for review after the pipeline completes.

dochia test -c api.yml -s "$API_URL" --output ./dochia-report

GitHub Actions Example​

Here is a complete workflow for running Dochia tests in GitHub Actions.

name: Dochia API Tests

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  api-testing:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Dochia
        run: | # Replace with your actual installation script
          wget "https://example.com/dochia-cli.tar.gz"
          tar -xzf dochia-cli.tar.gz
          chmod +x ./dochia
          echo "$(pwd)" >> $GITHUB_PATH

      - name: Run Dochia Tests
        env:
          API_URL: ${{ secrets.API_URL }}
          AUTH_TOKEN: ${{ secrets.AUTH_TOKEN }}
        run: |
          dochia test \
            -c openapi.yml \
            -s "$API_URL" \
            -H "Authorization=Bearer $AUTH_TOKEN" \
            --output ./dochia-report

      - name: Upload Test Report
        if: always() # Always run this step to upload reports even if tests fail
        uses: actions/upload-artifact@v3
        with:
          name: dochia-test-report
          path: ./dochia-report

GitLab CI Example​

Here is a .gitlab-ci.yml configuration for running Dochia tests in GitLab CI.

stages:
  - test

api_test:
  stage: test
  image: ubuntu:latest
  variables:
    API_URL: $STAGING_API_URL
    AUTH_TOKEN: $STAGING_AUTH_TOKEN

  before_script:
    - apt-get update && apt-get install -y wget
    - | # Replace with your actual installation script
      wget "https://example.com/dochia-cli.tar.gz"
      tar -xzf dochia-cli.tar.gz
      chmod +x ./dochia

  script:
    - ./dochia test \
      -c openapi.yml \
      -s "$API_URL" \
      -H "Authorization=Bearer $AUTH_TOKEN" \
      --output ./dochia-report

  artifacts:
    when: always
    paths:
      - ./dochia-report
    expire_in: 1 week

Best Practices for CI/CD​

  • Cache the Dochia Binary: Use your CI platform's caching mechanism to avoid downloading Dochia on every run.
  • Use Profiles for Each Stage: Use --profile quick or --profile ci on every commit, --profile security or --profile compliance on nightly schedules, and --health-check as a post-deployment smoke test.
  • Set Quality Gates: Use --quality-gate to define acceptable error thresholds rather than treating any single failure as a pipeline break — especially useful when introducing Dochia to a legacy API.
  • Use Blackbox Mode (-b): In staging environments where 4xx validation errors are expected, blackbox mode limits failures to 5xx server errors only.
  • Centralize Configuration: Use YAML files for headers, reference data, and query parameters to keep your CI scripts clean and maintainable.
  • Save Reports as Artifacts: Always pass --output and archive the report folder so failures are easy to investigate after the pipeline completes.

See Also​