| name | modifying-test-components |
| description | Building or modifying test WASM components in test-components/. Use when a test component needs to be rebuilt, a new test component is needed, or SDK changes require downstream test component rebuilds. |
Modifying Test Components
Worker executor tests, integration tests, and CLI integration tests use built WASM artifacts from test-components/. These .wasm files are no longer checked into the repository; compiling the components needed by the selected tests is a separate step before running those tests.
Key Rules
- Do not rebuild more test components than necessary. Prefer rebuilding only the components required by the selected tests.
- Only rebuild if the test component has its own
AGENTS.md with build instructions. If it doesn't, the component cannot be rebuilt by you.
- SDK changes require rebuilding dependent test components. If you modify
sdks/rust/ or sdks/ts/, you must rebuild any test components that use the changed SDK.
When to Rebuild
| Change | Action Required |
|---|
| Modifying a test component's source code | Rebuild that component (if it has an AGENTS.md) |
Modifying sdks/rust/ (golem-rust) | Rebuild Rust test components that depend on it |
Modifying sdks/ts/ (golem-ts-sdk) | Rebuild agent template WASM first, then TS test components |
| Modifying WIT interfaces | Run cargo make wit, then rebuild affected components |
| Running worker executor / integration / CLI integration tests that depend on missing test-component WASMs | Rebuild the specific components those tests use before running the tests |
| No source changes and required WASMs already exist | Do not rebuild |
Rebuilding a Test Component
Step 1: Check for build instructions
cat test-components/<component-name>/AGENTS.md
If no AGENTS.md exists, stop — you cannot rebuild this component.
Step 2: Follow the component's AGENTS.md
Each component's AGENTS.md contains specific build instructions. Follow them exactly.
Important: When running golem build (or ../../target/debug/golem build) for test components, always pass --yes to automatically confirm dependency/configuration updates without interactive prompts.
For Rust Golem application test components, rebuild with the release profile so the golem-temp/agents/*_release.wasm artifact used by tests is regenerated. Use -P release and force the build if you need to refresh an existing artifact:
../../target/debug/golem build -P release --force-build --yes
If a component's AGENTS.md gives a different component-specific command, follow it, but make sure Rust test-component rebuilds produce the release artifact unless the task explicitly asks for a debug build.
TS SDK Change Rebuild Chain
When modifying the TypeScript SDK, you must follow this exact rebuild order:
1. Build the TS SDK packages
cd sdks/ts
npx pnpm install
npx pnpm run build
2. Rebuild the agent template WASM
This step is required before rebuilding any TS test components. The agent template embeds the SDK runtime.
cd sdks/ts
npx pnpm run build-agent-template
Requires cargo-component v0.21.1 — see sdks/ts/AGENTS.md for installation.
3. Rebuild affected TS test components
Follow each component's AGENTS.md for specific instructions.
Rust SDK Change Rebuild Chain
When modifying the Rust SDK:
1. Build the Rust SDK
cargo build -p golem-rust
cargo build -p golem-rust-macro
2. Rebuild affected Rust test components
Follow each component's AGENTS.md for specific instructions. Rust Golem application test components should be rebuilt with golem build -P release --force-build --yes; Rust test components that are not Golem applications may use cargo component build or another component-specific command with a local path dependency on golem-rust.
Finding Test Components
Test components live in test-components/. To find which ones have build instructions:
ls test-components/*/AGENTS.md
To find which test components depend on a specific SDK, check their Cargo.toml (Rust) or package.json (TS) for SDK references.
Checklist
- Confirmed the component has an
AGENTS.md with build instructions
- If SDK was changed: rebuilt SDK first
- If TS SDK was changed: rebuilt agent template WASM before components
- Followed the component's specific
AGENTS.md build instructions
- Confirmed the expected
.wasm artifact now exists under test-components/; for Rust Golem application components, confirm the golem-temp/agents/*_release.wasm artifact was updated
- Ran the relevant tests after the rebuild (
cargo make worker-executor-tests, cargo make integration-tests, or cargo make cli-integration-tests)
