How to Run Automated Tests in Cloud Build

What automated testing in Cloud Build actually means

In Cloud Build, automated testing is just a pipeline step that runs your test suite inside a container. There is no special “test mode.” A test step is a normal build step that happens to run pytest, Jest, or whatever your stack uses. What makes it a quality gate is the exit code: if tests fail, the container exits with code 1 and Cloud Build halts the entire pipeline at that point.

You do not need to configure Cloud Build to understand what a test is. You just need your test runner to exit with a non-zero code on failure, which every mainstream test framework does by default.

Because every step runs in its own container, you get a clean, reproducible environment on every build. There is no state left over from a previous run. The same test that passes on your laptop will pass in Cloud Build — and the same one that fails locally will fail there too, assuming you use the same container image and dependencies.

How automated testing works in Cloud Build

Understanding the execution model helps you structure test pipelines that are both reliable and efficient.

Every step is a container

When Cloud Build runs a step, it pulls the container image you specify and executes the command inside it. For test steps, you typically use a public language image such as python:3.11, node:20, or golang:1.22, rather than one of the Google-maintained builders. The container has no memory of previous steps and no packages pre-installed beyond what the base image includes.

The /workspace directory is shared

All steps share one directory: /workspace. Your source code is checked out there before the first step runs. Dependencies installed to a path under /workspace in one step are available in the next. This is how multi-step pipelines work: install in step one, test in step two, build in step three.

A non-zero exit code stops everything

If any step’s container exits with a non-zero code, Cloud Build marks that step as failed and stops the pipeline. Subsequent steps do not run. This is the fail-fast behaviour you want from a CI system.

Steps can run sequentially or in parallel

By default, steps run one after another. Use the waitFor field to declare dependencies between steps. Two steps that both depend on the same completed step will start simultaneously. This lets you run unit tests and lint in parallel, cutting pipeline time without adding complexity. See Cloud Build Overview for a full explanation of how waitFor and step IDs work.

When to add automated tests to Cloud Build

Test steps are worth adding whenever the cost of a broken deployment is higher than the cost of running tests. In practice, that means almost always. Some specific situations where it pays off immediately:

• Validating pull requests: Run tests on every PR before merge. Prevent broken code from reaching your main branch before anyone reviews it.
• Before building a Docker image: Image builds take time. Catching failures before the build step saves minutes per failed run, which adds up across a team.
• Lint plus unit tests before deploy: Combining a lint step with unit tests in parallel before the Docker build is a common pattern for Cloud Run CI/CD pipelines.
• Checking helper scripts and infrastructure code: If your team writes Python or bash scripts that support your infrastructure, test steps can validate those too, not just application code.
• Separating fast tests from slow integration tests: Run unit tests on every push. Reserve slower integration tests for merges to main or release branches where the extra time is justified.

Tests belong before the Docker build

Without automated tests in CI, developers rely on manual testing, which is slow, inconsistent, and does not scale. But the order of steps matters as much as having them at all.

A pipeline that builds a Docker image first and then runs tests has the sequence backwards. Building an image for a typical Python or Node.js application takes two to four minutes. If your tests are going to fail, you want that failure before you burn that time. Multiply a wasted three-minute build across dozens of commits per week from a small team and you are looking at meaningful lost time.

The principle is straightforward: fail at the cheapest possible step. Tests come before the image build. The image build comes before pushing to Artifact Registry. The push comes before deployment. Each step gates the next.

Running unit tests in Cloud Build

The pattern is the same for any language: one step installs dependencies, the next step runs tests. Both steps use the same container image. Files written to /workspace during install are available during the test step.

For a Python project using pytest:

steps:
  - name: 'python:3.11'
    entrypoint: pip
    args: ['install', '-r', 'requirements.txt', '--target', '/workspace/.deps']
    id: install-deps

  - name: 'python:3.11'
    entrypoint: python
    args: ['-m', 'pytest', 'tests/', '-v', '--tb=short']
    env:
      - 'PYTHONPATH=/workspace/.deps'
    waitFor: ['install-deps']
    id: run-tests

