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-190: The number of test failures encountered.
  • 191: Usage error (e.g., invalid arguments).
  • 192: Internal error.

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

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.
  • Run Different Test Suites:
    • Run a quick smoke test (filter with --playbooks LargeStrings,NullValues,etc for selected playbooks) on every commit.
    • Run a full regression suite on a nightly schedule.
  • Use Blackbox Mode (-b): In development or staging environments, you might only want to fail the build on 5xx server errors, not on expected 4xx validation errors.
  • Centralize Configuration: Use YAML files for headers, reference data, and query parameters to keep your CI scripts clean and maintainable.

See Also​