Troubleshooting

Start with diagnostics in the saved inventory. A completed scan can exit with 0 while reporting errors, so the exit code alone does not establish completeness. The diagnostic reference describes every code.

No files or tests were found

1. Run from the project root, or pass its folder with --root.

2. Check the runner with --framework. Its name is node for node:test and bun for Bun.

3. Try an explicit, quoted glob for files that exist in the project:

   npx test-inventory "tests/**/*.spec.ts" --framework playwright --pretty

Without globs, runner defaults and the settings the scanner can read from config choose the files. A dynamic config or a custom location may need explicit globs. A bare folder is not a recursive glob. See no-files-matched, file-not-run and config-value-unknown in the reference.

If files were found but have no test records, check for framework-mismatch, parse-error and unresolved-test-import before assuming they contain no tests.

Several runners were detected

Scan once per runner, using its own patterns and --framework. For example, a project can use Playwright for browser tests and Vitest for unit tests. Do not compare those two inventories with diff: their frameworks must match.

Tests imported from a helper are missing

Read the unresolved-test-import message: it identifies where the import chain ends. Check that local files exist and parse, and that aliases are declared in a supported config or tsconfig. Workspace packages that point only at missing build output may need their source export corrected.

The scanner does not evaluate wrappers from installed packages. scanSource() follows no imports at all; use scan() when the answer needs project files. See import limits.

A config value or framework version is unknown

Configs are read, not executed. A value derived from environment variables, an installed package or an unsupported factory can produce config-value-unknown. Explicit globs help select files but do not resolve unknown settings. Fix a supported literal setting only if it represents how your runner should behave; otherwise retain the diagnostic.

For version detection, inspect frameworkVersion and its diagnostic. Pass --framework-version when you know the exact runner version but the project does not record it in a supported place. See version detection.

The runner reports a different test count

Check whether it creates one execution per table row, loop pass, browser or project. The default scan counts declarations. Try --expand-cases for known tables and loops, and inspect projects for browser and project coverage. Skipped suites, focus and runner-side filters can also explain differences. See key concepts and runner comparisons.

A related-files query returns too many tests

Inspect hasUnfollowedDependencies and dependency-not-followed. Tests with gaps are kept because the changed code may affect them through an unseen dependency. Shared setup, barrel exports and snapshots can also connect many tests to one file. Pass changed paths relative to the CLI's current folder; MCP related paths are relative to the server's project root. See dependency limits.

A diff refuses saved scans or warns about hashes

Use complete JSON inventories, without --fields or --format jsonl. Scan both revisions with the same core version, framework, root, patterns, filters and case-expansion setting. Different core versions disable hash comparison and rename matching. Scan errors can make missing tests look removed, so resolve them before drawing that conclusion. The diff guide describes the warnings.

The command fails or the MCP server does not start

CLI exit code 2 means invalid arguments, an input or output problem, or an unexpected failure. Read standard error; check the Node.js requirement, paths and write permissions. Exit code 0 with diagnostics is a different outcome.

For MCP, inspect the client's server status and logs, confirm its project root and call test_summary first. The server README covers setup and tool-call failures.

Report a scan problem

Include the core version, command or tool arguments, expected result, diagnostic and a small test file that reproduces the issue. Remove private project data before attaching files. Use the scan issue form. Report vulnerabilities privately through the security policy.