The —target /workspace/.deps flag installs packages into a directory under /workspace, making them available to the test step. The -v and —tb=short flags give you enough detail in the build log to understand what failed without pages of noise.

For a Node.js project using Jest or Vitest:

steps:
  - name: 'node:20'
    entrypoint: npm
    args: ['ci']
    id: install-deps

  - name: 'node:20'
    entrypoint: npm
    args: ['test', '--', '--ci', '--forceExit']
    waitFor: ['install-deps']
    id: run-tests

If tests fail, Cloud Build marks the run-tests step as failed. The build stops there. The Docker image never builds and nothing gets deployed.

Running test and lint steps in parallel with waitFor

By default, steps run sequentially. Once the dependency install step is done, there is no reason to run unit tests and lint one after another: neither depends on the other. Use waitFor to express that both steps depend on install, and Cloud Build will start them simultaneously.

steps:
  - name: 'python:3.11'
    entrypoint: pip
    args: ['install', '-r', 'requirements.txt', '--target', '/workspace/.deps']
    id: install-deps

  # unit-tests and lint both depend only on install-deps — they run in parallel
  - name: 'python:3.11'
    entrypoint: python
    args: ['-m', 'pytest', 'tests/unit/', '-v', '--tb=short']
    env:
      - 'PYTHONPATH=/workspace/.deps'
    waitFor: ['install-deps']
    id: unit-tests

  - name: 'python:3.11'
    entrypoint: python
    args: ['-m', 'flake8', 'src/']
    env:
      - 'PYTHONPATH=/workspace/.deps'
    waitFor: ['install-deps']
    id: lint

  # Docker image builds only after both unit tests and lint pass
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t', 'europe-west2-docker.pkg.dev/$PROJECT_ID/api/api:$SHORT_SHA', '.']
    waitFor: ['unit-tests', 'lint']
    id: build-image

The build-image step lists both unit-tests and lint in its waitFor. It will not start until both have succeeded. If either fails, the build halts and the image never builds.

On a pipeline that previously ran tests and lint sequentially, parallelising them typically cuts 30 to 50 percent off the combined check time. Faster pipelines mean faster feedback, which means less context-switching while developers wait for CI results.

Integration tests

Unit tests exercise code in isolation. Integration tests exercise code in combination with external dependencies: a database, a queue, an external API. They catch a different class of bugs and are slower to run, which is why they usually run separately from unit tests.

When integration tests are worth it: If your application talks to Cloud SQL and you want to verify that queries execute correctly against a real schema, integration tests give you that confidence. Unit tests with a mocked database do not.

For tests against a Cloud SQL instance in a dedicated test project, run the Cloud SQL Auth Proxy as a background process within the step:

steps:
  - name: 'python:3.11'
    entrypoint: bash
    args:
      - -c
      - |
        pip install -r requirements.txt --target /workspace/.deps
        # Start the Cloud SQL Auth Proxy in the background
        ./cloud-sql-proxy my-test-project:europe-west2:test-db &
        sleep 2
        # Run integration tests against the proxy on localhost
        PYTHONPATH=/workspace/.deps python -m pytest tests/integration/ -v --tb=short
    secretEnv: ['DATABASE_PASSWORD']
    id: integration-tests
availableSecrets:
  secretManager:
    - versionName: projects/$PROJECT_ID/secrets/test-db-password/versions/latest
      env: DATABASE_PASSWORD

The database password comes from Secret Manager via availableSecrets, not from a hardcoded value in the config file. See Secrets in CI/CD Pipelines for the full pattern. Build configs are committed to version control, so credentials must never appear in them.

If your integration tests are slow, consider running them on a separate trigger, for example only on pushes to main rather than on every branch push or pull request. Fast unit tests on every commit, slower integration tests on merges. See Managing Environments in CI/CD for how to structure triggers around different environments.

