Run tests related to changed source files using AST-based dependency analysis
npm install test-related 
Run tests related to changed source files using AST-based dependency analysis (tree shaking).
I wanted to run only the relevant tests for changed files with lint-staged.
Existing tools like Jest's --findRelatedTests don't work with Node.js's built-in node:test runner.
This tool uses TypeScript's AST to build a precise dependency graph, tracking which specific exports from source files are used by tests. When a source file changes, only tests that actually use its exports are triggered.
``bash`
npm install -D test-related
`bash`
yarn add -D test-related
`bash`
pnpm add -D test-related
`json`
{
"lint-staged": {
"src/*/.ts": [
"eslint --fix",
"typecheck-files",
"test-related"
],
"test/*/.ts": [
"eslint --fix",
"test-related"
]
}
}
> Tip: typecheck-files type-checks only changed files while respecting your tsconfig.json—perfect for fast pre-commit workflows.
`bash`
test-related src/index.ts src/utils.ts
`ts
import { findRelatedTests } from "test-related"
const result = findRelatedTests(["src/index.ts", "src/utils.ts"])
console.log(Running ${result.testFiles.length} related tests...)
// Run with node:test
const { execSync } = await import("node:child_process")
execSync(node --test ${result.testFiles.join(" ")}, { stdio: "inherit" })`
1. Parse test files - Extracts all imports using TypeScript AST
2. Parse source files - Extracts all exports (functions, classes, types, interfaces, enums)
3. Build dependency graph - Maps which tests use which exports
4. Match changed files - When a source file changes, finds tests that import its exports
`ts
// Source file: src/math.ts
export function add(a: number, b: number): number { return a + b }
export function subtract(a: number, b: number): number { return a - b }
// Test file: test/math.test.ts
import { add } from "../src/math.js" // Only uses 'add'
test("add works", () => { ... }) // This test runs
// No test for 'subtract' exists
`
If you change subtract() but not add(), the test won't run—because no test uses subtract.
`ts`
interface Options {
/* Working directory (defaults to process.cwd()) /
cwd?: string
/* Test directory patterns (defaults to ["test", "src"]) /
testDirs?: string[]
/* Source directory patterns (defaults to ["src"]) /
sourceDirs?: string[]
/* Always run tests matching this pattern when source files change /
alwaysRunPatterns?: string[]
/* Test runner command (defaults to "node --test") /
testRunner?: string
}
- TypeScript/JavaScript only - Requires .ts or .js filesimport * as x
- Static analysis only - Runtime dependencies (dynamic imports) are not tracked
- Export precision - Namespace imports () always trigger tests (can't determine specific usage)
For full coverage, run all tests in CI:
`bash``
node --test
MIT