How to Run Automated Tests with Google Cloud Build

To run automated tests with Google Cloud Build, add a build step to cloudbuild.yaml that invokes your project’s test command in a container with the right runtime and dependencies. Put that step before packaging, publishing, or deployment steps so a failed test stops the build before those actions. Submit the build manually while setting it up, then create a repository trigger to run it on changes.

Cloud Build executes build configurations written in YAML or JSON as a series of containerized steps. The test command is yours to choose: for example, python -m pytest, npm test, or go test. See Google Cloud’s Cloud Build overview and basic build configuration guide.

1. Add a test step to cloudbuild.yaml

Create cloudbuild.yaml in the project root. Select an image that includes the runtime and tools your test command needs. This minimal Python example runs pytest:

steps:
  - name: 'python:3.12'
    entrypoint: 'python'
    args: ['-m', 'pytest']

Use a runtime image and version that match your project. A floating tag such as latest can change over time; pinning a version makes the environment more predictable. If the image does not include project dependencies, add a dependency-install step before tests or use an image that already has them. The exact setup depends on your project.

Build steps run serially by default, in the order listed. Keep tests ahead of packaging, publishing, or deployment steps when tests are a release gate. A nonzero test command should fail its step and the build. Avoid wrappers or shell pipelines that discard the test process’s exit status.

2. Choose the test command for your project

These examples show the test command in context. Adapt the image tag, dependency installation, and command to your repository’s runtime and tooling. The Node.js example assumes a test script is defined in package.json.

Python with pytest

steps:
  - name: 'python:3.12'
    entrypoint: 'python'
    args: ['-m', 'pytest']

If your tests require dependencies that are not in the image, add an installation step or use a project image with the dependencies installed. For example, the command could install from a checked-in requirements file before running pytest; make sure the chosen image includes the package installer and that the dependency files are available in the build context.

Node.js with npm

steps:
  - name: 'node:22'
    entrypoint: 'npm'
    args: ['install']
  - name: 'node:22'
    entrypoint: 'npm'
    args: ['test']

Use the dependency installation command appropriate for your project and lockfile. The important parts are that dependencies are available to the test step and the script exits unsuccessfully when tests fail.

Go

steps:
  - name: 'golang:1.23'
    entrypoint: 'go'
    args: ['test', './...']

Google’s Go example runs go test and can convert verbose output to JUnit XML with go-junit-report. If you add a formatter in a shell pipeline, configure it to preserve a failing test exit status; the official example uses -set-exit-code for this purpose. See Google’s Cloud Build Go testing example.

3. Optionally create and store a JUnit report

JUnit XML can make test results portable as a file artifact. It is optional: generating a report and storing it are separate steps. The build log remains available for inspecting command output.

For pytest, add the report argument and declare the output under artifacts.objects:

steps:
  - name: 'python:3.12'
    entrypoint: 'python'
    args: ['-m', 'pytest', '--junitxml=${SHORT_SHA}_test_log.xml']

artifacts:
  objects:
    location: 'gs://${_BUCKET_NAME}/'
    paths:
      - '${SHORT_SHA}_test_log.xml'

Before relying on this configuration, create the destination bucket and grant the build service account permission to write objects there. Google’s Python testing guide documents the bucket and Storage Object Creator role in its prerequisites. Confirm the service account used by your build has the required access.

For Go, the same separation applies: configure the test/formatter command to write an XML file, then list that file in the artifact paths. Merely generating XML does not upload it. If you only need to diagnose a test run, start with the build logs and skip artifact storage.

4. Run a build manually

From the repository directory, submit a build with the Google Cloud CLI:

gcloud builds submit --config=cloudbuild.yaml .

This submits the current source directory and runs the configuration. Check the build result and logs in Cloud Build History or with the CLI/API. See the manual build guide for current command details.

If your configuration uses a custom substitution such as ${_BUCKET_NAME}, pass its value when submitting:

gcloud builds submit \
  --config=cloudbuild.yaml \
  --substitutions=_BUCKET_NAME=my-test-reports \
  .

