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:
npx mjolnir-qa@latestOr install globally:
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.
- Check your runtime with
node --version— use Node.js 22.18 or later. - Run
npx mjolnir-qa@6.1.0from that repository root. - Read the prioritized findings. Each gives you a rule ID, file location, evidence, and a suggested fix.
- 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:
- uses: Sergey-Bar/Mjolnir@v6
with:
scope: changed
fail-on: errorPin @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
| Command | What it does |
|---|---|
mjolnir | Full-repo scan + worthiness score |
mjolnir --scope changed | Only what your branch introduced — the CI form |
mjolnir ci install | Generate the advisory PR workflow |
mjolnir explain QA-CI-001 | What / why / fix + measured or unmeasured state |
mjolnir explain --list --unmeasured | The rules running on assumption, not measurement |
mjolnir --json / --format sarif | Machine-readable / GitHub Code Scanning |
mjolnir --include-warn | Also run WARN-tier rules (higher FP risk) |
When something's flaky
| Command | What 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
▍▞ 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.