CLAUDE.md

1To run tests:
2 
3```sh
4bun bd test <...test file>
5```
6 
7To run a command with your debug build of Bun:
8 
9```sh
10bun bd <...cmd>
11```
12 
13Note that compiling Bun may take up to 2.5 minutes. It is slow!
14 
15**CRITICAL**: Do not use `bun test` to run tests. It will not have your changes. `bun bd test <...test file>` is the correct command, which compiles your code automatically.
16 
17## Testing style
18 
19Use `bun:test` with files that end in `*.test.{ts,js,jsx,tsx,mjs,cjs}`. If it's a test/js/node/test/{parallel,sequential}/\*.js without a .test.extension, use `bun bd <file>` instead of `bun bd test <file>` since those expect exit code 0 and don't use bun's test runner.
20 
21- **Do not write flaky tests**. Unless explicitly asked, **never wait for time to pass in tests**. Always wait for the condition to be met instead of waiting for an arbitrary amount of time. **Never use hardcoded port numbers**. Always use `port: 0` to get a random port.
22- **Prefer concurrent tests over sequential tests**: When multiple tests in the same file spawn processes or write files, make them concurrent with `test.concurrent` or `describe.concurrent` unless it's very difficult to make them concurrent.
23 
24### Spawning processes
25 
26#### Spawning Bun in tests
27 
28When spawning Bun processes, use `bunExe` and `bunEnv` from `harness`. This ensures the same build of Bun is used to run the test and ensures debug logging is silenced.
29 
30##### Use `-e` for single-file tests
31 
32```ts
33import { bunEnv, bunExe, tempDir } from "harness";
34import { test, expect } from "bun:test";
35 
36test("single-file test spawns a Bun process", async () => {
37  await using proc = Bun.spawn({
38    cmd: [bunExe(), "-e", "console.log('Hello, world!')"],
39    env: bunEnv,
40  });
41 
42  const [stdout, stderr, exitCode] = await Promise.all([
43    proc.stdout.text(),
44    proc.stderr.text(),
45    proc.exited,
46  ]);
47 
48  expect(stderr).toBe("");
49  expect(stdout).toBe("Hello, world!\n");
50  expect(exitCode).toBe(0);
51});
52```
53 
54##### When multi-file tests are required:
55 
56```ts
57import { bunEnv, bunExe, tempDir } from "harness";
58import { test, expect } from "bun:test";
59 
60test("multi-file test spawns a Bun process", async () => {
61  // If a test MUST use multiple files:
62  using dir = tempDir("my-test-prefix", {
63    "my.fixture.ts": `
64      import { foo } from "./foo.ts";
65      foo();
66    `,
67    "foo.ts": `
68      export function foo() {
69        console.log("Hello, world!");
70      }
71    `,
72  });
73 
74  await using proc = Bun.spawn({
75    cmd: [bunExe(), "my.fixture.ts"],
76    env: bunEnv,
77    cwd: String(dir),
78  });
79 
80  const [stdout, stderr, exitCode] = await Promise.all([
81 
82    // ReadableStream in Bun supports:
83    //  - `await stream.text()`
84    //  - `await stream.json()`
85    //  - `await stream.bytes()`
86    //  - `await stream.blob()`
87    proc.stdout.text(),
88    proc.stderr.text(),
89 
90    proc.exitCode,
91  ]);
92 
93  expect(stdout).toBe("Hello, world!");
94  expect(stderr).toBe("");
95  expect(exitCode).toBe(0);
96```
97 
98When a test file spawns a Bun process, we like for that file to end in `*-fixture.ts`. This is a convention that helps us identify the file as a test fixture and not a test itself.
99 
100Generally, `await using` or `using` is a good idea to ensure proper resource cleanup. This works in most Bun APIs like Bun.listen, Bun.connect, Bun.spawn, Bun.serve, etc.
101 
102#### Async/await in tests
103 
104Prefer async/await over callbacks.
105 
106When callbacks must be used and it's just a single callback, use `Promise.withResolvers` to create a promise that can be resolved or rejected from a callback.
107 
108```ts
109const ws = new WebSocket("ws://localhost:8080");
110const { promise, resolve, reject } = Promise.withResolvers<void>(); // Can specify any type here for resolution value
111ws.onopen = resolve;
112ws.onclose = reject;
113await promise;
114```
115 
116If it's several callbacks, it's okay to use callbacks. We aren't a stickler for this.
117 
118### No timeouts
119 
120**CRITICAL**: Do not set a timeout on tests. Bun already has timeouts.
121 
122### Use port 0 to get a random port
123 
124Most APIs in Bun support `port: 0` to get a random port. Never hardcode ports. Avoid using your own random port number function.
125 
126### Creating temporary files
127 
128Use `tempDirWithFiles` to create a temporary directory with files.
129 
130```ts
131import { tempDir } from "harness";
132import path from "node:path";
133 
134test("creates a temporary directory with files", () => {
135  using dir = tempDir("my-test-prefix", {
136    "file.txt": "Hello, world!",
137  });
138 
139  expect(await Bun.file(path.join(String(dir), "file.txt")).text()).toBe(
140    "Hello, world!",
141  );
142});
143```
144 
145### Strings
146 
147To create a repetitive string, use `Buffer.alloc(count, fill).toString()` instead of `"A".repeat(count)`. "".repeat is very slow in debug JavaScriptCore builds.
148 
149### Test Organization
150 
151- Use `describe` blocks for grouping related tests
152- **Add tests to the existing test file for the code you're changing** — do not create a new file. Tests are organized by module (e.g., `/test/js/bun/`, `/test/js/node/`, `/test/js/web/`).
153- `/test/regression/issue/${issueNumber}.test.ts` is **only** for bugs that have a GitHub issue number **and** are true regressions (worked in a previous release, then broke). An issue number alone does not qualify — if it was never correct, put the test in the module's existing test file instead.
154- Integration tests are in `/test/integration/`
155 
156### Nested/complex object equality
157 
158Prefer usage of `.toEqual` rather than many `.toBe` assertions for nested or complex objects.
159 
160<example>
161 
162BAD (try to avoid doing this):
163 
164```ts
165expect(result).toHaveLength(3);
166expect(result[0].optional).toBe(null);
167expect(result[1].optional).toBe("middle-value"); // CRITICAL: middle item's value must be preserved
168expect(result[2].optional).toBe(null);
169```
170 
171**GOOD (always prefer this):**
172 
173```ts
174expect(result).toEqual([
175  { optional: null },
176  { optional: "middle-value" }, // CRITICAL: middle item's value must be preserved
177  { optional: null },
178]);
179```
180 
181</example>
182 
183### Common Imports from `harness`
184 
185```ts
186import {
187  bunExe, // Path to Bun executable
188  bunEnv, // Environment variables for Bun
189  tempDirWithFiles, // Create temporary test directories with files
190  tmpdirSync, // Create empty temporary directory
191  isMacOS, // Platform checks
192  isWindows,
193  isPosix,
194  gcTick, // Trigger garbage collection
195  withoutAggressiveGC, // Disable aggressive GC for performance tests
196} from "harness";
197```
198 
199### Error Testing
200 
201Always check exit codes and test error scenarios:
202 
203```ts
204test("handles errors", async () => {
205  await using proc = Bun.spawn({
206    cmd: [bunExe(), "run", "invalid.js"],
207    env: bunEnv,
208  });
209 
210  const exitCode = await proc.exited;
211  expect(exitCode).not.toBe(0);
212 
213  // For synchronous errors
214  expect(() => someFunction()).toThrow("Expected error message");
215});
216```
217 
218### Avoid dynamic import & require
219 
220**Only** use dynamic import or require when the test is specifically testing something relataed to dynamic import or require. Otherwise, **always use module-scope import statements**.
221 
222**BAD, do not do this**:
223 
224```ts
225test("foo", async () => {
226  // BAD: Unnecessary usage of dynamic import.
227  const { readFile } = await import("node:fs");
228 
229  expect(await readFile("ok.txt")).toBe("");
230});
231```
232 
233**GOOD, do this:**
234 
235```ts
236import { readFile } from "node:fs";
237test("foo", async () => {
238  expect(await readFile("ok.txt")).toBe("");
239});
240```
241 
242### Test Utilities
243 
244- Use `describe.each()` for parameterized tests
245- Use `toMatchSnapshot()` for snapshot testing
246- Use `beforeAll()`, `afterEach()`, `beforeEach()` for setup/teardown
247- Track resources (servers, clients) in arrays for cleanup in `afterEach()`
248