Built-in substitutions such as $PROJECT_ID and $SHORT_SHA provide build-specific values. Define user substitutions for values that vary by environment, such as a bucket name. Substitutions are configuration values; do not treat them as a secret store. See Google’s substitution reference.

5. Run tests from a repository trigger

After a manual build works, create a Cloud Build trigger connected to your repository. Select the repository event and branch pattern that should start the build, and point the trigger at cloudbuild.yaml. Trigger settings can also supply custom substitutions. Google’s trigger guide covers the current setup flow; its quickstart demonstrates a push-to-branch trigger.

Connect or select the repository in Cloud Build.
Create a trigger for the desired event, such as a push to a branch.
Choose the configuration file path, for example cloudbuild.yaml at the repository root.
Set any trigger substitutions the configuration needs, such as _BUCKET_NAME.
Push a change and inspect the resulting build in Cloud Build History.

Manual builds are useful for initial setup and ad hoc runs. Triggers automate execution after repository events. In either case, the build configuration determines the test command and step order.

6. Troubleshoot failed test builds

Symptom	Likely cause	What to check
The test command or runtime is not found	The selected image lacks the runtime or executable, or the entrypoint is wrong.	Choose an image with the required runtime and tooling; verify the command and arguments.
Imports or packages are missing	Dependencies were not installed or are unavailable to the test step.	Add the project’s dependency setup before tests, or use a suitable project image.
Tests pass locally but fail in the build	The build environment, working files, dependency versions, or configuration may differ.	Read the step’s build log; check the image version, dependency setup, paths, and required environment values.
The build succeeds even though tests fail	A shell wrapper or pipeline may have hidden the test command’s nonzero exit status.	Run the test command directly or explicitly propagate its exit status. For the Go formatter pattern, use the documented `-set-exit-code` option.
No JUnit file appears in Cloud Storage	The test command did not create the file, the artifact path does not match, or storage upload is not configured.	Check the test output path and `artifacts.objects.paths`; declare the storage location and confirm the bucket exists.
Artifact upload is denied	The build service account lacks permission to write to the bucket.	Check which service account the build uses and grant the needed bucket permissions, following the current Cloud Build guide.
A trigger does not start the expected build	The event, branch pattern, or configuration path may not match the change.	Review the trigger’s repository, event, branch, and build config settings, then inspect Cloud Build History.

These are configuration checks inferred from the documented build, test, and artifact setup. Build details and logs are the starting point for identifying the failing command or upload step.

7. Performance, reliability, and cost considerations

Keep setup intentional: install only what tests need and use a runtime image appropriate to the project. Dependency setup and test execution are separate build steps when configured that way.
Make runs reproducible: choose explicit runtime image versions and use the project’s normal dependency process. Floating image tags can change, which can change the test environment.
Preserve failure signals: keep tests before downstream release steps and ensure wrappers pass through a failing test exit status.
Store only useful reports: JUnit XML requires both report generation and a configured artifact destination with appropriate permissions. If logs are enough for your workflow, omit the upload configuration.
Check current pricing and quotas: this guide’s sources establish how to configure and run builds, not a price or runtime guarantee. Consult the current Cloud Build pricing and quota documentation for your project and region.

Or skip the browser setup

If your test pipeline also needs website screenshots—for visual checks, documentation, or test fixtures—you can call ScreenshotNeo with one HTTP GET request. See the ScreenshotNeo API documentation.

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

Cookie and consent 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 cost nothing; response headers identify the page verdict and billing status. An MCP server provides screenshot tools for AI agents. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.

FAQ

Does Cloud Build require JUnit XML?

No. It is an optional report format. You can run tests and inspect their build logs without creating or uploading a report.

Can I run more than one kind of test?

Yes. Add the commands your project needs as build steps, in the order they should run. Keep release actions after the checks that must pass first.

Where do I see whether a triggered build passed?

Open the build in Cloud Build History to review its status, steps, and logs.