Add Integration Tests to Deployment Jobs

You’ve automated your builds, your unit tests are green, and your deployment job runs like clockwork. But when your latest release reaches staging, the database schema is wrong, the API can’t reach the message queue, and the frontend can’t talk to the backend. Unit tests never caught it, because they don’t test the integration — the way your services actually connect and behave together. That’s the gap this lesson closes: adding integration tests to your deployment jobs so you catch real-world failures before they hit production, not after.

The problem this lesson solves

Unit tests check a single function, class, or module in isolation — but they don’t verify that your application works as a whole. When you deploy, you’re wiring together services, databases, caches, queues, and third-party APIs. If any of those connections break, the whole deployment fails.

Integration tests exercise those connections. By adding them to your deployment job, you validate that your freshly built artifact actually works with the infrastructure it needs. The pain points this solves:

• Happy-path deployments that break in production: Your code works on your laptop because you have different versions of dependencies or services.
• Schema mismatches: Your migration ran, but the application expects a column that doesn’t exist yet.
• Networking issues: Your service can’t reach the database because credentials or endpoints changed.
• Missing configuration: Environment variables, secrets, or feature flags that aren’t set correctly in the deployment environment.

Without integration tests, you’re in a poker game where you only see the cards after the money’s already bet. With them, you fold before production sees the mess.

Core concept / mental model

Think of your deployment pipeline like a plane’s pre-flight checklist. You don’t just check the engines fire individually — you test that the fuel system, hydraulics, and avionics work together. Integration tests are that systems check.

In CI/CD, the mental model is:

1. Build → produce a deployable artifact (container image, binary, package).
2. Unit test → verify individual components in isolation.
3. Deploy to environment → temporarily place the artifact into a controlled staging environment.
4. Integration test → test the artifact with its dependencies (database, services, network) to confirm it works as a whole.
5. Promote/rollback → if integration tests pass, promote to production; if they fail, rollback.

Pro tip: Integration tests aren’t a replacement for unit tests — they complement them. Unit tests are fast and cheap; integration tests are slower and more expensive, but they catch the stuff unit tests can’t.

Think of it as a trust ladder: the higher you climb (from unit → integration → end-to-end), the more trust you have in the deployment, but also the more time and complexity each rung costs.

How it works step by step

Adding integration tests to your deployment job follows a repeatable sequence. This is the cause-and-effect order you’ll use every time:

1. Deploy your application to a test environment (staging, preview, or a dedicated integration namespace). This is the setup phase.
2. Run integration test suite — a separate set of tests that hit the running application through its real interfaces (HTTP, database, message queues). This is the verification phase.
3. Collect results — check exit code and test report.
4. Automate the decision — if tests pass, continue to next stage (e.g., production promotion); if they fail, stop the pipeline and roll back.

Each step feeds into the next. The key is that integration tests run against the live artifact you’re about to deploy — not a separately built test instance that doesn’t match production.

Key detail: In GitHub Actions, you can use the needs keyword to control job dependencies. Your integration-test job needs the deployment job, and your production-promotion job needs the integration-test job (with a check that it succeeded). This creates a gate.

Hands-on walkthrough

Let’s make this concrete with GitHub Actions. We’ll add an integration test job to a pipeline that deploys to a staging environment, then only promotes to production if those tests pass.

Example 1: Simple integration test job in GitHub Actions

name: Deploy with integration tests

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t myapp:${{ github.sha }} .
      - run: docker push registry.example.com/myapp:${{ github.sha }}

  deploy-staging:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh staging ${{ github.sha }}

  integration-test:
    needs: deploy-staging
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Wait for staging to be ready
        run: ./scripts/wait-for-it.sh https://staging.example.com --timeout=60
      - name: Run integration tests
        run: ./scripts/integration-tests.sh https://staging.example.com

  deploy-production:
    needs: integration-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy.sh production ${{ github.sha }}

