find-and-run-tests
How to find, build, and run tests in workerd. Covers wd-test, kjtest target naming, bazel query patterns, and common flags. Also covers parent project integration tests if workerd is used as a submodule. Load this skill when you need to locate or run a test and aren't sure of the exact target name or invocation.
- 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 find-and-run-tests- 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 find-and-run-tests 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.
Finding and Running Tests
workerd Tests
Test types
| Type | File extension | BUILD macro | Target suffix |
|---|---|---|---|
| JS/TS integration | .wd-test | wd_test() | None (target name = rule name) |
| C++ unit | *-test.c++ | kj_test() | None |
Finding targets
# Find test targets in a directory
bazel query 'kind("test", //src/workerd/api/tests:*)' --output label
# Find test targets matching a name
bazel query 'kind(".*_test", //src/workerd/...)' --output label 2>/dev/null | grep -i '<name>'
# Find tests that depend on a source file
bazel query 'rdeps(//src/..., //src/workerd/io:trace-stream, 1)' --output label 2>/dev/null | grep -i test
Running
# Stream test output (preferred for debugging)
bazel test //src/workerd/api/tests:url-test --test_output=streamed
# Run with fresh results (no cache)
bazel test //target --test_output=streamed --nocache_test_results
# Run specific test case within a kj_test
bazel test //target --test_arg='-f' --test_arg='test case name'
Common flags
| Flag | Purpose |
|---|---|
--test_output=streamed | Stream test output to terminal in real time |
--nocache_test_results | Force re-run, don't use cached results |
--test_timeout=120 | Override default test timeout (seconds) |
Parent Project Integration Tests
If workerd is used as a submodule in a parent project, that project may have its own integration test framework with different conventions. Load the parent-project-skills skill to discover those conventions.
General principles that apply to any integration test framework
Target naming with variant suffixes. Some test macros generate multiple targets from a single source file by appending variant suffixes (e.g., @, @all-autogates, @force-sharding). If bazel says "is a source file, nothing will be built" or "No test targets were found", you likely need a suffix. Use bazel query 'kind("test", //path:*)' to discover the actual runnable target names.
Cached results hide changes. Always use --nocache_test_results when re-running after modifying test files or source code. Without it, bazel returns stale cached results with stale logs.
Verify the feature actually ran. After a test passes, search the test output for feature-specific evidence (script names, process types, subrequests, RPC calls). A passing test with no evidence the feature ran is not a valid test — see the test-driven-investigation skill.
Debugging test failures
- Always use
--nocache_test_resultswhen re-running after changes. - Check test logs at the path shown in bazel output:
bazel-out/.../testlogs/.../test.log - Search logs for feature-specific keywords to verify the feature actually ran.
- Subrequest mismatches (in frameworks that verify subrequests) typically show the actual vs expected request details — compare control headers carefully.
FAQ
What does the find-and-run-tests skill do?
How to find, build, and run tests in workerd. Covers wd-test, kjtest target naming, bazel query patterns, and common flags. Also covers parent project integration tests if workerd is used as a submodule. Load this skill when you need to locate or run a test and aren't sure of the exact target name or invocation.
How do I install find-and-run-tests?
Run npx skills add https://github.com/cloudflare/workerd --skill find-and-run-tests 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/find-and-run-tests/ (personal) or .claude/skills/find-and-run-tests/ (project).
Which AI agents can use find-and-run-tests?
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 find-and-run-tests 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 find-and-run-tests?
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.
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
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.
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