headlamp

Headlamp

Headlamp is a Rust-powered test UX CLI: smarter test selection, cleaner output, and a unified workflow across jest, Rust tests (headlamp runner), cargo test, cargo nextest, and pytest.

Headlamp is useful when you want a consistent way to run tests across different projects and keep feedback fast as your repo grows. It can select tests based on what changed, surface failures in a readable format, and keep common defaults (like runner args and coverage settings) in a single config file so your team doesn’t have to remember a long list of flags.

Why Headlamp

• One CLI, many runners: --runner=headlamp|jest|cargo-nextest|cargo-test|pytest
• Selection that scales: run what changed (--changed) and what’s related (dependency-graph driven)
• Coverage-first UX: coverage output you can actually read
• Fast: Rust core + caching

Installation

npm (Node.js projects)

Requirements:

• Node >= 18

Install:

npm i -D headlamp

Run:

npx headlamp --help

Cargo (Rust projects)

Install from crates.io:

cargo install headlamp

Python (pytest projects)

Install:

pip install headlamp

headlamp --runner=pytest

Peer dependencies (system requirements)

Headlamp is a wrapper around your project’s runners. It does not vendor the runners themselves, so you need the runner executables available in your environment for the features you’re using.

Common (all runners)

• Git: required for --changed=... modes (e.g. --changed=branch).

Jest runner (--runner=jest)

• Node.js: required.
• Jest installed in the repo: Headlamp expects Jest to be runnable from your project (typically ./node_modules/.bin/jest).
• Coverage (--coverage): requires Jest coverage support (standard Jest --coverage + reporters). Headlamp formats/prints coverage from generated reports.

Pytest runner (--runner=pytest)

• Python 3: required.
• pytest: must be on PATH (pytest / pytest.exe).
• Coverage (--coverage): requires pytest-cov (Headlamp enables coverage and passes --cov flags; branch coverage uses --cov-branch).

Headlamp (native Rust runner) (--runner=headlamp)

• Rust toolchain: cargo + rustc.
• Per-test timings: requires a preinstalled nightly toolchain (Headlamp enables libtest JSON + --report-time only when nightly is available).
  • Install via: rustup toolchain install nightly

Cargo test runner (--runner=cargo-test)

• Rust toolchain: cargo + rustc.
• Coverage (--coverage): collected via LLVM tools from rustup (no cargo-llvm-cov dependency).
  • Install via: rustup component add llvm-tools-preview

Cargo nextest runner (--runner=cargo-nextest)

• Rust toolchain: cargo + rustc.
• nextest: requires cargo-nextest (cargo install cargo-nextest).
• Coverage (--coverage): collected via LLVM tools from rustup (no cargo-llvm-cov dependency).
  • Install via: rustup component add llvm-tools-preview

Quickstart

Jest

npx headlamp --runner=jest

Forward runner args after -- (unknown args are forwarded):

npx headlamp --runner=jest -- --runInBand

Cargo nextest / cargo test

headlamp --runner=cargo-nextest
headlamp --runner=cargo-test

Requirements:

• --runner=cargo-nextest: requires cargo-nextest to be installed.
  • Install via: cargo install cargo-nextest (or your preferred installer)

CLI

Run headlamp --help to see the up-to-date flags list.

Highlights:

• runners: --runner=headlamp|jest|pytest|cargo-nextest|cargo-test
• changed selection: --changed=all|staged|unstaged|branch|lastCommit|lastRelease
  • lastRelease selects changes since the previous stable SemVer release tag
• coverage: --coverage plus --coverage-ui, --coverage-detail, thresholds, etc.
• artifacts (default: none): --keep-artifacts to keep runner artifacts on disk

Legacy aliases (still accepted, but not recommended):

• --keepArtifacts
• --coverage.detail

Configuration

Headlamp discovers config from your repo root. Supported file names:

• headlamp.toml (highest precedence)
• headlamp.config.ts
• headlamp.config.js
• headlamp.config.mjs
• headlamp.config.cjs
• headlamp.config.json
• headlamp.config.json5
• headlamp.config.jsonc
• headlamp.config.yaml
• headlamp.config.yml
• .headlamprc plus .headlamprc.* variants (.json, .json5, .jsonc, .yaml, .yml, .js, .cjs, .mjs, .ts)

Headlamp also supports embedded TOML config (lower precedence than explicit config files):

• pyproject.toml under [tool.headlamp]
• Cargo.toml under [package.metadata.headlamp]

Example: headlamp.toml (recommended for Rust + Python)

# Run tests sequentially (useful for very heavy integration tests)
sequential = true

[coverage]
abort_on_failure = true
mode = "auto"
page_fit = true
keep_artifacts = false

[changed]
depth = 20

Example: headlamp.config.ts

Rules:

• Must have a default export
• Only relative imports are supported inside the config file (./ and ../)

export default {
  // Runner defaults
  jestArgs: ["--runInBand"],

  // Run once before tests (npm script name or a shell command)
  bootstrapCommand: "test:jest:bootstrap",

  // Global toggles
  ci: false,
  verbose: false,
  noCache: false,
  keepArtifacts: false,

  // Coverage defaults
  coverage: true,
  coverageUi: "both",
  coverage: {
    abortOnFailure: true,
    mode: "auto",
    pageFit: true,
  },

  // Changed selection defaults
  changed: { depth: 2 },
};

Artifacts (coverage, caches, temp files)

By default, headlamp runs artifact-free: it uses an ephemeral per-run workspace and does not leave files behind in your repo (e.g. coverage/, .coverage, .pytest_cache, target/) or OS temp.

If you need artifacts on disk (for example, to upload coverage reports in CI), opt out:

• CLI: --keep-artifacts
• Config: keepArtifacts: true

Contributing

Pull requests are welcome. For large changes, open an issue first to align on direction.

Support

• Bug reports and feature requests: GitHub Issues

License

MIT — see LICENSE.