DEV Community

Cover image for How to Run Apidog CLI API Tests in Harness CI/CD
Hassann
Hassann

Posted on • Originally published at apidog.com

How to Run Apidog CLI API Tests in Harness CI/CD

You can run Apidog CLI tests in Harness with one CI stage and one Run step:

  1. Install apidog-cli.
  2. Run apidog run.
  3. Export JUnit XML.
  4. Point Harness test reporting at the XML files.

Try Apidog today

Store your Apidog access token as a Harness secret, reference it with <+secrets.getValue("...")>, and publish the CLI’s JUnit output through a reports block. The examples below include copy-paste YAML for both Harness Cloud and a self-hosted delegate.

What is Harness CI/CD?

Harness CI is the continuous integration module of the Harness platform. It builds, tests, and validates code on managed or self-hosted infrastructure, then can hand artifacts to Harness CD for deployment.

Harness pipelines are YAML-based:

  • pipeline contains metadata and stages.
  • stage defines a CI, CD, or other workflow stage.
  • execution contains ordered steps.
  • Run steps execute shell commands.

For API testing, the flow is simple: add a CI stage, run your API test command, and fail the build if the command fails.

Harness can also parse JUnit XML. Since the Apidog CLI can emit JUnit reports, Harness can show API test results in the native Tests tab.

How Harness CI works

A minimal Harness CI pipeline follows this structure:

pipeline:
  stages:
    - stage:
        type: CI
        spec:
          execution:
            steps:
              - step:
                  type: Run
                  spec:
                    shell: Sh
                    command: |-
                      echo "Run tests here"
Enter fullscreen mode Exit fullscreen mode

For shell commands, use a Run step. Its spec usually includes:

  • shell: for example Sh, Bash, PowerShell, Pwsh, or Python
  • command: the script to execute
  • reports: optional test report configuration

For Apidog, one Run step is enough to install the CLI, execute your tests, and publish JUnit results.

The Apidog CLI in one minute

The Apidog CLI runs test scenarios created in Apidog. You design and debug the scenario visually, then execute it headlessly in CI, similar to how Newman runs Postman collections.

For a comparison, see Apidog CLI vs Newman.

Install and run it with npm:

npm install -g apidog-cli

apidog run \
  --access-token <ACCESS_TOKEN> \
  -t <TEST_SCENARIO_ID> \
  -e <ENVIRONMENT_ID> \
  -r cli,junit \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Important CI flags:

Flag Purpose
--access-token Authenticates the CLI. No short form.
-t Test scenario ID.
-e Environment ID. Required.
-r Reporters. Use cli,junit for terminal output and Harness reports.
--out-dir Output directory for reports. Defaults to ./apidog-reports.

The key option for Harness is:

-r cli,junit
Enter fullscreen mode Exit fullscreen mode

That tells the CLI to write JUnit XML into the output directory. Harness can parse that XML directly.

For more detail, see the Apidog CLI test reports guide.

Store your Apidog access token as a Harness secret

Do not hardcode your Apidog token in pipeline YAML.

In Harness:

  1. Open your project, org, or account settings.
  2. Go to Secrets.
  3. Create a new Text secret.
  4. Set the identifier to: 
apidog_token
Enter fullscreen mode Exit fullscreen mode

Reference it in YAML with:

<+secrets.getValue("apidog_token")>
Enter fullscreen mode Exit fullscreen mode

For org-scoped secrets:

<+secrets.getValue("org.apidog_token")>
Enter fullscreen mode Exit fullscreen mode

For account-scoped secrets:

<+secrets.getValue("account.apidog_token")>
Enter fullscreen mode Exit fullscreen mode

Inside shell commands, wrap the expression in single quotes:

--access-token '<+secrets.getValue("apidog_token")>'
Enter fullscreen mode Exit fullscreen mode

This prevents the shell from expanding special characters such as $ if they appear in the token.

For token setup details, see the Apidog CLI authentication notes.

