How to Run Apidog CLI API Tests in CircleCI

To run Apidog CLI API tests in CircleCI, add a .circleci/config.yml file that uses a cimg/node Docker executor, installs apidog-cli with npm, and runs apidog run with your access token, test scenario ID, and environment ID. Store the token and IDs as CircleCI environment variables, then publish the JUnit and HTML reports with store_test_results and store_artifacts. This guide walks through each piece so you can copy, paste, and ship.

This article is about running tests, not picking a CI platform. If you are still deciding between tools, the CircleCI vs Jenkins comparison covers that ground. Here we assume you already chose CircleCI and want your API suite running on every push.

What CircleCI is and how it works

CircleCI is a cloud-based continuous integration and delivery service. It watches your Git repository, and when you push a commit, it runs the build, test, and deploy steps you defined. You describe those steps in a single YAML file, so your pipeline lives in version control alongside your code.

Everything starts with .circleci/config.yml at the root of your repo. CircleCI reads this file on every push and turns it into a pipeline. The current config format is version 2.1, which adds reusable building blocks like orbs, commands, and parameters on top of the base 2.0 engine.

A CircleCI config has three core concepts:

• Jobs are units of work. Each job runs a series of steps, such as checking out code, installing dependencies, or running a test command.
• Executors define where a job runs. A Docker executor runs your steps inside a container image you pick, like cimg/node for Node.js projects.
• Workflows orchestrate jobs. A workflow decides which jobs run, in what order, and whether they run in parallel or in sequence.

That separation matters for API testing. You define one job that installs the Apidog CLI and runs your scenarios, then a workflow that triggers it on the branches you care about.

Why run API tests in CircleCI

Running your API suite in CI catches contract breaks before they reach production. A schema change, a renamed field, or a broken auth flow shows up as a red build instead of a support ticket.

The Apidog CLI is built for exactly this. You design and debug a test scenario in the Apidog app, then run that same scenario headless in CI with one command. No rewriting assertions in code, and no separate test harness to maintain.

If you want the broader picture of how automated checks fit into a pipeline, the 12 CI/CD best practices for API testing guide is a good companion read.

Prerequisites

Before you write the config, get these ready in the Apidog app:

• An access token. Generate it under your Apidog account settings. This authenticates the CLI in headless environments. The Apidog CLI authentication guide covers token creation and CI secret handling in detail.
• A test scenario ID. Open the test scenario you want to run and copy its ID from the URL or scenario settings.
• An environment ID. This tells the CLI which base URL and variables to use, such as staging or production.

You will also need a CircleCI account connected to your Git provider, with the project enabled in the CircleCI dashboard.

Store secrets as environment variables

Never hardcode your access token in config.yml. The file is committed to Git, so a token there is a leaked token.

CircleCI gives you two safe options:

• Project environment variables. In the CircleCI UI, open Project Settings, then Environment Variables, and add each value. They are encrypted and exposed to jobs as $VARS.
• Contexts. A context is a named group of environment variables shared across projects. You create it under Organization Settings, then Contexts, and reference it from a workflow. Contexts are useful when several repos share the same Apidog token.

For this guide, add three variables: APIDOG_ACCESS_TOKEN, APIDOG_TEST_SCENARIO_ID, and APIDOG_ENVIRONMENT_ID. The CLI reads them at runtime, and nothing sensitive lives in your repo.

The full config.yml

Here is a complete, copy-paste config. Drop it at .circleci/config.yml, set your three environment variables, and push.

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

Let me break down what each part does.

The executor

docker:
  - image: cimg/node:20.11

cimg/node is CircleCI’s convenience image for Node.js. It ships with Node, npm, and common build tools preinstalled, so npm install -g apidog-cli works without extra setup. The :20.11 tag pins a Node version; pin to whatever your team standardizes on.

The steps

checkout pulls your repository into the job’s working directory. The first run step installs the CLI globally. The second run step executes your tests.

Look at the test command closely:

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

Each flag does one job:

