How to Build a TeamCity CI/CD Pipeline for Selenium Tests

To build a TeamCity CI/CD pipeline for Selenium tests, connect your repository, configure a pipeline or build configuration, prepare build agents with the project’s runtime and browser requirements, and run the repository’s existing test command. Add branch triggers and make sure the test framework’s results reach TeamCity. The exact command depends on your language and build system; there is no universal Selenium command.

This guide uses a script step as the portable example. Replace the placeholder test command with the one your project already uses locally or in another CI system. See the TeamCity pipeline documentation, first-build tutorial, and Selenium Manager documentation for version-specific details.

1. Choose a TeamCity workflow

TeamCity pipelines group work into jobs and steps. Jobs can depend on other jobs, run on different agents, or run in parallel. A simple Selenium workflow can use one test job; larger repositories may split independent suites into separate jobs.

TeamCity On-Premises pipelines were introduced in version 2025.07. The current documentation notes that pipelines support a subset of built-in step types available in build configurations. A script step can run project commands as long as the required tools are installed on the agent. Choose a build configuration if you need a runner or customization that the pipeline UI does not offer, and check your TeamCity edition and version before following UI labels.

2. Connect the repository and define the test job

Create a TeamCity project and connect it to your repository using the first-build workflow.
Choose a pipeline or build configuration based on the runners and controls your project needs.
Add a test job and assign it to an agent pool or compatible agent requirement.
Add a script step that runs the existing Selenium test task.
Configure a VCS trigger for the branches that should run tests, and set branch filters if only selected branches should trigger the job.

For an established Java project, the script could invoke its Maven or Gradle test task. For other languages, use that repository’s test command. These are examples of the kind of command to invoke, not a claim that every Selenium project uses a particular tool.

# Example only: replace with the command used by your repository
./your-project-test-command

If your test task accepts a suite, browser, or environment argument, configure it through the project’s supported options or TeamCity parameters. Keep secrets such as test credentials in secured parameters rather than committing them to the repository.

3. Prepare a compatible build agent

TeamCity agents execute build steps and report progress, test data, and logs to the server. The agent must have the language runtime and dependencies required by the project, plus a compatible browser environment. Match operating system and architecture to the browser and driver you intend to run.

Install or provision the project’s runtime and dependency tooling.
Choose the browser used by the test suite and ensure its required system libraries are available.
Choose how the driver will be supplied: Selenium Manager, a preinstalled driver, or an explicit driver path.
Make sure the agent can reach the repository, dependency sources, and any browser or driver download endpoints needed at runtime.
Use agent requirements or pools so jobs land only on agents with the right operating system, architecture, and browser setup.

A local browser on each agent is the simplest arrangement when one browser and operating system are enough. For remote or Grid-based execution, compare setup effort, browser and OS coverage, version control, network and proxy requirements, available concurrency, and where logs and reports are collected. The appropriate choice depends on your coverage and infrastructure; the TeamCity and Selenium sources do not prescribe a universal agent image or hosted provider.

4. Set up Selenium browser and driver management

Selenium needs a language binding, a browser, and a driver implementation. Selenium Manager is bundled with Selenium releases starting at version 4.6 and can resolve and cache a missing driver. Selenium Manager can also manage browser downloads starting with Selenium 4.11.0.

The Selenium project describes Selenium Manager as “the official driver manager of the Selenium project, and it is shipped out of the box with every Selenium release.” Automatic setup still depends on the agent’s platform and access to browser-vendor endpoints. It may need proxy configuration or allowed downloads, and it should not be assumed to work offline or on every architecture.

For predictable builds, pick one strategy and document it:

Use Selenium Manager: keep Selenium current enough for the behavior you need, provide browser download access, and account for first-run downloads and caching.
Preinstall browser and driver: control versions through your agent image or provisioning process and ensure the driver path is available to the test process.
Use a remote browser endpoint: configure the project’s WebDriver client to connect to that endpoint, and make sure the TeamCity agent can reach it. Handle endpoint credentials as secured parameters.

Do not rely on a developer workstation’s browser state or driver installation. An agent is a separate machine or environment, and a build should be reproducible there.

5. Configure reports and failure diagnostics

TeamCity can display detailed test results for supported testing frameworks when the runner or test process reports results in a recognized way. Confirm this with a small build before relying on the overview page as the only record of outcomes.

Use a runner or test framework integration that TeamCity supports, or configure the project’s results format to be recognized by TeamCity.
Keep console output and relevant test logs available for failed runs.
Publish diagnostic artifacts your test setup produces, such as screenshots, browser logs, or test reports, using the artifact options appropriate to your configuration.
Check that a failing test marks the build as failed, and that a successful run is shown as passing.

Useful failure evidence includes the failing test name, exception and stack trace, browser and driver versions, agent identity, and any screenshot or browser log produced by the test framework. Avoid logging credentials, cookies, or other secrets.

6. Add triggers and scale the suite

A VCS trigger starts the configured build when changes arrive in selected branches. Keep the trigger scope aligned with how the team works: for example, run the relevant tests on active development branches and ensure the protected branch receives the validation your release process requires.