Caching dependencies between builds

Cloud Build starts completely clean on every run. There is no persistent disk between builds. The upside is isolation and reproducibility. The downside is that you reinstall dependencies from scratch every time, which can add 30 to 90 seconds to builds that install large dependency trees.

The standard workaround is to store installed packages in a GCS bucket and restore them at the start of each build. This is not a true build cache. It is a manual restore-and-save pattern, but it works well for package managers that support a cache directory flag.

steps:
  # Try to restore cached packages — allowFailure so the build continues on a cold start
  - name: 'gcr.io/cloud-builders/gsutil'
    args: ['cp', 'gs://my-app-build-cache/pip-cache.tar.gz', '/workspace/pip-cache.tar.gz']
    allowFailure: true
    id: restore-cache

  - name: 'python:3.11'
    entrypoint: bash
    args:
      - -c
      - |
        if [ -f /workspace/pip-cache.tar.gz ]; then
          tar xzf /workspace/pip-cache.tar.gz -C /workspace
        fi
        pip install -r requirements.txt --target /workspace/.deps --cache-dir /workspace/.pip-cache
    waitFor: ['restore-cache']
    id: install-deps

  # Save the updated cache for the next build
  - name: 'gcr.io/cloud-builders/gsutil'
    entrypoint: bash
    args:
      - -c
      - |
        tar czf /workspace/pip-cache.tar.gz /workspace/.pip-cache
        gsutil cp /workspace/pip-cache.tar.gz gs://my-app-build-cache/pip-cache.tar.gz
    waitFor: ['install-deps']
    allowFailure: true
    id: save-cache

allowFailure: true on the restore step is intentional: there is no cache on the first run, so the gsutil cp command will fail. The build should continue regardless. The same flag on the save step means a cache write failure does not block the actual pipeline work.

An alternative to GCS caching is to bake your dependencies into a custom builder image. Push a Docker image with all packages pre-installed to Artifact Registry, then use that image as your step’s name. This is more work to set up but more predictable than the restore-from-GCS pattern.

Coverage thresholds, flaky tests, and test artifacts

Coverage thresholds

A coverage threshold enforces a minimum percentage of code covered by tests. The mechanism is simple: run your coverage tool, check the output, and exit with code 1 if coverage falls below the threshold. Cloud Build treats that exit code as a failure and stops the pipeline.

  - name: 'node:20-alpine'
    script: |
      npm run test:coverage
      node -e "
        const c = require('./coverage/coverage-summary.json');
        const pct = c.total.lines.pct;
        if (pct < 80) {
          console.error('Coverage ' + pct + '% is below the 80% threshold');
          process.exit(1);
        }
        console.log('Coverage OK: ' + pct + '%');
      "
    id: test-coverage

Flaky tests

Flaky tests pass sometimes and fail sometimes, usually due to timing issues, test isolation problems, or external dependencies that behave inconsistently. Do not use allowFailure: true broadly to hide them. This masks real failures and erodes confidence in the pipeline. Instead, quarantine known flaky tests in a separate suite that runs but does not block the build. Track them as technical debt and fix them. A pipeline that nobody trusts is worse than no pipeline.

Saving test results as artifacts

Save test result files so you can inspect them after a build fails without having to re-run it:

artifacts:
  objects:
    location: 'gs://my-app-build-artifacts/$BUILD_ID/'
    paths:
      - 'test-results/*.xml'
      - 'coverage/lcov.info'

JUnit XML files can be parsed by many reporting tools. Having them stored against the build ID makes it straightforward to trace failures back to specific test runs.

Unit tests vs integration tests in Cloud Build

These are not competing approaches. They cover different things and belong at different points in the pipeline.

A mature pipeline runs unit tests first on every push, fails fast if they break, then runs integration tests on a separate trigger or after the unit tests pass on main. This keeps PR feedback fast while still catching integration-level problems before they reach production. See Dev vs Staging vs Production for how environment separation reinforces this pattern.