Testing in CI
Run tests automatically on every push with GitHub Actions, caching, and gates.
What you'll learn
- Why tests must run in continuous integration, not just locally
- Configuring GitHub Actions to run tests on every push and PR
- Caching dependencies and sharding for speed
- Using test results as merge gates and status checks
Concept
CI Is Where Tests Earn Their Keep
Locally, it is easy to skip a failing test or forget to run the suite. Continuous integration (CI) runs the full suite on every push and pull request on a clean machine, so a broken test blocks the merge. This is the safety net that makes tests valuable at the team level: a passing CI run means the change is safe to merge, not just safe on your laptop.
A Basic Workflow
A GitHub Actions workflow installs dependencies with pnpm install --frozen-lockfile, runs pnpm test (and lint and build), and uploads the coverage report. The job runs on pull_request and push to main. Set the job as a required status check in branch protection so merges are blocked while tests fail or are still running.
Speed with Caching and Sharding
CI minutes are precious. Cache the pnpm store and any build output with actions/cache so installs are fast. Run tests in parallel by sharding: split the suite into N shards and run N jobs concurrently, then merge the results. Cache the Vitest transform output with dir: 'node_modules/.vite' to speed cold starts. Keep the total CI time under ten minutes so developers do not context-switch while waiting.
Gates and Quality
Beyond pass/fail, CI can enforce coverage thresholds, forbid new console.logs, and run a linter. Publish coverage to a service like Coveralls or Codecov so trends are visible. Treat the CI config as code: review changes to it, keep it in version control, and document what each job does so the team understands the gates protecting the main branch.
In Practice
Keep CI fast by caching the pnpm store and Vitest's transform output, and by sharding the suite across parallel jobs when it grows past a few hundred tests. Fail fast: run the unit suite first (seconds), and only run integration and E2E if unit passes — there is no point debugging a slow E2E failure when a unit test already caught the bug. Make the test job a required status check in branch protection so a red build blocks the merge. Publish coverage as an artifact and comment the diff on pull requests so reviewers see what changed. Periodically review the CI time: if it creeps past ten minutes, investigate sharding, caching, or pushing tests down the pyramid. A fast, trustworthy CI gate is the foundation that lets the team move quickly without breaking main.
Example
// scripts/ci-test.ts — orchestrate the test pipeline the way CI does.
import { execSync } from "node:child_process";
function run(label: string, cmd: string): void {
console.log(`\n=== ${label} ===`);
execSync(cmd, { stdio: "inherit", cwd: process.cwd() });
}
// Install with a frozen lockfile for reproducible builds
run("install", "pnpm install --frozen-lockfile");
// Single-pass test run (never watch mode in CI)
run("test", "pnpm test:run");
// Collect coverage and fail the build below thresholds
run("coverage", "pnpm test:run --coverage");
console.log("\nCI test pipeline complete — safe to merge.");
This script mirrors what the CI workflow does: install with a frozen lockfile, run tests once (not in watch mode), and collect coverage. The equivalent GitHub Actions YAML calls these same commands in steps.
Try it
- CI YAML Generator
Scaffold the GitHub Actions workflow that runs your tests.
- YAML Validator
Validate your workflow YAML before committing it.
Common mistakes
The mistake
Running tests in watch mode in CI
The fix
Use `vitest run` (or `jest --ci`) for a single pass that exits. Watch mode never terminates and hangs the CI job until timeout.
The mistake
Not caching dependencies
The fix
Cache the pnpm store and node_modules with actions/cache. A cold install on every run wastes minutes and money.
Practice Testing in CI
3 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.