writing-dev-server-tests — Claude Code skill for HMR and dev server tests
writing-dev-server-tests — a skill for Claude Code and five other platforms that teaches the agent to write hot-reload and dev server tests inside test/bake/. Kicks in when you create or edit bundling, HMR, or DevServer tests.
MIT 1 installs ★ 96,817 updated 2026-10-29
npx skills add oven-sh/bun --skill writing-dev-server-tests -a claude-codeWhat writing-dev-server-tests does
The skill hands the agent the layout of the test harness from the oven-sh/bun repository: bake-harness.ts, client-fixture.mjs, and the dev/ folder with files split by concern — CSS, ESM, React SPA, source maps, HTML, plugins, and ecosystem compatibility.
The core primitive is devTest, which takes an initial filesystem snapshot and an async test body receiving a dev object. dev.fetch() makes HTTP requests against the running server; dev.write, dev.patch, and dev.delete mutate files and block until hot-reload finishes — that is why node:fs has no place here. The Client object from dev.client() checks console output and catches full page reloads.
Module resolution errors are covered through the errors option on both dev.client() and the filesystem mutation methods: pass the expected error string, and the test fails if it does not appear. Omitting errors when a broken import is expected lets the test pass silently despite the failure.
What it helps with
- Write an HMR test that verifies an HTML file updates after a content change
- Assert that deleting a module produces the correct resolution error string
- Add a CSS bundling test for the Bun dev server
- Cover a React SPA scenario with react-refresh and server components
- Run one scenario in both dev and production mode using
devAndProductionTest
Example prompts for the agent
- Write a test in
test/bake/dev/css.test.tsthat checks hot-reload when a CSS file changes - Add a test to
bundle.test.tsfor a dynamic-import bundling bug in the dev server - Create a test in
esm.test.tsusingdevTestanddev.patchto verify ESM module rebuilds
How to install writing-dev-server-tests
1Skills CLI (Vercel)
npx skills add oven-sh/bun --skill writing-dev-server-tests -a claude-code2Manually: put the files in place
~/.claude/skills/writing-dev-server-tests/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/writing-dev-server-tests/
1Skills CLI (Vercel)
npx skills add oven-sh/bun --skill writing-dev-server-tests -a codex2Manually: put the files in place
.agents/skills/writing-dev-server-tests/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oven-sh/bun --skill writing-dev-server-tests -a cursor2Manually: put the files in place
.cursor/skills/writing-dev-server-tests/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oven-sh/bun .claude/skills/writing-dev-server-tests2Manually: put the files in place
.github/skills/writing-dev-server-tests/SKILL.md1Skills CLI (Vercel)
npx skills add oven-sh/bun --skill writing-dev-server-tests -a gemini-cli2Platform CLI
gemini skills install https://github.com/oven-sh/bun --path .claude/skills/writing-dev-server-testsManually: put the files in place
.devin/skills/writing-dev-server-tests/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oven-sh/bun --skill writing-dev-server-tests -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about writing-dev-server-tests
How do I install writing-dev-server-tests in Claude Code?
Run npx skills add oven-sh/bun --skill writing-dev-server-tests -a claude-code. The skill file lands at ~/.claude/skills/writing-dev-server-tests/SKILL.md.
What does the writing-dev-server-tests skill do?
It gives the agent the structure of Bun's dev server and HMR test harness: which utility files to import, how devTest, Dev, and Client work, and how to test module resolution errors.
Why must tests use dev.write instead of node:fs?
dev.write, dev.patch, and dev.delete wait for hot-reload to complete before the test continues. Writing files directly through node:fs skips that wait, so assertions run against stale state.
Source text
SKILL.md · MIT
---
name: writing-dev-server-tests
description: Guides writing HMR/Dev Server tests in test/bake/. Use when creating or modifying dev server, hot reloading, or bundling tests.
---
# Writing HMR/Dev Server Tests
Dev server tests validate hot-reloading robustness and reliability.
## File Structure
- `test/bake/bake-harness.ts` - shared utilities: `devTest`, `prodTest`, `devAndProductionTest`, `Dev` class, `Client` class
- `test/bake/client-fixture.mjs` - subprocess for `Client` (page loading, IPC queries)
- `test/bake/dev/*.test.ts` - dev server and hot reload tests
- `test/bake/dev-and-prod.ts` - tests running on both dev and production mode
## Test Categories
- `bundle.test.ts` - DevServer-specific bundling bugs
- `css.test.ts` - CSS bundling issues
- `plugins.test.ts` - development mode plugins
- `ecosystem.test.ts` - library compatibility (prefer concrete bugs over full package tests)
- `esm.test.ts` - ESM features in development
- `html.test.ts` - HTML file handling
- `react-spa.test.ts` - React, react-refresh transform, server components
- `sourcemap.test.ts` - source map correctness
## devTest Basics
```ts
import { devTest, emptyHtmlFile } from "../bake-harness";
devTest("html file is watched", {
files: {
"index.html": emptyHtmlFile({
scripts: ["/script.ts"],
body: "<h1>Hello</h1>",
}),
"script.ts": `console.log("hello");`,
},
async test(dev) {
await dev.fetch("/").expect.toInclude("<h1>Hello</h1>");
await dev.patch("index.html", { find: "Hello", replace: "World" });
await dev.fetch("/").expect.toInclude("<h1>World</h1>");
await using c = await dev.client("/");
await c.expectMessage("hello");
await c.expectReload(async () => {
await dev.patch("index.html", { find: "World", replace: "Bar" });
});
await c.expectMessage("hello");
},
});
```
## Key APIs
- **`files`**: Initial filesystem state
- **`dev.fetch()`**: HTTP requests
- **`dev.client()`**: Opens browser instance
- **`dev.write/patch/delete`**: Filesystem mutations (wait for hot-reload automatically)
- **`c.expectMessage()`**: Assert console.log output
- **`c.expectReload()`**: Wrap code that causes hard reload
**Important**: Use `dev.write/patch/delete` instead of `node:fs` - they wait for hot-reload.
## Testing Errors
```ts
devTest("import then create", {
files: {
"index.html": `<!DOCTYPE html><html><head></head><body><script type="module" src="/script.ts"></script></body></html>`,
"script.ts": `import data from "./data"; console.log(data);`,
},
async test(dev) {
const c = await dev.client("/", {
errors: ['script.ts:1:18: error: Could not resolve: "./data"'],
});
await c.expectReload(async () => {
await dev.write("data.ts", "export default 'data';");
});
await c.expectMessage("data");
},
});
```
Specify expected errors with the `errors` option:
```ts
await dev.delete("other.ts", {
errors: ['index.ts:1:16: error: Could not resolve: "./other"'],
});
```
© oven-sh · MIT · oven-sh/bun