How to Integrate Automated Tests with Bitbucket

To run automated tests with Bitbucket Cloud, add a bitbucket-pipelines.yml file at the repository root, choose a build image with your test runtime, and run your existing test command in a pipeline step. To see test outcomes in Bitbucket, configure the test runner to write JUnit-style XML and make sure the report lands in a supported location or is declared as a test-report artifact. Atlassian’s Pipelines getting-started guide explains the pipeline structure. Its test-reporting documentation covers report formats and paths.

1. Confirm the project command and CI environment

This guide covers Bitbucket Cloud and Bitbucket Pipelines. Start with the command developers already use locally or in another CI system. The YAML configuration describes the pipeline; each step runs its scripts inside the configured build container.

Identify the runtime and version your tests require.
List dependencies and external services needed by the tests.
Find the existing test command, such as npm test or pytest.
Decide whether tests need to emit JUnit XML for Bitbucket’s test view.

A single image is easiest to maintain. If you need to validate several runtime or dependency versions, use separate steps with appropriate images. Atlassian documents this pattern for cross-platform testing.

2. Add a pipeline that runs the tests

Create bitbucket-pipelines.yml in the repository root. This schematic Node.js example installs locked dependencies and runs the project test script. Replace the image and commands to match the repository; it does not produce a test report unless the test command is configured to do so.

image: node:latest

pipelines:
  default:
    - step:
        name: Test
        script:
          - npm ci
          - npm test

Commit the file and enable Pipelines for the repository if it is not already enabled. A push that matches the configured pipeline starts a run. Consult the Bitbucket Pipelines YAML configuration reference for trigger and step configuration details.

Separate work into steps when it helps

For a small project, one step can install dependencies and run all tests. Larger projects often benefit from separate build, unit-test, integration-test, and lint steps because each has a clearer log and failure boundary. Independent work can run in parallel when shared resources and the pipeline’s runtime and resource constraints permit it. Keep dependent work sequential.

3. Generate test results Bitbucket can display

A passing or failing pipeline tells you whether a command returned success, but Bitbucket’s built-in test reporting needs compatible XML output. Configure the test runner to write JUnit-style XML (including Maven Surefire XML where applicable). Examples in Atlassian’s getting-started material include PHPUnit’s --log-junit, pytest’s --junit-xml, Jest with jest-junit, and JUnit reporters for Playwright or Cypress. The exact package and configuration can vary by framework version; use that framework’s current documentation.

For example, a pytest step can ask pytest to produce an XML report:

image: python:3.12

pipelines:
  default:
    - step:
        name: Python tests
        script:
          - pip install -r requirements.txt
          - pytest --junit-xml=test-results/pytest.xml

The report path must exist after the test command runs. If your runner writes elsewhere, either change its output path or configure the artifact path to match.

4. Make report paths discoverable

Pipelines searches documented default locations for supported XML reports. These include patterns such as ./**/surefire-reports/**/*.xml, ./**/failsafe-reports/**/*.xml, ./**/test-results/**/*.xml, ./**/test-reports/**/*.xml, and ./**/TestResults/**/*.xml, subject to a directory-depth limit. Check the current reporting documentation if a deeply nested report is not detected.

For a custom location, declare test-report artifacts. For the pytest example above:

image: python:3.12