Harness Cloud pipeline

Use Harness Cloud if your API endpoints are publicly reachable and you want the fastest setup.

Harness Cloud provides managed Linux build machines with Node.js and npm available. In this mode, the CI stage uses:

platform:
  os: Linux
  arch: Amd64
runtime:
  type: Cloud
Enter fullscreen mode Exit fullscreen mode

You do not need to specify a Docker image for the Run step.

pipeline:
  name: Apidog API Tests
  identifier: apidog_api_tests
  projectIdentifier: YOUR_PROJECT
  orgIdentifier: YOUR_ORG
  stages:
    - stage:
        name: API Tests
        identifier: api_tests
        type: CI
        spec:
          cloneCodebase: false
          platform:
            os: Linux
            arch: Amd64
          runtime:
            type: Cloud
            spec: {}
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli

                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 \
                        -e 1629989 \
                        -n 1 \
                        -r cli,junit \
                        --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml
Enter fullscreen mode Exit fullscreen mode

Replace these values:

Placeholder Replace with
YOUR_PROJECT Harness project identifier
YOUR_ORG Harness org identifier
605067 Apidog test scenario ID
1629989 Apidog environment ID
apidog_token Your Harness secret identifier, if different

cloneCodebase: false is useful when the tests live in Apidog and the pipeline does not need your repository.

Publish test results in Harness

Harness reads JUnit XML from the reports block on the Run step:

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml
Enter fullscreen mode Exit fullscreen mode

This path must match the XML files created by:

-r cli,junit --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

After the pipeline runs, Harness shows the parsed results in the build’s Tests tab, including pass/fail status and timing.

Keep junit in the reporter list. If you switch to only cli, html, or json, Harness will not receive XML test results.

Self-hosted delegate pipeline

Use a self-hosted delegate when:

  • Your API is inside a private network.
  • Tests must run behind a VPN.
  • You need a custom runtime.
  • You want to use your own compute instead of Harness Cloud build credits.

With Kubernetes-backed CI infrastructure, the stage uses an infrastructure block instead of platform and runtime.

Each Run step also needs:

  • connectorRef
  • image

Example:

