CI / Speed and debugging
Skip the tests of packages that did not change
Your pnpm monorepo has many packages, and a change to one package runs the tests of all of them in every CI run. A package cache skips the tests of the packages that did not change: when a run of a test step with the same package files passed before, the step does not run.
6 min read
Give a test step cache: { package }. Before the step runs, the runner hashes the files of that package and of each workspace package that it depends on. Without Nx or Turborepo, nothing else skips these tests for you.
Tip
You do not have to write these settings yourself. The CI caches agent can open a pull request that adds them for you: see Get a pull request that caches your CI steps.
1. Add cache: { package } to each test step
Give each test step the folder of its package:
import { defineWorkflow, pullRequest, push, setup } from '@tanstack-source/ci'
export default defineWorkflow('ci', { on: [pullRequest({ branches: ['main'] }), push({ branches: ['main'] })] })
.job('test', {
steps: [
setup.node(),
setup.pnpm(),
{ name: 'Install dependencies', run: 'pnpm install --frozen-lockfile' },
{ name: 'Test the git engine', run: 'pnpm -C packages/git test', cache: { package: 'packages/git' } },
{ name: 'Test the CLI', run: 'pnpm -C packages/cli test', cache: { package: 'packages/cli' } },
],
})
A test step makes no files, so it has no outputs. When it passes, the runner saves only that it passed with these inputs.
2. Push the workflow
The first run has no entry for the steps yet. Each step runs, and its log starts with:
No cache for step-3f2a... (412 input files): the step runs, and saves that it passed if it passes
When the step passes, the last line of its log is Saved the cache step-3f2a....
3. Push a change to one package
Push a change to packages/cli only. In the new run:
Test the git engine (cached)did not run. Its log saysRestored the outputs from the cache step-... This step did not run.Test the CLIruns, because a file of its package changed.
A change to a package runs the steps of each package that depends on it. When packages/cli has "@acme/git": "workspace:*" in its package.json, a change to packages/git runs both steps.
Done
The tests of a package run only when one of these changed: a file of the package, of a workspace package that it depends on, of the root install files, or of .source/. src ci run uses the package cache too, with the cache folder of your machine (see Run CI jobs on your machine).
Add the files that a test reads outside the package
Some tests read a file outside their package, like a fixture at the root, or a source file of an app. Add these files to inputs:
{
name: 'Test the CLI',
run: 'pnpm -C packages/cli test',
cache: { package: 'packages/cli', inputs: ['apps/web/src/server/rest.ts', 'test/fixtures/**'] },
}
With package, inputs is optional, and takes 0 to 100 paths or globs. They have the rules of the inputs of a step cache.
Cache each cell of a matrix
A matrix job can test one package in each cell, with one step. Give cache a function of the ctx of the step, and it gives the cache of each cell:
.job('test', {
matrix: { suite: ['git', 'ci', 'cli'] },
steps: [
setup.node(),
setup.pnpm(),
{ name: 'Install dependencies', run: 'pnpm install --frozen-lockfile' },
{
name: 'Tests',
do: async (ctx) => {
await ctx.sh`pnpm -C packages/${ctx.matrix.suite} test`
},
cache: (ctx) => ({ package: `packages/${ctx.matrix.suite}` }),
},
],
})
- The runner calls the function before the step, after its
if. - The values of the matrix cell are in the key, so each cell has its own entry.
- When the function gives a cache that breaks a rule, the step fails. Its log says
The cache function of step "Tests" gave a cache that is not valid:and the reason. - The plan cannot know what the function gives.
src ci plan --jsonshows the cache of the step as{ "atRunTime": true }. - A
dostep has no command text in the key. Change thekeyof the cache when you change what the step runs.
What goes into the key
The key is step- and a sha256 of the step and of its files.
The step:
- The name of the step. For a
runstep, also its command and itsworkingDirectory. - The image of the job (
nodeorbrowser), and thekeyof the cache, when you give one. - The values of the matrix cell, in a job with a matrix.
- The folder of the package.
The files (the path and the content of each one):
- Every file of the package folder.
- Every file of each workspace package that it depends on, and of their dependencies in turn. A dependency counts when its version starts with
workspace:, independencies,devDependencies,optionalDependenciesorpeerDependencies. - The root files, when they exist:
pnpm-lock.yaml,package.json,pnpm-workspace.yaml,.npmrcand.nvmrc. - Every file of
.source/, so a change to a workflow file runs the step again. - The files of
inputs.
git lists the files of the folders, with git ls-files --cached --others --exclude-standard:
- An ignored file, like a file of
node_modulesordist, is not in the key. - A new file that you did not commit yet is in the key.
The runner finds the folder of a package from its name, through the packages of pnpm-workspace.yaml. Without that file, it uses the workspaces of the root package.json. The env of the step is not in the key.
What can go wrong
- A file outside the hash gives a wrong pass. When a test reads a file that is not in the key, a change to that file does not run the test. The step shows as passed with
(cached), but the tests did not run. Add the file toinputs. There is no check for this. - Only
workspace:versions count. A dependency with another version, like*or^1.0.0, is not followed, also when it names a package of the workspace. - A wrong package fails the step. A folder with no
package.json, or aworkspace:dependency that names no package of the workspace, fails the step. Its log saysCould not list the files of the step cache packageand the reason. - The whole lockfile is in the key. A change to any dependency of any package runs every step that has a package cache.
- A skipped step does nothing else. On a hit,
ctx.setOutput,ctx.summary,ctx.addPathandctx.afterJobof the step do not happen.
Who reads which entry
A package cache entry is a step cache entry, so it follows the cache scopes:
- A pull request from a fork saves its entries in the scope of its pull request. No trusted or protected run restores them.
- An untrusted run without a pull request saves none.
- A job of a hidden workflow neither restores nor saves. Its steps always run.
To see the entries, run src ci cache list: their keys start with step-. To delete them, run src ci cache delete, or use Settings > CI > Cache.