find-and-run-tests

✓ Official★ 8,400

by cloudflare · part of cloudflare/workerd

How to find, build, and run tests in workerd. Covers wd-test, kj_test target naming, bazel query patterns, and common flags. Also covers parent project…

🔥🔥✓ VerifiedFreeQuick setup

#cloud #git

🔒 Repo-maintenance skill. It exists to help maintain cloudflare/workerd itself — it's only useful if you contribute code to that project.

How to find, build, and run tests in workerd. Covers wd-test, kj_test target naming, bazel query patterns, and common flags. Also covers parent project…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

name: find-and-run-tests description: How to find, build, and run tests in workerd. Covers wd-test, kj_test 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.

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

Copy & paste — that's it

# 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

Copy & paste — that's it

# 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_results when 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.