• --access-token authenticates the run. It has no short form.
• -t selects the test scenario by ID.
• -e selects the environment. This flag is required; the CLI needs to know which base URL and variables to use.
• -r sets the reporters. Here you ask for three: cli prints live results to the build log, junit writes machine-readable XML, and html writes a browsable report.
• --out-dir tells the CLI where to write the report files.

Publishing the reports

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

store_test_results points CircleCI at the JUnit XML in ./reports. CircleCI parses it and shows a Tests tab on the build, so failures are listed by name with timing data. This is what turns a wall of log text into a structured pass/fail view.

store_artifacts uploads the same directory as downloadable files, including the HTML report. After a build, you open the Artifacts tab and view the rendered report in your browser. The Apidog CLI test reports guide explains the CLI, HTML, and JSON formats in more depth.

The workflow

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

This workflow runs the api-tests job on every push. You can add filters to restrict it to certain branches, or add other jobs that run before or after it. For a single test job, this minimal block is all you need.

Run tests only on the main branch

You may not want a full API run on every feature branch. Add a branch filter to the workflow:

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

Now the job runs only on pushes to main and develop. Other branches skip it, which keeps your build minutes focused on the branches that ship.

Use a Context instead of project variables

If several repositories share one Apidog token, a Context keeps it in one place. Create the Context in Organization Settings, add your variables there, then reference it:

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

The job now reads APIDOG_ACCESS_TOKEN and the rest from the apidog-secrets Context. Rotate the token once, and every project picks up the new value.

Data-driven runs and other options

The CLI has more flags than this guide uses. Two are worth knowing for CI.

You can repeat a scenario across rows of test data with -d and -n:

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 takes a CSV or JSON file path, or a numeric stored-data-set ID, and runs the scenario once per row. The data-driven testing guide shows how to structure those files.

You can also control how the run handles failures with --on-error, which accepts continue, end, or ignore. And for projects that use Apidog branches, --project <id> --branch <name> targets a specific branch. To push a report overview to the Apidog cloud, add --upload-report as a bare flag.

How this fits the Apidog workflow

The point of the Apidog CLI is that you do not write or maintain test code. You build a test scenario from the command line or in the visual test builder, set assertions on status codes and response bodies, and save it. CI then runs that exact scenario.

Because the scenario lives in your Apidog project, your team edits tests in one place. The CI config rarely changes; it just calls apidog run. When someone adds an assertion in the app, the next CircleCI build picks it up with no YAML edit.

That keeps a clean split. Apidog owns what gets tested. CircleCI owns when and where it runs. If you want to compare CircleCI against other runners for this kind of work, the roundup of continuous integration tools for API teams lays out the trade-offs.

Ready to put your API suite on every push? Download Apidog, build a test scenario, and drop the config above into your repo.

Frequently Asked Questions

What is CircleCI?

CircleCI is a cloud continuous integration and delivery platform. It connects to your Git repository, reads a .circleci/config.yml file, and automatically runs build, test, and deploy steps each time you push code. It removes the need to run those steps by hand on your own machine.

What is CircleCI used for?

Teams use CircleCI to automate testing and deployment. Common jobs include compiling code, running unit and integration tests, checking API contracts, building Docker images, and shipping releases to staging or production. In this guide, the job runs Apidog CLI API tests on every push.

Is CircleCI free?

CircleCI has a free plan that includes a monthly allotment of build credits, which is enough for small projects and personal repos. Larger teams that need more concurrency, longer build minutes, or bigger machines move to paid Performance and Scale plans. Check CircleCI’s current pricing page for exact limits.

Is CircleCI open source?

No, CircleCI is a commercial, hosted product, not open source. You configure it through a YAML file and run it on CircleCI’s infrastructure or a self-hosted runner. If you need a fully open-source CI server, Jenkins is the common alternative, which the CircleCI vs Jenkins comparison discusses.

How does CircleCI work?

When you push a commit, CircleCI detects the change, reads .circleci/config.yml, and spins up the executor you defined, such as a cimg/node Docker container. It runs each step in your jobs in order, then reports results back to your Git provider. Workflows let you chain and parallelize jobs. For the bigger picture of how this fits a delivery pipeline, see the What is CI/CD guide.