How to Run Apidog CLI API Tests in CircleCI

To run Apidog CLI API tests in CircleCI, create .circleci/config.yml, use a cimg/node Docker executor, install apidog-cli with npm, and run apidog run with your access token, test scenario ID, and environment ID. Store those values as CircleCI environment variables, then publish JUnit and HTML reports with store_test_results and store_artifacts.

Try Apidog today

This guide focuses on implementation: how to wire an existing Apidog API test scenario into CircleCI so it runs on every push. If you are still comparing CI tools, read the CircleCI vs Jenkins comparison. Here, we assume CircleCI is already your CI runner.

What CircleCI runs

CircleCI is a cloud CI/CD platform that watches your Git repository and runs jobs when code changes. Your pipeline is defined in:

.circleci/config.yml

CircleCI reads this file on every push and starts the configured pipeline.

A CircleCI config usually contains three parts:

• Jobs: units of work, such as installing dependencies and running tests.
• Executors: the runtime environment for a job, such as a Docker image.
• Workflows: orchestration rules that decide which jobs run and in what order.

For Apidog API testing, you only need one job:

1. Check out the repository.
2. Install the Apidog CLI.
3. Run an Apidog test scenario.
4. Upload test reports.

Why run Apidog API tests in CircleCI

Running API tests in CI helps catch regressions before they reach production. Examples include:

• A response schema changes unexpectedly.
• A required field is renamed or removed.
• Authentication breaks.
• An endpoint starts returning the wrong status code.
• A staging deployment introduces a contract mismatch.

The Apidog CLI lets you run the same scenarios you created in Apidog from a terminal or CI job. You do not need to rewrite those assertions in a separate test framework.

For a broader CI/CD testing strategy, see the 12 CI/CD best practices for API testing.

Prerequisites

Before creating the CircleCI config, prepare these values in Apidog:

• Access token
  
  Used by the CLI to authenticate in CI. Generate it from your Apidog account settings. For more detail, see the Apidog CLI authentication guide.

• Test scenario ID
  
  The ID of the Apidog test scenario you want CircleCI to run.

• Environment ID
  
  The Apidog environment that provides the base URL and variables, such as staging or production.

You also need:

• A CircleCI account.
• Your Git repository connected to CircleCI.
• The project enabled in the CircleCI dashboard.

Store Apidog values as CircleCI environment variables

Do not hardcode tokens or IDs in config.yml. The file is committed to Git, so secrets in that file can leak.

In CircleCI, add these variables:

APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID

You can store them in either:

• Project environment variables
  
  Go to Project Settings → Environment Variables and add each value.

• Contexts
  
  Go to Organization Settings → Contexts and create a shared secret group. Use this if multiple repositories share the same Apidog token or configuration.

For a single project, project environment variables are enough.

Add the CircleCI config

Create this file in your repository:

.circleci/config.yml

Paste the following config:

version: 2.1

jobs:
  api-tests:
    docker:
      - image: cimg/node:20.11
    steps:
      - checkout
      - run:
          name: Install Apidog CLI
          command: npm install -g apidog-cli
      - run:
          name: Run Apidog API tests
          command: |
            apidog run \
              --access-token $APIDOG_ACCESS_TOKEN \
              -t $APIDOG_TEST_SCENARIO_ID \
              -e $APIDOG_ENVIRONMENT_ID \
              -r cli,junit,html \
              --out-dir ./reports
      - store_test_results:
          path: ./reports
      - store_artifacts:
          path: ./reports

workflows:
  test-api:
    jobs:
      - api-tests

Commit and push the file. CircleCI will start the api-tests job on the next push.

How the config works

Executor

docker:
  - image: cimg/node:20.11

This job runs inside CircleCI’s Node.js Docker image. It includes Node.js, npm, and common build tools, which is enough to install and run apidog-cli.

Pinning the image to cimg/node:20.11 makes the runtime predictable. If your team standardizes on a different Node.js version, update the tag.

Checkout step

- checkout

This pulls your repository into the CircleCI job workspace.

Even if the Apidog test scenario lives in Apidog, you still usually want the repo checked out so CircleCI has the project context and can access files such as test data.

Install Apidog CLI

- run:
    name: Install Apidog CLI
    command: npm install -g apidog-cli

This installs the Apidog CLI globally in the job container.

Run the API test scenario

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports

The command uses values injected by CircleCI at runtime.

Flag breakdown:

• --access-token authenticates the CLI.
• -t selects the Apidog test scenario.
• -e selects the Apidog environment.
• -r cli,junit,html enables three reporters:
  • cli: prints results in the CircleCI log.
  • junit: generates XML for CircleCI’s test UI.
  • html: generates a readable HTML report.
• --out-dir ./reports writes all report files to ./reports.

