Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oven-sh/bun --skill writing-dev-server-tests -a claude-code
Open on GitHub

What 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.ts that checks hot-reload when a CSS file changes
  • Add a test to bundle.test.ts for a dynamic-import bundling bug in the dev server
  • Create a test in esm.test.ts using devTest and dev.patch to 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-code

2Manually: put the files in place

~/.claude/skills/writing-dev-server-tests/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/writing-dev-server-tests/

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

Similar skills

All skills for Testing and QA →

Project sponsors

Companies that keep this analytics open