bazel-test-hygiene
Mandatory rules for running bazel tests during development. Load this skill before running any bazel test command, especially when validating fixes or verifying regression tests. Prevents false confidence from cached results, filter flags that silently match nothing, and partial test runs that miss breakage.
- Installs
- 50
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cloudflare/workerd --skill bazel-test-hygiene- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads bazel-test-hygiene automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Bazel Test Hygiene
The Three Rules
1. Always disable caching
bazel test //... --nocache_test_results
Why: Bazel's action cache can serve stale test binaries even after you edit source files. Without --nocache_test_results, you may be running the OLD binary and seeing OLD results. This is not hypothetical — it has caused real false-positive/false-negative confusion in this repo.
Always include --nocache_test_results. No exceptions.
2. Keep it simple — no filter flags
Do NOT use --test_arg='-f' or similar filter flags to run individual test cases.
Why: KJ test's -f flag silently passes when zero tests match. If you typo the filter or the test name changes, bazel reports "PASSED" with zero tests actually run. This gives completely false confidence.
Run the full test target. If you need to check a specific test, look for its name in the full output. If the full suite is too slow, run the specific test target (e.g., //src/workerd/api:streams/standard-test@), not a filtered subset within a target.
3. Run the full suite before claiming done
A single test target passing does not mean you haven't broken something else. Fixes to shared code (queue.c++, standard.c++, common.h) can break tests in completely different directories.
Before claiming any fix is complete:
bazel test //... --nocache_test_results
Check the final summary line: Executed N out of N tests: N tests pass. All N must match. If any test fails, the fix is not done.
Red-Green Verification for Regression Tests
When writing a regression test for a bug fix, you MUST verify the test actually catches the bug:
- Green: Run
bazel test //... --nocache_test_results— all tests pass (fix in place) - Red: Remove the fix, run
bazel test //... --nocache_test_results— the new test(s) MUST fail - Green: Restore the fix, run
bazel test //... --nocache_test_results— all tests pass again
If step 2 passes (test doesn't fail without the fix), the test is not testing what you think. Go back and fix the test.
Do the red-green on the full suite, not just the one target. This catches two problems at once: (a) the regression test actually detects the bug, and (b) the fix doesn't break anything else.
Anti-Patterns
| Don't | Do instead |
|---|---|
bazel test //target (no cache flag) | bazel test //target --nocache_test_results |
--test_arg='-f' --test_arg='test name' | Run the full target, grep output for test name |
| Run one target, claim fix is done | Run //..., check all-pass summary |
| Claim "tests pass" from a previous run | Run fresh, read fresh output |
| Trust filter-based "PASSED" at face value | Check that the expected test names appear in output |
FAQ
What does the bazel-test-hygiene skill do?
Mandatory rules for running bazel tests during development. Load this skill before running any bazel test command, especially when validating fixes or verifying regression tests. Prevents false confidence from cached results, filter flags that silently match nothing, and partial test runs that miss breakage.
How do I install bazel-test-hygiene?
Run npx skills add https://github.com/cloudflare/workerd --skill bazel-test-hygiene in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/bazel-test-hygiene/ (personal) or .claude/skills/bazel-test-hygiene/ (project).
Which AI agents can use bazel-test-hygiene?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is bazel-test-hygiene safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains bazel-test-hygiene?
It is published by cloudflare in cloudflare/workerd, and it is an official skill from the maker of the technology it covers. It has 50 recorded installs.
More from cloudflare/workerd
verification-before-completion
cloudflare/workerd
Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
rust-review
cloudflare/workerd
Rust code review for workerd. Covers CXX FFI safety, unsafe code patterns, JSG resource conventions, error handling, and a review checklist adapted from the C++ review skills. Load this skill when reviewing Rust code in src/rust/.
dad-jokes
cloudflare/workerd
After completing any task that took more than 5 tool calls, or after long-running builds/tests finish, load this skill and deliver a dad joke to lighten the mood. Also load before any user-requested joke, pun, or limerick. Never improvise jokes without loading this skill first.
markdown-drafts
cloudflare/workerd
Use markdown formatting when drafting content intended for external systems (GitHub issues/PRs, Jira tickets, wiki pages, design docs, etc.) so formatting is preserved when the user copies it. Load this skill before producing any draft the user will paste elsewhere.
workerd-api-review
cloudflare/workerd
Performance optimization, API design & compatibility, security vulnerabilities, and standards spec compliance for workerd code review. Covers tcmalloc-aware perf analysis, compat flags, autogates, web standards adherence, and security patterns. Load this skill when reviewing API changes, performance-sensitive code, security-relevant code, or standards implementations.
receiving-code-review
cloudflare/workerd
Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
Popular testing & qa skills
tdd
mattpocock/skills
Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.
grilling
mattpocock/skills
Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
migrate-to-shoehorn
mattpocock/skills
Migrate test files from as type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace as in tests, or needs partial test data.
run-train
lllllllama/rigorpilot-skills
Rigor Train skill for deep learning research repositories. Use when a documented or selected training command should be run conservatively for startup verification, short-run verification, full kickoff, or resume, with command, config, seed, log, checkpoint, status, and metric evidence written to standardized trainoutputs/. Do not use for environment setup, exploratory sweeps, speculative idea implementation, or end-to-end orchestration.
test-driven-development
obra/superpowers
Use when implementing any feature or bugfix, before writing implementation code
finishing-a-development-branch
obra/superpowers
Use when implementation is complete, all tests pass, and you need to decide how to integrate the work