When a suite becomes slow, first identify whether time is spent preparing the agent, downloading dependencies, starting the browser, or running tests. Then consider splitting independent suites into dependent or parallel jobs. Parallel jobs need enough compatible agents and must not contend for shared test data or external accounts. More concurrency can shorten elapsed time while using more agent capacity.

7. Validate the pipeline with a small change

Start a build manually to catch agent and dependency problems before relying on a trigger.
Confirm the job runs on an agent with the intended OS, architecture, runtime, browser, and driver.
Check that Selenium can start a browser and reach the application under test.
Verify that TeamCity displays test results and marks a deliberately failing test as failed in a controlled branch or test run.
Push a small repository change and confirm the VCS trigger starts the intended build.
Review the build logs and retained artifacts to ensure a failure can be diagnosed without access to the agent’s interactive desktop.

8. Troubleshooting common failures

Symptom	Likely cause	Fix
Build cannot find the runtime or test command	The selected agent lacks the project’s runtime, dependencies, or expected working directory.	Install or provision the required tools on the agent, verify the checkout directory, and run the repository’s command in the same environment.
Driver executable cannot be found	No driver is installed or resolvable, or the configured path is wrong.	Use a supported Selenium Manager setup with required network access, or install a compatible driver and set the explicit path expected by the project.
Selenium Manager cannot download a driver or browser	The agent cannot reach the vendor endpoint, a proxy is missing, or the platform is unsupported.	Configure the required proxy and network access, or provision browser and driver through the agent image. Do not expect automatic downloads on an offline agent.
Browser starts locally but fails on the agent	The agent has a different OS, architecture, browser version, system libraries, or headless/display setup.	Match the agent environment to the test’s requirements and inspect browser startup logs. Configure the project’s supported headless or display behavior.
Tests pass but TeamCity shows no test results	The selected runner or framework output is not recognized or has not been connected to TeamCity reporting.	Use a supported integration or configure the test output/report format for TeamCity, then inspect the build’s test data.
Build is triggered for the wrong branches or not triggered	VCS trigger branch filters or repository connection settings do not match the intended branches.	Review the trigger and branch filters, then verify a new commit reaches the connected repository.
Parallel jobs fail intermittently	Jobs may share mutable test data, accounts, ports, or other resources.	Isolate test data and resources per job, or serialize the affected suite with job dependencies.
Build is slow on first run	Dependencies, browsers, or drivers may be downloading or initializing.	Measure the slow step in logs, cache dependencies where appropriate, or provision stable browser and driver versions on agents.

9. Performance, reliability, and cost considerations

Build duration depends on the repository, test suite, agent, browser, and network. There is no meaningful universal runtime for this setup. Measure queue time and step durations in your own TeamCity builds. Reuse prepared agents or provisioned images when setup downloads dominate, while keeping browser and driver versions controlled.

Reliability improves when each agent has a predictable environment and the pipeline captures enough output to explain failures. Selenium Manager reduces manual driver maintenance in supported conditions, but its downloads introduce a network dependency. A preinstalled browser and driver can make builds less dependent on runtime downloads, at the cost of maintaining the versions in the agent provisioning process.

TeamCity capacity and cost depend on your TeamCity deployment and agent resources; this guide does not assume a license, hosted service, or provider price. Parallel execution can reduce elapsed time when agents are available, but it increases concurrent resource use. Choose browser coverage and parallelism based on the checks your release process needs.

10. Capture screenshots of pages under test

For screenshots of your own application during Selenium tests, use the browser automation and screenshot facilities already available in your test framework, and retain the resulting files as build artifacts when they help diagnose failures. For a URL-to-image capture outside the test browser workflow, ScreenshotNeo is a website screenshot API and MCP server for developers. Its API can return PNG, JPEG, WebP, or PDF, and the request below demonstrates a WebP capture.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await require('node:fs/promises').writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

See the ScreenshotNeo API documentation for request options and response details. The API accepts one GET request with a URL and supports full-page or selector captures, viewport and device settings, dark mode, custom CSS and JavaScript, waits, request blocking, custom headers and cookies, geolocation, caching, asynchronous jobs, bulk capture, signed links, and more. Responses identify page verdict and billing status in headers.

Or skip the browser setup

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed; responses identify the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000 screenshots.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

Find request details in the ScreenshotNeo docs, visit ScreenshotNeo, and sign up for 1,000 free screenshots a month with no card.

FAQ

Can one TeamCity pipeline run Selenium tests in more than one language?

Yes. Use the command and dependencies for each repository or suite, and ensure the agent assigned to each job has the matching runtime and browser setup.

Should browser tests run on every commit?

That depends on suite duration and the team’s feedback needs. Configure VCS triggers and branch filters to match the branches where fast feedback matters, and reserve broader coverage for the stages where it is useful.

Does Selenium Manager remove the need to install a browser?

It can manage browser downloads starting with Selenium 4.11.0, subject to network, platform, and environment constraints. Verify the behavior for the exact agent environment you use.

Can I use TeamCity pipelines in older installations?

Pipelines were introduced in TeamCity On-Premises 2025.07. Check your installed version and available step types; build configurations remain an option when pipeline functionality does not cover the needed runner or customization.