Turborepo Test Caching: Speed Up Your Monorepo Test Suite

Turborepo Test Caching: Speed Up Your Monorepo Test Suite

Turborepo is a high-performance build system for JavaScript and TypeScript monorepos, made by Vercel. Its core feature is aggressive caching: if you run a test task and nothing has changed, the second run is instant. Applied across a monorepo with dozens of packages, this eliminates most CI test time.

Setup

Add Turborepo to an existing monorepo:

npm install turbo --save-dev
# or
npx create-turbo@latest

Create turbo.json in the root:

{
  "$schema": "https://turbo.build/schema.json",
  "pipeline": {
    "test": {
      "outputs": ["coverage/**"],
      "cache": true
    }
  }
}

Running Tests

# Run tests in all packages
turbo run test

# Run only in specific packages
turbo run test --filter=@my-org/ui

# Run in packages changed since main
turbo run test --filter=...[main]

The --filter flag is Turborepo's way of scoping work. The ...[main] syntax means "packages changed since the main branch, plus their dependents".

How Caching Works

Turborepo hashes the following inputs for each task:

  • Source files in the package
  • Environment variables listed in env config
  • The task's pipeline configuration
  • Outputs from upstream tasks

If the hash matches a previous run, Turborepo replays the cached output (logs, exit code) without executing the task.

turbo run test
# First run: executes tests
# → cache miss, executing...

turbo run test
# Second run: instant replay
# → cache hit, replaying logs...

Configuring the Pipeline

The pipeline in turbo.json defines how tasks relate and what they cache:

{
  "pipeline": {
    "build": {
      "outputs": ["dist/**", ".next/**"],
      "cache": true
    },
    "test": {
      "dependsOn": ["^build"],
      "outputs": ["coverage/**"],
      "cache": true,
      "env": ["NODE_ENV", "CI"]
    },
    "lint": {
      "outputs": [],
      "cache": true
    }
  }
}

Key fields:

  • dependsOn: ["^build"] — run build in all dependencies before running test in this package
  • outputs — files to cache and restore (coverage reports, build artifacts)
  • env — environment variables that affect the cache hash (changes to these bust the cache)
  • cache: true — enable caching for this task (default is true)

Disabling Cache for Specific Tasks

Some tasks shouldn't be cached — like E2E tests that depend on external state:

{
  "pipeline": {
    "test:e2e": {
      "cache": false,
      "dependsOn": ["^build"]
    }
  }
}

Or bypass cache at the CLI:

turbo run test --no-cache

Remote Caching with Vercel

For team sharing and CI, enable Vercel Remote Cache:

npx turbo login
npx turbo link

This links your monorepo to Vercel's remote cache. CI and team members share the same cache — if one machine ran the tests, others skip them.

# CI — authenticates with TURBO_TOKEN env var
TURBO_TOKEN=${{ secrets.TURBO_TOKEN }} turbo run test --filter=...[HEAD^1]

Self-Hosted Remote Cache

If you can't use Vercel's cache, use a community remote cache server. Options:

  • turbo-remote-cache (S3/GCS/Azure Blob — open source)
  • Ducktape (self-hosted Turborepo remote cache)

Set via environment variables:

TURBO_API=https://your-cache-server.com
TURBO_TOKEN=your-secret-token
TURBO_TEAM=your-team-name

Or in turbo.json:

{
  "remoteCache": {
    "signature": true
  }
}

Package-Level Test Configuration

Each package has its own package.json with a test script. Turborepo calls this:

// packages/ui/package.json
{
  "name": "@my-org/ui",
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest watch",
    "test:coverage": "vitest run --coverage"
  }
}

Turborepo doesn't care which test runner you use — Jest, Vitest, Mocha, or anything else. It caches the output of whatever test script runs.

Parallelism

Turborepo runs tasks in parallel by default, up to your CPU count:

# Run with 10 concurrent tasks
turbo run test --concurrency=10

# Run sequentially (useful for debugging)
turbo run test --concurrency=1

Concurrency is bounded by the dependency graph — tasks with dependsOn relationships run in order.

Filter Syntax

Turborepo's --filter is powerful:

# Single package
turbo run test --filter=@my-org/ui

# Package and all packages that depend on it
turbo run test --filter=...@my-org/ui

# Package and all its dependencies
turbo run test --filter=@my-org/ui...

# All packages changed since main (with dependents)
turbo run test --filter=...[main]

# All packages changed in the last commit
turbo run test --filter=...[HEAD^1]

CI Integration

GitHub Actions example:

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    env:
      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
      TURBO_TEAM: ${{ vars.TURBO_TEAM }}

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # Turborepo needs at least HEAD and HEAD^1

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci

      - name: Run tests
        run: turbo run test --filter=...[HEAD^1]

With remote caching, PRs that reuse untouched packages skip their tests entirely.

Viewing Cache Stats

turbo run test --summarize

This outputs a JSON summary at .turbo/runs/*.json with:

  • Which tasks were cached vs executed
  • Task durations
  • Cache hit rate

Use this to identify which packages aren't benefiting from caching (misconfigured outputs, missing env declarations, etc.).

Common Pitfalls

Missing outputs declaration: If a test task writes a coverage report but outputs doesn't include it, the report won't be cached or restored. Turborepo only caches what you declare.

Non-deterministic tests: Tests that flicker (pass sometimes, fail sometimes) will thrash the cache. Fix flaky tests before relying on caching.

Undeclared environment variables: If your tests read process.env.DATABASE_URL but you don't list DATABASE_URL in env, cache hits may replay results from a different database. Always declare env vars that affect test behavior.

fetch-depth: 1 in CI: With a shallow clone, Turborepo can't compare against HEAD^1. Use fetch-depth: 2 or fetch-depth: 0.

Summary

Turborepo caching makes monorepo test suites fast by eliminating redundant work:

  1. Configure pipeline.test with correct outputs and env
  2. Use --filter=...[HEAD^1] to scope to changed packages
  3. Enable remote cache (Vercel or self-hosted) for team + CI sharing
  4. Set cache: false for E2E or stateful tests that shouldn't be cached
  5. Use --summarize to diagnose cache effectiveness

Once caching is working, CI test time scales with the number of changed packages — not the size of the monorepo.

Read more

Start now free