jestjs/jest · error · Error

Package '${pkg.name}' does not declare '@jest/test-utils' as

Error message

Package '${pkg.name}' does not declare '@jest/test-utils' as dev dependency, but it is referenced in:

${testUtilsReferences.join('\n')}

What it means

The inverse of 245: buildTs.mjs:142-152 fires when a package does NOT declare @jest/test-utils in devDependencies, yet one or more of its __tests__/tsconfig.json files reference a path ending in 'test-utils'. The build enforces a 1:1 correspondence between TS project references and the package.json devDependency declaration.

Source

Thrown at scripts/buildTs.mjs:143

    return tsConfig.references.some(
      ({path}) => path && path.endsWith('test-utils'),
    );
  });

  if (hasJestTestUtils && testUtilsReferences.length === 0) {
    throw new Error(
      chalk.red(
        `Package '${
          pkg.name
        }' declares '@jest/test-utils' as dev dependency, but it is not referenced in:\n\n${tsConfigPaths.join(
          '\n',
        )}`,
      ),
    );
  }

  if (!hasJestTestUtils && testUtilsReferences.length > 0) {
    throw new Error(
      chalk.red(
        `Package '${
          pkg.name
        }' does not declare '@jest/test-utils' as dev dependency, but it is referenced in:\n\n${testUtilsReferences.join(
          '\n',
        )}`,
      ),
    );
  }
}

const args = [
  'tsc',
  '-b',
  ...packagesWithTs.map(({packageDir}) => packageDir),
  ...process.argv.slice(2),
];

View on GitHub (pinned to f49721c78e)

Solutions

Add "@jest/test-utils" to the package's devDependencies (e.g. "@jest/test-utils": "workspace:*").
Alternatively, remove the stray test-utils reference from __tests__/tsconfig.json if test-utils isn't actually used.
Re-run scripts/buildTs.mjs to verify the reference/declaration pair is consistent.

Example fix

// before: package.json has no @jest/test-utils, but __tests__/tsconfig.json references it
// after (package.json)
"devDependencies": { "@jest/test-utils": "workspace:*" }

Defensive patterns

Strategy: validation

Validate before calling

function assertNoDanglingTestUtilsReference(pkg, packageDir, glob, fs, stripJsonComments) {
  const isDevDep = Object.keys(pkg.devDependencies || {}).includes('@jest/test-utils');
  const tsConfigs = glob.sync('**/__tests__/tsconfig.json', { absolute: true, cwd: packageDir });
  const refs = tsConfigs.filter(p => {
    const cfg = JSON.parse(stripJsonComments(fs.readFileSync(p, 'utf8')));
    return (cfg.references || []).some(r => r.path && r.path.endsWith('test-utils'));
  });
  if (!isDevDep && refs.length > 0) {
    throw new Error(`${pkg.name}: test-utils referenced in tsconfig but not in devDependencies`);
  }
}

Prevention

Any time you add a `references` entry ending in 'test-utils', also add @jest/test-utils to devDependencies.
When copying a __tests__/tsconfig.json from another package, prune references you don't need.
Treat the devDependency declaration and the tsconfig reference as a single atomic change.

When it happens

Trigger: Running scripts/buildTs.mjs after adding a `{ "path": "...test-utils" }` reference to a __tests__/tsconfig.json without also adding @jest/test-utils to that package's devDependencies.

Common situations: Copying a test tsconfig from another package that uses test-utils; adding a test that imports @jest/test-utils and wiring the TS reference but forgetting the package.json entry; workspace hooping masking the missing declaration locally.

Related errors

AI-assisted analysis of jestjs/jest@f49721c78e (2026-08-03). Data as JSON: /data/errors/96ce0eb3805114c9.json. Report an issue: GitHub.