// 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.
Load when working with the module registry in workerd — reading, modifying, debugging, or reviewing module resolution, compilation, evaluation, or registration code. Provides pointers to three reference documents covering the legacy registry, V8 module internals, and the new registry design.
Guidelines for posting pull request review comments via GitHub CLI, including suggested edits format, handling unresolved comments, etiquette, and report/issue tracking. Load this skill when reviewing a PR via GitHub and posting inline comments.
Structured scratch tracking document for investigation state during bug hunts - prevents re-reading code, losing context, and rabbit holes; maintains external memory so you don't re-derive conclusions
Step-by-step guide for updating the V8 JavaScript engine in workerd, including patch rebasing, dependency updates, integrity hashes, and verification. Load this skill when performing or assisting with a V8 version bump.
KJ/workerd C++ style guidelines for code review. Covers naming, type usage, memory management, error handling, inheritance, constness, and formatting conventions. Load this skill when reviewing or writing C++ code in the workerd codebase.
JS/TS style guidelines and review checklist for workerd. Covers TypeScript strictness, import conventions, export patterns, private field syntax, error handling, feature gating, and test structure. Load this skill when reviewing or writing JavaScript or TypeScript code in src/node/, src/cloudflare/, or JS/TS test files under src/workerd/.
| name | bazel-test-hygiene |
| description | 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. |
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.
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.
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.
When writing a regression test for a bug fix, you MUST verify the test actually catches the bug:
bazel test //... --nocache_test_results — all tests pass (fix in place)bazel test //... --nocache_test_results — the new test(s) MUST failbazel test //... --nocache_test_results — all tests pass againIf 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.
| 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 |