Recommended Free Tools
Build the pipeline around your repository’s existing Selenium test command, and run it on a TeamCity agent that has the project’s runtime, dependencies, browser, and a compatible driver available. Choose a TeamCity pipeline for a straightforward workflow or a build configuration when you need runner features and customization that pipelines do not provide. Then configure the trigger and confirm that test results reach TeamCity.
Choose a TeamCity workflow
TeamCity’s On-Premises documentation is labeled 2026.2. Pipelines were introduced in TeamCity 2025.07, but their built-in step types are a subset of those available in build configurations. A script step can run your project’s commands if the required tools are installed on the agent.
As an Amazon Associate I earn from qualifying purchases.
| Use | When it fits | What to check |
|---|---|---|
| Pipeline | You want jobs and steps organized as a workflow, potentially with dependencies or parallel jobs. | Confirm that the pipeline supports the step types your test runner needs. TeamCity jobs can run on different agents. |
| Build configuration | You need the broader step selection or more advanced customization. | Choose the runner and settings that match your repository’s language and build system. |
There is no universal Selenium command or agent image: the right setup depends on the repository, test framework, operating system, and browser. Do not copy a Maven, Gradle, or other runner command until you have confirmed that your project uses it.
Prepare an agent that can run the tests
TeamCity build agents execute jobs and send progress, logs, and test data back to the server. Selenium tests therefore depend on the agent environment, not just on the TeamCity server configuration.
#1 Best Overall
- Runtime and dependencies: Make the project’s language runtime and dependency installation available to the agent. Use the same dependency and test setup your team uses locally or in another CI environment.
- Browser: Install or provision a browser compatible with the tests. Match the browser to the agent’s operating system and architecture.
- Driver: Ensure that a compatible WebDriver implementation is available, either through Selenium Manager or an explicit driver setup.
- Network access: Check whether the agent can reach the sites under test and any endpoints needed to download browser or driver components.
- Consistency: Keep agent images and browser versions predictable so a change in the build environment does not look like a product regression.
Selenium’s documentation describes Selenium Manager as “the official driver manager of the Selenium project” and says it is shipped with every Selenium release. Selenium Manager has been bundled with Selenium since version 4.6 and can resolve and cache a missing driver. Its browser-management capability begins with Selenium 4.11.0. Automatic provisioning is not guaranteed in every environment: vendor download endpoints, proxies, system libraries, and platform architecture can affect it. Restricted or offline agents may need preinstalled browser and driver versions or a manually specified driver path.
Connect the repository and add the test job
- Create a TeamCity project from your repository connection. Use the repository-connected first-build workflow, then select a pipeline or build configuration based on the runner support you need.
- Add a test job or build step. Use the runner your project already uses, or a script step that invokes the repository’s existing Selenium test task. The actual command is project-specific; verify it in the repository before adding it to TeamCity.
- Assign an appropriate agent. Ensure the job can be scheduled only on agents with the runtime, browser, driver strategy, and network access it requires.
- Set the trigger scope. Configure the repository trigger for the branches that should run Selenium tests. If the project has independent suites, separate jobs can make their dependencies and parallel execution explicit.
- Run a build and inspect its results. Confirm that the job starts on the intended agent, the browser launches, and the selected runner reports test outcomes in a format TeamCity recognizes.
TeamCity’s pipeline tutorial demonstrates build and test jobs, dependencies, and jobs that can use different agents. A single test job is a reasonable starting point; split work only when the suites can run independently and the extra configuration is useful to the team.
Rank #2
Make test results and failures useful
TeamCity provides detailed test results for supported frameworks when the configured runner reports them in a recognized way. A successful process exit alone may not give the same visibility as structured test reporting. Check a completed build’s overview and test results rather than assuming the framework output was imported.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →- Keep the build log and the test runner’s useful diagnostic output.
- Retain screenshots, browser logs, or other failure artifacts if your test setup already produces them.
- Make sure failures return a failing process status so TeamCity does not mark a failed suite as successful.
- When results are missing, verify the runner/framework reporting integration and test output format before changing the Selenium tests themselves.
Local browser or remote browser execution?
A browser installed on the build agent is a direct option for a small, controlled test environment. Remote or Grid-based execution may suit teams that need broader browser or operating-system coverage. The right choice depends on operational constraints rather than a universal performance advantage.
| Decision factor | Local agent browser | Remote or Grid-based browser |
|---|---|---|
| Setup | Install and maintain browser and driver requirements on eligible agents. | Configure access to the remote execution environment and make its browsers available to tests. |
| Browser and OS coverage | Limited to the combinations provisioned on your agents. | Can suit broader coverage, depending on the Grid or service you operate. |
| Version control | You control what is installed on each agent. | Depends on how the remote environment exposes and manages browser versions. |
| Network requirements | Agents need access to the application under test and, where applicable, browser/driver downloads. | Tests must reach the remote endpoint, and the remote browser must reach the application under test. |
| Concurrency and results | Bound by available agents and their capacity; TeamCity collects job logs and reported test data. | Bound by available remote browser capacity as well as agent and job scheduling; collect useful diagnostics in the test job. |
Troubleshoot common failures
Build agent cannot find a runtime or dependency
Cause: The agent does not have the runtime, dependency setup, or environment configuration expected by the repository’s test task. Fix: Install or provision the required tools on eligible agents and verify the test task there using the same setup the CI job invokes.
WebDriver cannot start the browser
Cause: The browser is missing, incompatible with the driver, unavailable to the agent’s user, or unable to start because of platform or system-library requirements. Fix: Check the browser and driver versions, OS and architecture, agent permissions, and required system libraries. If automatic driver resolution is unreliable, provision a compatible browser and driver explicitly.
Selenium Manager cannot download a browser or driver
Cause: The agent cannot reach the vendor endpoint, proxy configuration is missing, or the platform is not supported by the expected download. Fix: Check outbound access and proxy settings; where network policy prevents downloads, preinstall the required components and configure the project to use them.
Tests pass locally but fail on the agent
Cause: The local and CI environments differ in browser version, OS, architecture, permissions, network access, or available system libraries. Fix: Compare those conditions and make agent provisioning repeatable. Use build logs and browser diagnostics to identify where startup or navigation fails.
TeamCity shows no detailed test results
Cause: The selected runner or framework is not reporting in a format TeamCity recognizes, or the chosen step is not configured to publish those results. Fix: Check the framework’s TeamCity reporting support and configure the matching runner or reporting integration; inspect the build output to see whether test results were produced.
A pipeline does not offer the needed runner step
Cause: Pipeline step support is narrower than the build-configuration step selection. Fix: Use a script step if the needed tools are installed on the agent and the project command can run that way, or choose a build configuration for the required runner or customization.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Or skip the browser setup
For a screenshot artifact in a build, ScreenshotNeo can capture a page without you provisioning a browser on the TeamCity agent. It is a screenshot API, not a replacement for Selenium assertions or interactive browser tests. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.
One GET request returns a screenshot; the API can also return a PDF. See the ScreenshotNeo API documentation for configuration and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo bills only clean shots: bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and each response includes page-verdict and billing headers. Sign up for 1,000 free screenshots a month with no card.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