pipelines:
  default:
    - step:
        name: Python tests
        script:
          - pip install -r requirements.txt
          - pytest --junit-xml=test-results/pytest.xml
        artifacts:
          - name: Test reports
            type: test-reports
            paths:
              - test-results/*.xml

Use the documented test-report artifact configuration when your XML output does not match a default discovery location. Test reports serve Bitbucket’s test-results view; other artifacts can preserve useful failure evidence such as screenshots, videos, and logs. Check Atlassian’s current artifact documentation for scope and retention behavior.

5. Verify a pipeline run

Open the repository’s Pipelines view and confirm a run was triggered by the expected branch or event.
Open the step log and check that dependency setup and the test command completed.
Confirm the runner created XML at the configured path, including when tests fail.
Open the run’s test results and check that failures and useful details are visible.
For a failing test, inspect the report and retain any extra logs or screenshots needed to reproduce the issue.

Common configurations and choices

Need	Approach
One runtime	Use one build image and run the test suite in a step.
Several runtime versions	Use separate steps with the relevant images, following Atlassian’s cross-platform testing pattern.
Fast independent suites	Split suites into parallel steps if they do not depend on shared mutable state.
Bitbucket test view	Emit supported JUnit-style or Maven Surefire XML and use a recognized path or test-report artifact.
Failure evidence	Keep screenshots, videos, and logs as artifacts when useful, and confirm retention behavior in current docs.

For richer pull-request reporting, Atlassian documents Code Insights for surfacing reports and metrics. Atlassian also describes Bitbucket Tests as an open beta with summaries, flaky-test detection, and quarantine controls, with availability limited in the reviewed documentation to Standard and Premium customers. Feature status and plan eligibility can change, so verify them in current Atlassian documentation before relying on them. For hosted browser and device testing, Atlassian’s integrations page lists Sauce Labs; check the current service details for fit.

Troubleshooting

Symptom	Likely cause	Fix
No pipeline run appears	Pipelines is not enabled, the YAML is missing or invalid, or no configured trigger matches the push.	Enable Pipelines, confirm `bitbucket-pipelines.yml` is at the repository root, inspect the YAML and check the configured pipeline trigger.
Tests do not start	The image lacks the required runtime, dependencies were not installed, or the script uses the wrong working assumptions.	Select a compatible image and add the project’s dependency and service setup before the test command.
The step fails but no test details appear	The runner did not create supported XML, or it wrote the report outside a recognized location.	Enable the runner’s JUnit output and align the report path with a documented default or an explicit `type: test-reports` artifact.
Report artifact is empty or missing	The glob does not match the actual output, the directory is nested differently, or the test command stopped before writing XML.	Check the step log and report directory, then correct the runner output option or artifact glob. Ensure the report is generated on failing runs too.
Tests pass locally but fail in Pipelines	The container environment differs: runtime version, environment variables, services, filesystem assumptions, or network dependencies may differ.	Match the local runtime where practical, declare required services and variables, and make setup explicit in the step.
Parallel tests interfere	Steps or test workers share mutable state, a database, or external resources.	Isolate data and resources per worker or run the dependent tests sequentially.

Performance, reliability, and cost

Pipeline time is often spent installing dependencies and waiting for external services as well as executing tests. Use the project’s lockfile-based install command where available, split suites when it improves diagnosis, and parallelize only work that is safe to run concurrently. Keep external service setup deterministic and make required configuration explicit.

Reliable reporting depends on producing the XML even when tests fail, placing it where Pipelines can collect it, and preserving diagnostic artifacts when needed. A green step alone does not prove that a test report was discovered; verify the result view after configuration changes.

Pipeline usage and plan limits depend on the current Bitbucket plan and account configuration. The research material does not establish a fixed cost for this setup, so check Atlassian’s current plan and billing information for the repository rather than assuming a price.

Or skip the browser setup

If your automated workflow also needs website screenshots, ScreenshotNeo is a website screenshot API and MCP server. It is separate from Bitbucket’s test runner: keep your tests in Pipelines, and call the API when a test or workflow needs a page image or PDF. The API documentation describes request options.

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

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

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners are accepted and removed before capture, along with supported newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers report the page verdict and billing status. An MCP server provides take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

FAQ

Does Bitbucket run the tests itself?

The pipeline step runs the project’s test command inside its build environment. The test framework executes the tests; Pipelines orchestrates the step and can display compatible report output.

Do I need XML if the pipeline already fails on a test?

No XML is needed for a command’s exit status to fail the step. Compatible XML is needed for Bitbucket’s built-in test reporting view.

Can I use this YAML for Bitbucket Data Center?

This guide is for Bitbucket Cloud Pipelines. Data Center has a different deployment and CI setup; do not assume this configuration applies.

Can browser tests attach screenshots?

Yes, configure the framework to save screenshots or videos and retain those files as artifacts. The exact reporter and output settings depend on the framework.