pipeline:
  name: Apidog API Tests
  identifier: apidog_api_tests
  projectIdentifier: YOUR_PROJECT
  orgIdentifier: YOUR_ORG
  stages:
    - stage:
        name: API Tests
        identifier: api_tests
        type: CI
        spec:
          cloneCodebase: false
          infrastructure:
            type: KubernetesDirect
            spec:
              connectorRef: YOUR_K8S_CONNECTOR
              namespace: harness-ci
          execution:
            steps:
              - step:
                  type: Run
                  name: Run Apidog CLI Tests
                  identifier: run_apidog_cli_tests
                  spec:
                    connectorRef: YOUR_DOCKER_CONNECTOR
                    image: node:20
                    shell: Sh
                    command: |-
                      npm install -g apidog-cli

                      apidog run \
                        --access-token '<+secrets.getValue("apidog_token")>' \
                        -t 605067 \
                        -e 1629989 \
                        -r cli,junit \
                        --out-dir ./apidog-reports
                    reports:
                      type: JUnit
                      spec:
                        paths:
                          - apidog-reports/*.xml
Enter fullscreen mode Exit fullscreen mode

Use image: node:20 to get Node.js and npm inside the pod.

Do not mix Harness Cloud and delegate-backed infrastructure in the same stage. A CI stage should use either:

platform:
runtime:
Enter fullscreen mode Exit fullscreen mode

or:

infrastructure:
Enter fullscreen mode Exit fullscreen mode

not both.

Harness Cloud vs self-hosted delegate

Choose based on network access and infrastructure ownership.

Factor Harness Cloud Self-hosted delegate
Setup No infrastructure to maintain You manage the cluster or VMs
Network access Public endpoints Private/internal endpoints
Run step image Not required Required on Kubernetes infrastructure
Compute Harness Cloud build credits Your own compute
Best for Fast setup, public APIs Internal APIs, custom runtimes

Start with Harness Cloud if your Apidog environment targets public endpoints. Move to a delegate when the API is private or needs a runtime you control.

Data-driven Apidog runs

The Apidog CLI supports CSV or JSON data files for parameterized tests.

Use:

  • -d or --iteration-data for the data file
  • -n for the number of iterations

Example:

apidog run \
  --access-token <ACCESS_TOKEN> \
  -t <TEST_SCENARIO_ID> \
  -e <ENVIRONMENT_ID> \
  -d ./data.csv \
  -n 5 \
  -r cli,junit \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

In Harness, stage the data file before running the CLI. For example, if the file is in your repo, enable checkout or clone the repo inside the Run step, then reference the file path with -d.

Example command section:

command: |-
  git clone https://github.com/YOUR_ORG/YOUR_REPO.git repo
  cd repo

  npm install -g apidog-cli

  apidog run \
    --access-token '<+secrets.getValue("apidog_token")>' \
    -t 605067 \
    -e 1629989 \
    -d ./data.csv \
    -n 5 \
    -r cli,junit \
    --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

For more patterns, see Apidog CLI data-driven testing and the automated API testing guide.

Why design tests in Apidog first?

The CLI runs scenarios that already exist in your Apidog project.

Apidog is an all-in-one API platform for design, debugging, testing, mocking, and documentation. You build the scenario once, then run it locally or in CI.

A typical workflow is:

  1. Create or import your API definition.
  2. Build a test scenario visually.
  3. Chain requests.
  4. Extract values from one response into later requests.
  5. Add assertions in the UI.
  6. Run the same scenario in Harness with apidog run.

Because Apidog is OpenAPI-native with branch support and team workspaces, backend developers and QA engineers can work from the same API source of truth.

For related CI/CD examples, see:

Download Apidog for free, create your first test scenario, then wire it into Harness using one of the YAML examples above.

Frequently Asked Questions

What is Harness CI/CD?

Harness CI/CD is a pipeline platform for building, testing, and deploying software. Pipelines are defined as YAML with stages and steps. A CI stage runs on build infrastructure, either Harness Cloud or a self-hosted delegate. A CD stage handles deployment.

How does Harness CI work?

A Harness pipeline contains stages. A CI stage declares infrastructure and an execution block. The execution block runs ordered steps. A Run step executes shell commands, which is where you install and run the Apidog CLI.

How do you store and use secrets in Harness?

Create a Text secret in the Harness secret manager and reference its identifier:

<+secrets.getValue("apidog_token")>
Enter fullscreen mode Exit fullscreen mode

Use org. or account. prefixes for org-scoped or account-scoped secrets:

<+secrets.getValue("org.apidog_token")>
<+secrets.getValue("account.apidog_token")>
Enter fullscreen mode Exit fullscreen mode

Inside shell commands, wrap the expression in single quotes.

How do you publish test results in Harness?

Add a reports block to the Run step:

reports:
  type: JUnit
  spec:
    paths:
      - apidog-reports/*.xml
Enter fullscreen mode Exit fullscreen mode

Then run Apidog CLI with the JUnit reporter:

-r cli,junit
Enter fullscreen mode Exit fullscreen mode

Harness parses the XML and shows results in the Tests tab.

Is Harness CI free?

Harness offers a free tier for CI, and Harness Cloud builds consume build credits included with your plan. Check the current Harness pricing page for up-to-date limits and pricing.

Can I run Apidog CLI tests without cloning my repo?

Yes. If your tests live in Apidog, set:

cloneCodebase: false
Enter fullscreen mode Exit fullscreen mode

The CLI authenticates with your Apidog access token and pulls the scenario and environment by ID. Your pipeline does not need source code unless you also need local files, such as data files for data-driven testing.

Top comments (0)