阅读中文版本

Local-to-CI Parity Workflow

Align local and CI test execution so a test passing locally also passes in CI, eliminating environment-only failures.

Overview

Make tests behave the same locally and in CI.

This workflow is reusable across teams and environments; adapt the commands to your tooling while keeping the sequence and checkpoints intact.

Environment and prerequisites

• A container or version manager
• CI configuration
• A reproducible task runner

Procedure

1. Pin the same runtime versions

Use identical language and tool versions locally and in CI.

Expected state: Version drift cannot explain failures.

2. Run tests in the same container

Execute tests in the same container image locally and in CI.

Expected state: The environment is identical on both sides.

3. Align environment variables

Produce the same environment for tests in both places.

Expected state: Config differences no longer cause failures.

4. Verify parity with a sample change

Break a test locally and confirm CI reports the same failure.

Expected state: Local and CI results agree.

# run tests in the same image the CI uses
docker run --rm -v "$PWD":/app -w /app node:22-alpine npm test

Verification

Confirm a deliberately broken test fails the same way locally and in CI.

Decision points

Container parity or version managers?

• Container where possible
• Version managers only

Recommendation: Containers give the strongest parity; version managers are a lighter option.

Mirror all CI env vars?

• Only test-relevant vars
• All variables

Recommendation: Align only test-relevant variables to keep secrets out of local runs.

Common failures

• Version drift causes local-only passes.
• Secret env differences cause failures.
• Unreproducible environments waste debugging time.