To run Selenium tests in Bitbucket Pipelines, add a step to the repository-root bitbucket-pipelines.yml, install your project’s dependencies, and run its test command. Configure the Selenium client to use RemoteWebDriver with a Grid URL that the pipeline step can actually reach. Then configure your test framework—not Selenium—to generate report files that Bitbucket can display.
Choose where Selenium Grid will run
Before writing the pipeline, decide how the build step will reach the Grid. A URL that works on your laptop may not work inside a Pipelines build container: localhost refers to the current container, not automatically to a separate service, host, or remote Grid.
As an Amazon Associate I earn from qualifying purchases.
- Existing Grid: Point the build at a Grid hosted on a network reachable from the runner. Restrict access to trusted clients.
- Grid provisioned for a step: Configure service networking, startup readiness, and teardown for the runner and runtime you use. The official documentation reviewed here does not provide a complete Bitbucket-specific Grid service-container recipe, so validate those details in your environment rather than assuming a generic configuration will work.
- Managed browser testing: Consider a hosted service if you do not want to operate Grid infrastructure. Atlassian’s third-party integration guide describes BrowserStack as supporting Selenium testing: Atlassian’s third-party integrations guide.
Also choose a Grid topology. Selenium documents Standalone, Hub-and-Node, and fully distributed deployments. Connect to the server URL for Standalone, the Hub for Hub-and-Node, or the Router for a distributed Grid. The appropriate topology depends on your browser coverage, parallel-session needs, network isolation, and observed stability—not a universal sizing formula.
Grid’s documented default address is http://localhost:4444, but that is useful only when the client and Grid share the relevant network namespace. For a remote or separate-container Grid, use its reachable address. See Selenium Grid: Getting started and Selenium Remote WebDriver.
#1 Best Overall
Configure the Bitbucket pipeline step
Bitbucket reads bitbucket-pipelines.yml from the repository root. Choose a build image containing the runtime your project needs, pin image and dependency versions for repeatability, and set the Grid address as a pipeline variable or other project-appropriate configuration.
image: maven:3.9-eclipse-temurin-17
pipelines:
default:
- step:
name: Selenium integration tests
script:
- mvn test
artifacts:
- target/surefire-reports/**This is a starting shape, not a complete Grid deployment recipe. It assumes the Grid is already reachable at the URL supplied to the tests. Replace the image, install or build commands, test command, report path, and Grid URL to match your project. If the step needs Docker commands, Bitbucket documents enabling Docker as a step service; check the documentation for your runner and runtime before relying on specific Docker flags.
Rank #2
See Configure your pipeline, Use Docker in a pipeline, and Use Docker images as build environments.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchesPoint Java tests at the remote Grid
Create browser options, read the Grid URL from the environment, and pass both to RemoteWebDriver. Always close the session, including when a test fails.
import java.net.URL;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
URL gridUrl = new URL(System.getenv("SELENIUM_REMOTE_URL"));
ChromeOptions options = new ChromeOptions();
WebDriver driver = new RemoteWebDriver(gridUrl, options);
try {
// Invoke the project test flow.
} finally {
driver.quit();
}Set SELENIUM_REMOTE_URL to the actual Grid endpoint reachable from the pipeline. It is an application-specific environment-variable convention, not a special Bitbucket or Selenium setting. Selenium’s documented Java pattern likewise supplies a server URL and browser options to the remote driver: Remote WebDriver documentation.
Generate and publish test reports
Selenium drives browsers; it does not run your test framework or create test reports. Configure JUnit, TestNG, or another supported framework and build tool to emit a compatible report, then make the pipeline step collect the correct output path. The example’s Surefire artifact path is Maven-specific; another framework or build tool may use a different path and report setup.
Bitbucket’s reporting instructions explain how to configure supported test-result files for display: Test reporting in Pipelines. Confirm the report exists at the configured path after the test command, especially when a failed test causes the build to exit before later commands run.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchSecure and size the Grid for the workload
Do not expose an unprotected Grid to untrusted external traffic. Selenium warns that a publicly reachable Grid can expose infrastructure, internal applications, and files, and can allow binary execution. Restrict network access and follow the security guidance for your deployment: Selenium Grid: Getting started.
There is no universally correct number of Grid nodes or sessions. Start with the browser/platform coverage and concurrency your suite needs, then validate capacity and stability in the target environment. Selenium’s sizing guidance is a rough starting point, not a guarantee for a particular pipeline workload.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot common integration failures
Connection refused or a timeout
- Likely cause: The Grid is not running or ready, the port is unavailable, a firewall blocks traffic, or the test uses
localhostfrom the wrong container. - Fix: Check the endpoint from the build step’s network context, verify the Grid has completed startup, and use the hostname and port reachable from that step. Add readiness handling when provisioning Grid alongside the build.
Could not start a new session
- Likely cause: The requested browser or capabilities do not match what the Grid can provide, or available session capacity is exhausted.
- Fix: Compare the browser options in the test with the Grid’s available browser configuration, and check active workload and configured capacity before increasing parallelism.
Tests pass locally but fail in Pipelines
- Likely cause: The build image, runtime, dependencies, environment variables, or network access differ from the local setup.
- Fix: Pin the build image and dependencies, confirm the remote URL is present in the step, and verify that the runner can reach the Grid and the applications under test.
No test results appear in Bitbucket
- Likely cause: The test framework did not generate a supported report, the configured artifact/report path is wrong, or the build stopped before writing the report.
- Fix: Run the framework’s report configuration, inspect the output directory in the step, and align the Bitbucket reporting setup with the actual file format and path.
Or skip the browser setup
If the job is to capture website screenshots rather than exercise browser interactions as a test suite, ScreenshotNeo is a website screenshot API and MCP server. One GET request returns a PNG, JPEG, WebP, or PDF. For example, using cURL:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo accepts cookie or consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server gives AI agents tools for screenshots, page information, and PDF capture. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for 1,000 free screenshots a month—no card required.
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.
