Skip to content
Source
Sign inSign up

Skip unchanged packages

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 says Restored the outputs from the cache step-... This step did not run.
  • Test the CLI runs, 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 --json shows the cache of the step as { "atRunTime": true }.
  • A do step has no command text in the key. Change the key of 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 run step, also its command and its workingDirectory.
  • The image of the job (node or browser), and the key of 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:, in dependencies, devDependencies, optionalDependencies or peerDependencies.
  • The root files, when they exist: pnpm-lock.yaml, package.json, pnpm-workspace.yaml, .npmrc and .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_modules or dist, 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 to inputs. 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 a workspace: dependency that names no package of the workspace, fails the step. Its log says Could not list the files of the step cache package and 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.addPath and ctx.afterJob of 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.