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@latestCreate 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
envconfig - 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"]— runbuildin all dependencies before runningtestin this packageoutputs— 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-cacheRemote Caching with Vercel
For team sharing and CI, enable Vercel Remote Cache:
npx turbo login
npx turbo linkThis 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-nameOr 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=1Concurrency 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 --summarizeThis 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:
- Configure
pipeline.testwith correctoutputsandenv - Use
--filter=...[HEAD^1]to scope to changed packages - Enable remote cache (Vercel or self-hosted) for team + CI sharing
- Set
cache: falsefor E2E or stateful tests that shouldn't be cached - Use
--summarizeto diagnose cache effectiveness
Once caching is working, CI test time scales with the number of changed packages — not the size of the monorepo.