Publish test results and artifacts

The config publishes reports in two ways:

- store_test_results:
    path: ./reports
- store_artifacts:
    path: ./reports

store_test_results tells CircleCI to parse JUnit XML files from ./reports. This enables the CircleCI Tests tab, where failures are shown by test name.

store_artifacts uploads the report files as downloadable build artifacts. Use this for the HTML report.

For more report options, see the Apidog CLI test reports guide.

Run tests only on selected branches

By default, the workflow runs on every push.

To run API tests only on main and develop, add branch filters:

workflows:
  test-api:
    jobs:
      - api-tests:
          filters:
            branches:
              only:
                - main
                - develop

Use this when full API test runs are too expensive or slow for every feature branch.

Use a CircleCI Context for shared Apidog secrets

If multiple repositories use the same Apidog credentials, store them in a CircleCI Context.

Example:

workflows:
  test-api:
    jobs:
      - api-tests:
          context:
            - apidog-secrets

The job can then read:

APIDOG_ACCESS_TOKEN
APIDOG_TEST_SCENARIO_ID
APIDOG_ENVIRONMENT_ID

from the apidog-secrets Context.

This makes token rotation easier because you update the value once at the organization level.

Run data-driven API tests

If your scenario should run against multiple data rows, use the -d flag:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -d ./data/users.csv \
  -r cli,junit \
  --out-dir ./reports

The -d flag accepts:

• A CSV file path.
• A JSON file path.
• A numeric stored-data-set ID.

This lets one Apidog scenario run multiple times with different input data.

For file structure examples, read the data-driven testing guide.

Useful Apidog CLI options for CI

You can extend the basic command depending on your CI policy.

Control failure behavior

Use --on-error:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  --on-error end \
  -r cli,junit,html \
  --out-dir ./reports

Supported values:

• continue
• end
• ignore

Target an Apidog project branch

If your Apidog project uses branches, pass the project and branch:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  --project <id> \
  --branch <name> \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports

Upload a report overview to Apidog

Add --upload-report:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t $APIDOG_TEST_SCENARIO_ID \
  -e $APIDOG_ENVIRONMENT_ID \
  -r cli,junit,html \
  --out-dir ./reports \
  --upload-report

Recommended implementation flow

Use this sequence when adding Apidog tests to an existing CircleCI project:

1. Create or verify the API test scenario in Apidog.
2. Copy the test scenario ID.
3. Copy the environment ID.
4. Generate an Apidog access token.
5. Add the three values to CircleCI environment variables.
6. Add .circleci/config.yml.
7. Push a commit.
8. Open the CircleCI build.
9. Check the live CLI output.
10. Open the Tests tab for JUnit results.
11. Open the Artifacts tab for the HTML report.

How this fits the Apidog workflow

Apidog owns the API scenario: requests, assertions, variables, and environments.

CircleCI owns the execution schedule: when the scenario runs, which branch triggers it, and where reports are stored.

That keeps your pipeline simple. You create or update a test in Apidog, and CircleCI runs it with the same apidog run command.

You can create a test scenario from the command line or build it visually in Apidog. Once saved, the CI config does not need to change unless you switch scenario IDs, environments, or report settings.

If you want to compare CI runners for API testing workflows, see this roundup of continuous integration tools for API teams.

Ready to put your API suite on every push? Download Apidog, build a test scenario, and add the CircleCI config above to your repository.

Frequently Asked Questions

What is CircleCI?

CircleCI is a cloud continuous integration and delivery platform. It connects to your Git repository, reads .circleci/config.yml, and runs build, test, and deploy steps when you push code.

What is CircleCI used for?

Teams use CircleCI to automate CI/CD tasks such as:

• Running unit tests.
• Running integration tests.
• Checking API contracts.
• Building Docker images.
• Deploying to staging or production.

In this guide, CircleCI runs Apidog CLI API tests.

Is CircleCI free?

CircleCI has a free plan with a monthly build-credit allowance. Small projects and personal repositories may fit within that allowance. Larger teams usually use paid plans for more concurrency, longer build minutes, or larger machines. Check CircleCI’s pricing page for current limits.

Is CircleCI open source?

No. CircleCI is a commercial hosted CI/CD platform. You configure it with YAML and run jobs on CircleCI infrastructure or self-hosted runners. If you need a fully open-source CI server, Jenkins is a common alternative. The CircleCI vs Jenkins comparison covers the differences.

How does CircleCI work?

When you push a commit, CircleCI detects the change, reads .circleci/config.yml, starts the configured executor, and runs each job step in order. For this setup, it starts a cimg/node Docker container, installs apidog-cli, runs the Apidog scenario, and publishes the reports.

For more CI/CD context, read the What is CI/CD guide.