Expected output: The pipeline runs build → deploy-staging → integration-test → deploy-production. If integration-test fails, deploy-production is skipped.

Example 2: Python integration test script

Here’s a simple integration test script in Python using requests and pytest:

# tests/integration/test_api.py
import os
import requests

def test_health_endpoint():
    base_url = os.environ["APP_URL"]
    response = requests.get(f"{base_url}/health", timeout=10)
    assert response.status_code == 200

def test_user_creation_flow():
    base_url = os.environ["APP_URL"]
    payload = {"email": "test@example.com", "password": "secret"}
    response = requests.post(f"{base_url}/users", json=payload, timeout=10)
    assert response.status_code == 201
    user_id = response.json()["id"]
    fetch = requests.get(f"{base_url}/users/{user_id}", timeout=10)
    assert fetch.status_code == 200

And the shell script that runs it:

#!/usr/bin/env bash
set -euxo pipefail

APP_URL="$1"

IMPORTANT: use the same environment as the deployed artifact

export APP_URL
pytest tests/integration --junitxml=integration-report.xml

If any assertion fails, pytest exits non-zero, and GitHub Actions marks the job as failed.

Example 3: Separate test environment (preview deployment)

For pull requests, you can deploy a preview environment and run integration tests against it:

name: PR preview

on:
  pull_request:

jobs:
  deploy-preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/deploy-preview.sh ${{ github.event.pull_request.head.sha }}

  integration-test:
    needs: deploy-preview
    runs-on: ubuntu-latest
    steps:
      - run: ./scripts/wait-for-it.sh https://preview-${{ github.event.number }}.example.com --timeout=60
      - run: pytest tests/integration

  comment-status:
    needs: integration-test
    runs-on: ubuntu-latest
    if: always()
    steps:
      - uses: actions/github-script@v7
        with:
          script: |
            const outcome = needs.integration-test.result;
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `Integration tests: ${outcome}`
            });

Here, the comment job runs even if tests fail, so you get feedback on every PR.

Pro tip: Always add a wait-for-it (or health-check) step before running integration tests. Your app may take a few seconds to boot, and tests run too early will fail even though the app is fine.

Compare options / when to choose what

You have several ways to add integration tests to deployment jobs. Here’s how to choose:

When to choose:

• Small app, low stakes: same job is fine.
• Medium/large app: separate job with needs.
• Many PRs, want parallel testing: preview environments.
• Already using k8s: inline test job is natural.

Troubleshooting & edge cases

Even with the right setup, things break. Here are the most common issues:

• Tests fail because the app isn’t ready yet — you hit a race condition. Fix: add health check with retry, not just a sleep.
• Database isolation: Your integration tests share a database with other tests and corrupt state. Fix: use a dedicated schema or spin up a test database per run.
• Credentials not available in test job: The integration test job doesn’t have the same secrets as the deploy job. Fix: explicitly pass secrets using env: or secrets: in the job.
• Test environment differs from production: A different database version, different environment variables, or different network config. Fix: keep the test environment as close to production as possible (use the same images, same config templates).

Pro tip: When a deployment fails an integration test, rollback to the previous version rather than trying to fix forward. It’s faster and safer.

What you learned & what's next

You now know how to add integration tests to deployment jobs: you understand the purpose, the mental model, the step-by-step flow, how to implement it in GitHub Actions, and when to use different approaches.

You can now:

• Explain the core concept behind integration tests in deployment jobs.
• Complete a hands-on exercise (like the ones above) to add integration tests to your own pipeline.
• Diagnose common failures and avoid them.

Next lesson: In the next step of the CI/CD foundations track, you’ll learn to handle deployment failures gracefully — how to rollback, alert, and debug when a deployment goes wrong despite your tests passing. That’s the natural follow-up to making your pipeline safer at the gate.

Go ahead and add an integration test job to one of your own pipelines — even a simple health check. You’ll immediately see the safety it adds.