scopetest


Run only the tests that matter. A fast, dependency-aware test selector for JS/TS monorepos.

``bash


Run affected tests with one command


scopetest affected -x "jest --runTestsByPath {} --colors"
`

Why?

In large monorepos, running all tests is slow. scopetest analyzes your dependency graph and runs only tests affected by your changes—cutting CI time from minutes to seconds.

Install

`bash
npm install -g scopetest-cli
`

Usage

`bash


Find affected tests

scopetest affected --base main

Execute tests directly

scopetest affected -x "jest --runTestsByPath {}"
scopetest affected -x "vitest run {}"

Get affected source files instead

scopetest affected --sources

Different output formats

scopetest affected -f list # newline-separated
scopetest affected -f json # full stats

Changes since a specific commit

scopetest affected --since HEAD~5

Stop on first failure

scopetest affected -x "jest --runTestsByPath {}" --fail-fast

Run all tests if too many affected (blast radius protection)

scopetest affected -x "jest --runTestsByPath {}" --threshold 100
`

$3

affected - Find tests affected by changes

`
Options:
-b, --base Git ref to compare against (branch, commit, tag)
--since Find changes since this commit (commit..HEAD range)
-f, --format Output: paths, list, json [default: paths]
-x, --exec Execute command with {} replaced by affected files
--fail-fast Stop on first test failure (only with --exec)
--threshold If affected tests exceed N, use all tests instead
--sources Output affected source files instead of tests
--no-cache Skip cache, force rebuild
-r, --root Project root directory
`

why - Explain why a test is affected

`bash


See why a specific test is in the affected set

scopetest why src/utils/calc.spec.ts

Show all dependency paths, not just shortest

scopetest why src/utils/calc.spec.ts --all
`

`
Options:
The test file to explain
-b, --base Git ref to compare against
--since Find changes since this commit
--all Show all paths, not just the shortest
-r, --root Project root directory
--no-cache Skip cache, force rebuild
`

build - Rebuild dependency graph cache

`
Options:
-r, --root Project root directory
`

Output Formats

| Format | Description | Example |
|--------|-------------|---------|
| paths | Space-separated (default) | src/a.spec.ts src/b.spec.ts |
| list | Newline-separated | src/a.spec.ts
src/b.spec.ts |
| json | Full stats | {"tests": [...], "stats": {...}} |

Aliases: jest and vitest both map to paths.

Configuration

Create .scopetestrc.json:

`json
{
"testPatterns": ["/.spec.ts", "/.test.ts"],
"ignorePatterns": ["/node_modules/", "/dist/"],
"extensions": [".ts", ".tsx", ".js", ".jsx"]
}
`

CI Examples

$3

`yaml
- name: Run affected tests
run: npx scopetest-cli affected -b origin/main -x "jest --runTestsByPath {} --colors"

With blast radius protection (threshold exceeded = run all tests)


- name: Run affected tests (with threshold)
run: npx scopetest-cli affected -b origin/main -x "jest --runTestsByPath {}" --threshold 500
`

$3

`bash
npx scopetest-cli affected -b origin/master -x "npx jest --runTestsByPath {} --colors"
`

$3

`bash
jest --runTestsByPath $(scopetest affected -b main)
`

How It Works

1. Parses all JS/TS files using oxc
2. Builds a dependency graph with petgraph
3. Gets changed files from git diff
4. Traverses graph to find all affected files
5. Filters to test files only

Performance

On a 12,500+ file monorepo:
- Initial build: ~20-30s
- Cached: ~200ms

Supported Imports

- ES6: import x from 'y'
- Dynamic: import('path')
- CommonJS: require('path')
- Re-exports: export * from 'y'`
- TypeScript path aliases
- Workspace packages

License

MIT