How to Run Automated API Tests in TeamCity ?

Your API can pass every test locally and still break after a teammate merges a field rename. If nobody reruns the API suite, the first signal may be a crashing mobile client in production. TeamCity closes that gap by running the same checks on every change.

Try Apidog today

TeamCity, JetBrains’ CI/CD server, can compile, test, package, and deploy your application automatically. The missing piece in many pipelines is real API testing. Unit tests and successful builds do not catch broken response contracts, failed auth flows, or edge-case 500s.

This guide shows how to run automated API tests in TeamCity with Apidog and the Apidog CLI. You will design the tests in Apidog, run them headlessly in TeamCity, publish JUnit results, and fail the build when an API assertion fails.

What you’ll build

By the end, you’ll have:

• A TeamCity project connected to your Git repository
• A build configuration triggered on every push
• A TeamCity build step that runs your Apidog API test suite
• JUnit test results visible in the TeamCity Tests tab
• A pipeline that fails when an endpoint breaks

The same setup works for a small internal API or a large public API. You scale coverage by adding scenarios in Apidog, not by rewriting TeamCity pipeline logic.

Why run API tests in TeamCity?

Local testing depends on someone remembering to run the suite. CI removes that dependency. Every commit runs the same steps in the same build environment with the same assertions.

TeamCity is useful for API testing because it gives you:

• Build chains: run API tests only after deploying the current build to staging.
• Test history: track which API assertions passed or failed across builds.
• Investigation and muting: assign flaky or broken tests without blocking every team member indefinitely.
• Agent pools: run heavier API suites on dedicated agents.

TeamCity does not know your API contract by itself. It runs commands. Your job is to provide one command that:

1. Runs the full API suite.
2. Produces machine-readable test results.
3. Exits with a non-zero code when a test fails.

That is what the Apidog CLI gives you.

Step 1: Design API tests in Apidog

Before configuring TeamCity, create API tests that can run unattended. A CI test cannot depend on a human reading a JSON response. Every expected behavior must be encoded as an assertion.

Examples:

• Status code is 200
• Response body matches a JSON Schema
• id is a number
• price is greater than 0
• Response time is under 800 ms
• Authenticated endpoints reject invalid tokens

Apidog lets you design requests and attach API assertions for status codes, response bodies, schemas, headers, field values, and timings. You can also chain requests so output from one request feeds the next request.

A practical e-commerce API scenario could look like this:

1. POST /auth/login

   • Send test credentials.
   • Assert 200.
   • Extract the bearer token into a variable.

2. GET /products?category=books

   • Send the token.
   • Assert 200.
   • Assert the response is an array.
   • Assert each item has a price greater than 0.

3. POST /cart/items

   • Add a product ID.
   • Assert 201.
   • Assert the returned cart total matches the item price.

4. GET /cart

   • Assert 200.
   • Assert item count is 1.

Run the scenario in Apidog first. If it does not pass manually against your staging environment, it will not pass in TeamCity.

Group related scenarios into a test suite so CI can run them with one command.

This avoids maintaining two sets of tests: one for manual debugging and another for automation. Compared with a code-first framework like REST Assured, you avoid writing repetitive request and assertion boilerplate for every endpoint.

You can download Apidog if you want to follow along.

Step 2: Run the Apidog CLI locally

Do not debug a new CI command inside TeamCity first. Prove it locally, then copy the working command into TeamCity.

Install the Apidog CLI with npm:

npm install -g apidog-cli

Check the installation:

apidog --version

Run your test suite from Apidog using an access token and environment ID:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -e "$APIDOG_ENV_ID" \
  -r cli,html,junit

What the flags do:

• --access-token authenticates the CLI run.
• -e selects the Apidog environment, such as staging or production-readonly.
• -r selects reporters:
  • cli prints readable output to the terminal.
  • html generates a browsable report.
  • junit generates XML that TeamCity can parse.

The CLI exits with:

• 0 when all tests pass
• non-zero when any assertion fails

That exit code is what lets TeamCity fail the build automatically.

For data-driven API tests, pass a CSV or JSON file:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -d test-data/checkout-cases.csv \
  -r cli,junit

Use this for cases like:

• Many product IDs
• Invalid payload tables
• Role-based permission checks
• Boundary values

Once the command runs successfully locally, use the same command in TeamCity.

Step 3: Connect TeamCity to your repository

If you are running TeamCity locally for the first time, start with the official Docker image:

docker run -d --name teamcity-server \
  -v ~/teamcity/datadir:/data/teamcity_server/datadir \
  -v ~/teamcity/logs:/opt/teamcity/logs \
  -p 8111:8111 \
  jetbrains/teamcity-server

Open:

http://localhost:8111

Complete the first-run setup and create an admin account.

For production, use an external database and dedicated agents. For this walkthrough, the bundled agent is enough.

Create a TeamCity project:

1. Go to Administration.
2. Select Create project.
3. Choose From a repository URL.
4. Paste your Git remote URL.
5. Add credentials if the repository is private.
6. Let TeamCity create the VCS root and build configuration.

Then add a VCS trigger:

1. Open the build configuration.
2. Go to Triggers.
3. Add a VCS Trigger.
4. Keep the default rule to trigger builds on changes to the watched branch.

At this point, every push queues a build. Next, add the API test step.

Step 4: Add the Apidog CLI build step

In your TeamCity build configuration:

1. Open Build Steps.
2. Add a new step.
3. Select Command Line.
4. Choose Custom script.
5. Paste this script:

#!/bin/bash
set -e

# Install the Apidog CLI on the build agent
npm install -g apidog-cli

# Run the API test suite and emit a JUnit report for TeamCity
apidog run \
  --access-token "%env.APIDOG_ACCESS_TOKEN%" \
  -e "%env.APIDOG_ENV_ID%" \
  -r cli,junit \
  --out-dir reports

Important details:

• set -e stops the script when any command fails.
• %env.APIDOG_ACCESS_TOKEN% reads a TeamCity environment parameter.
• %env.APIDOG_ENV_ID% lets you switch environments without editing the script.
• --out-dir reports writes reports to a predictable directory.
• -r junit creates results TeamCity can display in the Tests tab.

If your agent does not have Node.js, either:

• Install Node.js earlier in the build chain.
• Use an agent image with Node.js.
• Run the step inside a Docker image such as node:20.

Also make sure the API is reachable before this step runs. If TeamCity deploys your service to staging first, run the Apidog step after deployment by using a build chain or snapshot dependency.

Step 5: Store secrets as TeamCity parameters

Do not hardcode your Apidog token in the script or commit it to your repository.

Create TeamCity parameters:

1. Open the build configuration or parent project.
2. Go to Parameters.
3. Add env.APIDOG_ACCESS_TOKEN.
4. Set Spec to Password.
5. Paste the Apidog access token.
6. Add env.APIDOG_ENV_ID with your Apidog environment ID.

Use project-level parameters if multiple build configurations need the same token. That lets you rotate the token once and apply it everywhere.

A password parameter masks the token in the TeamCity UI and build logs.

Step 6: Publish results in the TeamCity Tests tab

A red build tells you something failed. JUnit results tell you exactly which test failed.

Because the CLI command uses -r junit, it writes JUnit XML files. Configure TeamCity to read them:

1. Open your build configuration.
2. Go to Build Features.
3. Add XML report processing.
4. Set report type to Ant JUnit.
5. Set the monitoring path:

reports/*.xml

Run the build and open the Tests tab. You should see individual scenarios and assertions with pass/fail status and timing.

This makes failures easier to debug. Instead of reading a long console log, you can see that a specific assertion, such as cart total validation, started failing in a specific commit.

Step 7: Fail the build and block the merge

The build fails automatically when an API assertion fails because:

1. The Apidog CLI exits non-zero.
2. The shell script uses set -e.
3. TeamCity treats the failed command as a failed build step.

To block merges, publish TeamCity status back to your Git provider:

1. Add the Commit Status Publisher build feature.
2. Select your VCS hosting provider, such as GitHub, GitLab, or Bitbucket.
3. Add a token so TeamCity can post build statuses.
4. In your Git provider, require the TeamCity check in branch protection rules.

Now a pull request cannot merge until the API test suite passes.

Example TeamCity pipeline

A complete setup usually looks like this:

• VCS root connected to your repository
• VCS trigger for main and pull request branches
• Build step 1: deploy the service to staging or start it in Docker
• Build step 2: run the Apidog CLI suite
• Build feature: XML report processing for reports/*.xml
• Build feature: Commit Status Publisher
• Parameters:
  • env.APIDOG_ACCESS_TOKEN as a password parameter
  • env.APIDOG_ENV_ID as an environment selector

If you keep CI configuration in version control, TeamCity also supports Kotlin DSL in .teamcity/settings.kts. The underlying command stays the same:

apidog run \
  --access-token "%env.APIDOG_ACCESS_TOKEN%" \
  -e "%env.APIDOG_ENV_ID%" \
  -r cli,junit \
  --out-dir reports

You can also add a Schedule Trigger for nightly regression runs. A common pattern is:

• Fast smoke suite on every push
• Full regression suite nightly against staging

That gives developers quick feedback without dropping deeper coverage.

How this compares to other CI platforms

The pattern is portable. The core command is still apidog run; only the CI wrapper changes.

• In GitHub Actions, put the command in a workflow YAML step. See How to Automate API Tests in GitHub Actions.
• In Jenkins, put it in a Jenkinsfile stage. See How to Integrate Apidog Automated Tests with Jenkins for CI/CD.
• For the broader CI/CD strategy, see How to Automate API Tests in CI/CD.

If you are still choosing a CI server, this comparison of the best CI/CD tools explains where TeamCity fits. TeamCity is especially useful for teams that need build chains, detailed test history, Kotlin DSL, or complex multi-stage pipelines.

Common problems and fixes

TeamCity cannot find the apidog command

The agent probably does not have Node.js installed, or the global npm binary directory is not on PATH.

Fix it by:

• Installing Node.js earlier in the pipeline
• Using an agent image with Node.js
• Running the step inside node:20

Tests pass locally but fail in CI with connection errors

The TeamCity agent may not be able to reach your API.

Check that:

• The selected Apidog environment points to a reachable base URL.
• The staging API is available from the build agent network.
• VPN, firewall, or allowlist rules include the agent.

Authentication fails only in CI

Check the parameter names.

If your script uses:

%env.APIDOG_ACCESS_TOKEN%

Then the TeamCity parameter must be named exactly:

env.APIDOG_ACCESS_TOKEN

The env. prefix matters.

Also verify that the token is still valid.

Tests are flaky

Flaky API tests are usually caused by timing, shared state, or data ordering.

Fixes:

• Add response-time assertions to expose slow endpoints.
• Make each scenario create and clean up its own test data.
• Avoid relying on data left behind by previous runs.
• Use TeamCity mute/investigate features while fixing the root cause.

The Tests tab is empty

The JUnit XML path probably does not match.

Check both sides:

--out-dir reports

And TeamCity XML report monitoring path:

reports/*.xml

FAQ

Do I need to write code to run API tests in TeamCity?

No. You design requests and assertions in Apidog. TeamCity only needs a command-line build step that runs apidog run.

That is different from a code-first framework like REST Assured, where you write request and assertion code for each endpoint.

Can I run the same tests against different environments?

Yes. Define environments in Apidog, such as staging, pre-prod, or production-readonly. Then change the -e environment ID in TeamCity.

Example:

apidog run \
  --access-token "%env.APIDOG_ACCESS_TOKEN%" \
  -e "%env.APIDOG_ENV_ID%" \
  -r cli,junit

The test logic stays the same. Only the target environment changes.

How do I keep the Apidog access token secure?

Store it as a TeamCity password parameter:

env.APIDOG_ACCESS_TOKEN

Do not hardcode it in:

• Build scripts
• Repository files
• Docker images
• Plain-text TeamCity parameters

Will a failed API test block a merge?

Yes, if you configure both parts:

1. The Apidog CLI fails the TeamCity build by exiting non-zero.
2. Your Git provider requires the TeamCity status check before merging.

Use TeamCity’s Commit Status Publisher to report build status back to GitHub, GitLab, or Bitbucket.

Should I run tests online or from an exported file?

Both are possible.

Running online with an access token keeps Apidog as the source of truth. Whatever the team updates in Apidog is what CI runs.

Running from an exported file pins the tests to a version committed with your code.

Most teams start with online runs because they are easier to keep in sync.

Can I run the full regression suite on a schedule?

Yes. Add a TeamCity Schedule Trigger.

A practical setup is:

• Smoke tests on every push
• Full regression tests nightly
• Optional production-readonly checks on a separate schedule

Wrapping up

A TeamCity API testing pipeline catches broken endpoints before they reach users. The build runs on every change, executes the same API assertions, publishes structured test results, and blocks merges when the contract breaks.

The setup has three main parts:

1. Build API scenarios with assertions in Apidog.
2. Run them headlessly with apidog run.
3. Configure TeamCity to execute the command, parse JUnit reports, and publish status to your Git provider.

Once it is in place, you maintain coverage by adding or updating scenarios in Apidog instead of editing pipeline code for every endpoint.