Skip to content

Getting started ​

Mjölnir (mjolnir-qa on npm) audits your test suite and CI pipelines, then reports a single worthiness score plus prioritized findings — each with a rule ID, a location, and a fix.

Install ​

Run it with no install:

bash
npx mjolnir-qa@latest

Or install globally:

bash
npm i -g mjolnir-qa@latest

@latest is the dist-tag, not a version number, and it is deliberate: it always resolves to the newest published stable release, so an instruction in a README can never 404 because a version was renamed or a release was withdrawn.

It is also mutable. If you are copying this into a gate that has to behave the same next month, pin the version instead — that is the whole difference between npx mjolnir-qa@6.1.0 and the lines above.

Requires Node.js ≥ 22.18. Works on Windows, macOS, and Linux.

Run the command from your repository root. It reads test code and CI workflows and prints prioritized findings with locations, evidence, and suggested fixes. It does not run your test suite or automatically apply those fixes. Review a finding, make the change, run the affected tests, then scan again. A scan may write cache data; it is not a promise of zero filesystem writes.

Why ≥ 22.18? The build toolchain sets the floor — tsdown targets Node 22.18, and that is the oldest runtime the release pipeline compiles and smoke-tests against; the runtime dependencies themselves have no such requirement.

Your first scan ​

Open a terminal in the repository you want to inspect: the directory containing your project files, test code, and CI configuration. Use a repository with supported test files or workflows; an empty repository has no test suite to score.

  1. Check your runtime with node --version — use Node.js 22.18 or later.
  2. Run npx mjolnir-qa@6.1.0 from that repository root.
  3. Read the prioritized findings. Each gives you a rule ID, file location, evidence, and a suggested fix.
  4. Review one relevant finding, make the change, run the affected tests, and repeat the scan.

If a scan is partial, investigate the reported problem and rerun it before drawing conclusions. A clean scan means no findings in the scanned scope; it does not establish that your tests pass.

See an example report to learn how to read the output before running the command.

GitHub Action ​

The Marketplace action runs the same scan from any workflow:

yaml
- uses: Sergey-Bar/Mjolnir@v6
  with:
    scope: changed
    fail-on: error

Pin @v6 to follow the major line, or an exact release tag for a reproducible gate. The direct composite Action is blocking by default; the workflow generated by mjolnir ci install is advisory unless you select --gate error or --gate warning.

Core commands ​

CommandWhat it does
mjolnirFull-repo scan + worthiness score
mjolnir --scope changedOnly what your branch introduced — the CI form
mjolnir ci installGenerate the advisory PR workflow
mjolnir explain QA-CI-001What / why / fix + measured or unmeasured state
mjolnir explain --list --unmeasuredThe rules running on assumption, not measurement
mjolnir --json / --format sarifMachine-readable / GitHub Code Scanning
mjolnir --include-warnAlso run WARN-tier rules (higher FP risk)

When something's flaky ​

CommandWhat it does
mjolnir explain --evidence ./test-results/Flake verdicts from a real run: retries, lucky passes, durations
mjolnir explain --playwright ./test-results/Playwright run summary — retries / flakes / slowest

One finding, up close ​

text
▍▞ QA-CI-001 — continue-on-error masks a failing verification gate

Severity:    error
Confidence:  high
Evidence:    E2

WHAT WAS FOUND
  Job `security-scan` runs a verification gate under `continue-on-error: true`.

WHY IT MATTERS
  This job can fail every day and CI will still show green. The checkmark
  on this workflow cannot be trusted.

HOW TO FIX
  Remove continue-on-error, or scope it to individual non-blocking steps only.

That is the unit of value: not a style nit, but a place where your CI is telling you something passed when it didn't.

Released under the MIT License.