Run API tests in CI: GitHub Actions and GitLab CI

Click through a request once and you know it works today. Run it on every push and you know it still works tomorrow. Zyvra turns the requests you save and the checks you add to them into a command you can run in any CI system.

What you run

Save requests in a collection (a file in your project), then add checks to them: assertions on the status, headers, a value in the JSON, or a JSON Schema, and JavaScript test scripts if you need them. Run the lot with:

zyvra run "Checkout flow" --junit report.xml

• The exit code is 1 if any request could not be sent or any check failed, so the job fails.
• --junit report.xml writes a JUnit report that GitHub, GitLab, Jenkins and most other systems can show as test results. --json report.json writes the full result.
• A value one request saves, such as a login token, is available to the next request.
• --data users.csv runs the collection once per row of a CSV or JSON file.
• --env staging picks an environment, and --var name=value overrides a variable.

Test against mocks, with no real service

Add --with-mocks and Zyvra starts the project’s mock services for the run, so the tests call mocks, not a real service that has to be up. The same project that you use on your laptop runs in the pipeline unchanged. You can even make a mock fail on purpose to check your client’s retries: see testing API failures.

GitHub Actions

name: API tests
on: [push, pull_request]
jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Zyvra
        run: curl -fsSL https://www.zyvra.dev/install.sh | sh
      - name: Run the API tests
        run: ~/.local/bin/zyvra run "Checkout flow" --with-mocks --junit report.xml
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: api-test-report
          path: report.xml

GitLab CI

api-tests:
  image: debian:stable-slim
  before_script:
    - apt-get update && apt-get install -y curl ca-certificates
    - curl -fsSL https://www.zyvra.dev/install.sh | sh
  script:
    - ~/.local/bin/zyvra run "Checkout flow" --with-mocks --junit report.xml
  artifacts:
    when: always
    reports:
      junit: report.xml

Run the command from the folder that holds zyvra.yaml, which is usually the root of your repository.

Secrets in CI

Do not put tokens in the project. Mark a variable as secret on your computer, and in CI give its value as an environment variable named ZYVRA_SECRET_ plus the variable’s name (for a variable called API_KEY, set ZYVRA_SECRET_API_KEY). Zyvra reads it from the environment, and masks it in the report.

Scripts and trust

Test scripts are JavaScript, so they only run in a project that has been trusted with zyvra trust. Assertions and saved values need no trust. If a script is skipped, the run says so.

See Commands for every option, and Collections for how to add checks.