Testing in Turborepo: Pipelines, Caching, and Parallelization
Turborepo has become a go-to tool for JavaScript and TypeScript monorepos, especially in the Next.js and React ecosystem. Its core strength is a smart build system that caches task outputs and runs everything in parallel whenever possible. When applied to testing, this means you can have dozens of packages and still get sub-second test runs on code that hasn't changed. This guide covers how to configure Turborepo pipelines for testing, set up remote caching, manage task dependencies, and use workspace filtering to run only what you need.
Understanding turbo.json Pipeline Configuration
The heart of Turborepo is turbo.json at the workspace root. Every task you want Turbo to manage — build, lint, test, type-check — gets defined in the pipeline (now called tasks in Turborepo v2) section.
Here's a complete configuration covering a typical monorepo's testing needs:
{
"$schema": "https://turbo.build/schema.json",
"tasks": {
"build": {
"dependsOn": ["^build"],
"outputs": ["dist/**", ".next/**", "!.next/cache/**"]
},
"test": {
"dependsOn": ["^build"],
"outputs": ["coverage/**"],
"cache": true
},
"test:unit": {
"dependsOn": ["^build"],
"outputs": ["coverage/unit/**"],
"cache": true
},
"test:integration": {
"dependsOn": ["^build"],
"outputs": ["coverage/integration/**"],
"cache": true,
"env": ["DATABASE_URL", "TEST_API_KEY"]
},
"test:e2e": {
"dependsOn": ["build"],
"cache": false
},
"lint": {
"outputs": []
},
"type-check": {
"dependsOn": ["^build"],
"outputs": []
}
}
}A few things to note here. The ^build syntax in dependsOn means "this task depends on the build task of all packages this package depends on." So if apps/web imports from packages/ui, Turbo will build packages/ui before running tests in apps/web. The outputs array tells Turbo what to cache — if the inputs haven't changed and the outputs exist in cache, Turbo skips the task entirely. E2e tests set cache: false because they typically depend on external state and running them from cache would give false confidence.
Setting the env Array Correctly
Turborepo's cache key includes the content of files and the values of environment variables you declare in env. If you don't declare an env var that affects your tests, you risk cache hits on test runs that should be invalid.
{
"tasks": {
"test:integration": {
"dependsOn": ["^build"],
"outputs": ["coverage/**"],
"cache": true,
"env": [
"NODE_ENV",
"DATABASE_URL",
"REDIS_URL",
"TEST_TIMEOUT"
]
}
}
}For unit tests that are pure (no network, no DB), you generally don't need to declare any env vars. For integration tests, list every env var that could change the test outcome. If you're using .env.test files, make sure they're committed or at least consistent across machines, because Turbo reads them into the hash.
Remote Caching with Vercel
Turborepo's remote cache is what makes it shine in CI. Instead of each CI run computing everything from scratch, runs share a global cache.
With Vercel (the simplest option):
# Link your repo to Vercel Remote Cache
npx turbo login
npx turbo linkThis writes a .turbo/config.json with your team and token. In CI, set the environment variables:
# .github/workflows/ci.yml
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ secrets.TURBO_TEAM }}Now when a CI run tests a package that hasn't changed since the last run, it pulls the cached output in milliseconds instead of running Jest again.
Self-Hosted Remote Cache
If you can't use Vercel or need to keep artifacts on-premise, you can run your own Turborepo remote cache server. The API is simple — there are several open-source implementations:
# Using ducktape (a popular self-hosted option)
docker run -p 3000:3000 \
-e TURBO_TOKEN=your-secret-token \
-e STORAGE_PROVIDER=local \
-v /data/turbo-cache:/app/cache \
ducktape/turborepo-remote-cacheThen point your workspace at it:
// .turbo/config.json
{
"teamId": "my-team",
"apiUrl": "https://cache.internal.mycompany.com"
}Set TURBO_TOKEN in your environment and everything else works identically to Vercel's hosted cache. S3-backed implementations are available for production use where local storage won't scale.
Dependency Ordering: Test Depends on Build
The dependsOn: ["^build"] pattern is the most important ordering rule in Turborepo. Here's what it means in practice:
packages/
ui/ — exports Button, Input, etc.
api-client/ — exports fetchUser, postComment, etc.
apps/
web/ — imports from @myorg/ui and @myorg/api-client
dashboard/ — imports from @myorg/uiIf you run turbo run test, Turbo builds this dependency graph:
- Build
packages/uiandpackages/api-clientin parallel (no dependencies) - Build
apps/webandapps/dashboardin parallel (after their deps are built) - Run tests for all packages in the order that respects build outputs
Without the ^build dependency, tests in apps/web might run against stale compiled output from packages/ui. The caret syntax enforces that you always test against fresh builds.
For packages that don't compile (raw TypeScript resolved by Jest's transform), you can skip the build dependency:
{
"tasks": {
"test": {
"dependsOn": [],
"outputs": ["coverage/**"],
"cache": true
}
}
}This makes test runs faster but only works if your test runner (Jest, Vitest) handles TypeScript transformation directly without needing compiled outputs.
Filtering Workspaces: turbo run test --filter
Turborepo's --filter flag is powerful for local development and targeted CI runs:
# Test only a specific package
turbo run test --filter=@myorg/ui
# Test a package and everything that depends on it
turbo run test --filter=...@myorg/ui
# Test all packages that depend on @myorg/ui (downstream)
turbo run test --filter=@myorg/ui...
# Test packages matching a glob
turbo run test --filter="apps/*"
# Test packages changed since main (git-aware)
turbo run test --filter=[main]
# Test packages changed since a specific commit
turbo run test --filter=[HEAD^1]
# Combine filters
turbo run test --filter=apps/* --filter=[main]The [main] syntax is particularly useful in CI — it tells Turbo to only run the task for packages with git changes relative to the base branch. Unlike Nx's affected which uses a separate command, Turborepo integrates this directly into the filter syntax.
Parallelization Configuration
By default, Turbo runs as many tasks in parallel as your CPU allows. You can control this:
# Limit concurrency for resource-heavy tests
turbo run test --concurrency=4
# Run sequentially (useful for debugging)
turbo run test --concurrency=1
# Use percentage of CPU cores
turbo run test --concurrency=50%For e2e tests that spin up browsers, limiting concurrency prevents your CI machine from running out of memory:
turbo run test:e2e --concurrency=2You can also set a default concurrency in turbo.json:
{
"globalEnv": ["NODE_ENV"],
"tasks": {
"test:e2e": {
"dependsOn": ["build"],
"cache": false
}
}
}Practical GitHub Actions Workflow
Here's a complete workflow that uses filtering and remote caching:
name: CI
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Required for --filter=[main] to work
- uses: actions/setup-node@v4
with:
node-version: 20
cache: 'npm'
- run: npm ci
- name: Run tests (affected only on PR)
run: |
if [ "${{ github.event_name }}" = "pull_request" ]; then
npx turbo run test --filter=[origin/main] --cache-dir=.turbo
else
npx turbo run test --cache-dir=.turbo
fi
env:
TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
TURBO_TEAM: ${{ secrets.TURBO_TEAM }}
- name: Upload coverage
uses: codecov/codecov-action@v4
if: always()
with:
directory: ./coverageThe fetch-depth: 0 is critical — without full git history, the --filter=[origin/main] comparison can't determine what changed. On push to main you run all tests; on pull requests you only run tests for changed packages.
Inspecting the Task Graph
Before running tests in CI for the first time, use --dry-run to verify Turborepo's execution plan:
turbo run test --dry-runThis prints every task that would run, in what order, and whether each would be a cache hit or miss. It's invaluable for debugging why a task that should be cached is running again, or why a task you expected to run is being skipped.
turbo run test --dry-run=json | jq '.tasks[] | {package: .package, task: .task, cache: .cache}'Conclusion
Turborepo's pipeline model makes monorepo testing significantly more manageable as your codebase scales. The combination of fine-grained caching, remote cache sharing across CI runners, and flexible workspace filtering means you can maintain fast feedback loops even with dozens of packages. The key configuration decisions are declaring the right env variables in your test tasks, setting correct dependsOn relationships to ensure tests run against fresh builds, and using --filter=[main] in CI to skip unchanged packages. Once remote caching is in place, PRs that touch a handful of packages complete in roughly the same time regardless of how large your monorepo has grown.