Honest tests
Every test maps to a spec ID, risky specs must have a test and every test must assert something. Deleting tests, removing expects and loosening matchers is blocked on pull requests, and new tests must fail on the base branch.
A Workshop 42 tool
Config-driven checks that stop coding agents from padding, weakening or bypassing your tests, docs and architecture.
npm i -D @ws42ca/guardrails
⚠ TEST-5W Weak assertions (heuristic) (1)
test/receipt.test.ts:4 "ORDER-01 formats the receipt total":
only tautological assertions (toBeTruthy).
Assert the exact value.
fix: Assert on the observable result (returned value,
written data, response status).
✖ TEST-7 No test weakening (1)
test/receipt.test.ts:4 "ORDER-01 formats the receipt total"
lost 1 expect() call(s). Restore them.
fix: Restore the test/assertion/threshold. Deleting
base-branch tests needs the tests-removed-approved
label from a code owner.
FAIL: 1 blocking, 1 warnings, 0 known (diff vs main)
Left alone, a coding agent will delete the failing test, loosen an assertion, special-case the expected value, add a package that does not exist or write a new doc for every task. Guardrails blocks those shortcuts in CI and inside the agent’s own editor.
49 rules. One config file per project.
Every test maps to a spec ID, risky specs must have a test and every test must assert something. Deleting tests, removing expects and loosening matchers is blocked on pull requests, and new tests must fail on the base branch.
Product code that detects the test runner, exits early, overloads equality or hard-codes expected values is blocked. Agents stop and flag a conflict instead of bending a test, and a human has to answer before merge.
Declared import boundaries, production reachability, duplication on new code, restricted strings and no fixtures in production code. Existing violations go in a baseline that can only shrink.
New packages must exist on the npm registry, be old enough and downloaded enough, and carry no high or critical advisory. That catches package names an agent made up.
Hooks for Claude Code, Gemini CLI, Antigravity and Codex deny edits to the config, the baseline, CI files and spec-tagged tests, so the rules are not one edit away from off.
Critical user journeys are plain-language tasks a human approves. Approved journeys need an end-to-end test, and the CLI can generate and run those tests with Playwright.
Node 20 or newer.
Install it as a dev dependency, scaffold the files, record the baseline and run the checks. init never overwrites an existing file unless you pass --force.
It writes guardrails.config.json, AGENTS.md with one-line CLAUDE.md and GEMINI.md pointers, CODEOWNERS, a starter GitHub Actions workflow and the agent hook and MCP files.
npm i -D @ws42ca/guardrails
# scaffold config, AGENTS.md, CODEOWNERS, CI workflow and agent hooks
npx guardrails init --owner @your-github-handle --base main
# record today's violations; the baseline can only shrink from here
npx guardrails baseline
# run the checks (exit code 1 means a blocking finding)
npx guardrails check
# on a branch, also run the diff rules
npx guardrails check --base origin/main --fails-on-baseDescribe the behaviours you promise (specs), how strict each part of the code is (tiers) and which layers may not touch. Unknown keys are an error, so a typo cannot quietly turn a rule off.
{
"version": 1,
"baseBranch": "main",
"sourceRoots": ["src"],
"tiers": {
"T1": ["src/payments/**"],
"T3": ["src/**"]
},
"specs": {
"items": {
"ORDER-01": {
"tier": "T1",
"behaviour": "A paid order sends a receipt email"
}
}
},
"architecture": {
"entries": ["src/main.ts"],
"forbidden": [
{ "name": "ui-not-db", "from": ["src/ui/**"], "to": ["src/db/**"],
"message": "Go through the service layer" }
]
}
}Critical user journeys (CUJs).
A journey is a short, plain-language task a real visitor does, such as “sends an enquiry through the contact form and sees a confirmation”. Unit tests can all pass while that form is broken.
run list becomes Playwright tests you can run against a local preview, a staging site or production.{
"journeys": {
"items": {
"CUJ-CHECKOUT": {
"title": "Visitor buys a product and sees a confirmation",
"priority": "P0",
"steps": [
"Open the shop", "Add an item", "Pay", "See the confirmation"
],
"specs": ["ORDER-01"],
"routes": ["/shop"],
"run": [
{ "goto": "/shop" },
{ "click": { "role": "button", "name": "Add to cart" } },
{ "expectText": "Order confirmed" }
]
}
}
}
}# a human approves; agents can only draft
npx guardrails journeys approve CUJ-CHECKOUT
# turn journeys into Playwright tests and run them
npx guardrails journeys scaffold
npx guardrails journeys generate-tests
npx guardrails journeys run --base-url http://localhost:4321The same checks, with the base branch.
Run the checks on every pull request with the base branch so the diff rules apply: no test weakening, new tests fail on base and new dependencies are verified. The job writes a Markdown report to the run summary.
guardrails:tests-removed-approved, guardrails:journeys-approved and guardrails:config-approved let a code owner approve a specific exception.guardrails affected keep pull requests fast.name: Guardrails
on:
pull_request:
types: [opened, synchronize, reopened, labeled, unlabeled]
push:
branches: [main]
jobs:
guardrails:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: actions/setup-node@v4
with: { node-version: 20, cache: npm }
- run: npm ci
- name: guardrails
env:
GUARDRAILS_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
run: |
ARGS=""
if [ "${{ github.event_name }}" = "pull_request" ]; then
ARGS="--base origin/${{ github.base_ref }} --fails-on-base"
fi
npx guardrails report --format markdown $ARGS >> "$GITHUB_STEP_SUMMARY" || true
npx guardrails check $ARGSHooks, an MCP server and a skill.
The MCP server lets an agent list specs, validate a test before writing it, run the checks, see surviving mutants and flag a conflict. It can read journeys but has no tool to approve one.
It works with Claude Code, Gemini CLI, Antigravity and Codex. A skill file in the package tells an agent how to work under the rules.
claude mcp add guardrails --scope project -- \
npx -y -p @ws42ca/guardrails guardrails-mcp{
"mcpServers": {
"guardrails": {
"command": "npx",
"args": ["-y", "-p", "@ws42ca/guardrails", "guardrails-mcp"],
"cwd": "."
}
}
}[mcp_servers.guardrails]
command = "npx"
args = ["--no-install", "guardrails-mcp"]
[shell_environment_policy.set]
GUARDRAILS_AGENT = "codex"MIT licensed · Node 20+ · npm package @ws42ca/guardrails