Getting started

Requirements #

• Node.js 22.12 or newer
• A JavaScript or TypeScript project that uses Jest, Vitest, node --test, Playwright or Cypress (several runners and several projects in one repository are fine)
• Git is optional; without it SmartTest uses local snapshots

Install #

npm install -D @tkmremi/smarttest     # or: pnpm add -D @tkmremi/smarttest · yarn add -D @tkmremi/smarttest

To try an unreleased build, run pnpm install && pnpm build && pnpm release:pack in a clone of the repository and install the tarball it writes to packages/cli/.publish/.

If your repository has no root package.json (several independent projects), add a minimal one for repository tooling, as LeadsIt does.

Set up #

npx smarttest init --dry-run    # print the plan and the diff of every file
npx smarttest init --yes        # apply it

Example output on a repository with three runners:

Detected: Wasp + React + Express + Prisma + TypeScript + Vitest + Jest + node:test · npm · 6 independent projects · Git

Recommended
  Test layout      colocated                  (63% of existing tests follow this convention)
  Adapter          vitest, jest, node         (existing runner configuration is reused as-is)
  Impact mode      balanced
  Skipped tests    backend/**/*redisJobQueue* (your existing test commands skip these, so SmartTest does too)
  Git hook         smarttest run --staged     (.husky/pre-commit runs 3 full suite(s); one affected-tests run can replace them)

Changes
  + smarttest.config.ts   SmartTest configuration
  ~ .gitignore            ignore local SmartTest state

Running init again changes nothing. npx smarttest init --rollback restores the files it changed, unless you edited them since.

Run #

npx smarttest run                  # affected by uncommitted changes
npx smarttest run --staged         # affected by staged changes, for a pre-commit hook
npx smarttest run --base main      # affected by the current branch
npx smarttest run --all            # everything

Check the selection #

npx smarttest explain <test>          # why it ran or not
npx smarttest explain <file>          # which tests cover a file
npx smarttest validate-selection      # run selection and full suite, compare
npx smarttest benchmark --commits 20  # replay history: full run vs SmartTest, misses re-checked
npx smarttest shadow                  # full suite next to the selection, recorded over time
npx smarttest graph why <dependency> <dependent>  # how a file depends on another
npx smarttest doctor                  # runners, discovery, index, configuration

Record what each test runs (optional) #

npx smarttest trace           # runs each test file once with V8 coverage (about one full run)
npx smarttest trace --status  # how many traces are still fresh
npx smarttest trace --stale   # refresh only the stale ones

With fresh traces, a test that can reach a change on paper but never ran the changed code is skipped in FAST and BALANCED mode. See runtime evidence.

Use it in a Git hook #

init plans this for you. To do it separately:

npx smarttest hook status             # which hook manager, and which steps run whole suites
npx smarttest hook install --replace  # add SmartTest, comment out the full-suite steps
npx smarttest hook uninstall          # remove it and restore those steps

It works with husky, lefthook, simple-git-hooks and plain .git/hooks. The pre-commit hook runs npx --no-install smarttest run --staged --hook || exit 1 when node_modules/.bin/smarttest exists, and prints a notice instead when it does not. See commit and push hooks.

Use it in CI #

npx smarttest ci                      # picks the base for merge requests and branch builds

Reports and generated tests #

npx smarttest report --open           # HTML report of the last run
npx smarttest generate --dry-run      # missing test files as it.todo scaffolds

Next: how selection works, runtime evidence, CLI reference, configuration, running in CI.

Edit this page on GitHub