writing-bundler-tests

Source excerpt starting at line 1.

1---2name: writing-bundler-tests3description: Guides writing bundler tests using itBundled/expectBundled in test/bundler/. Use when creating or modifying bundler, transpiler, or code transformation tests.4---5 6# Writing Bundler Tests7 8Bundler tests use `itBundled()` from `test/bundler/expectBundled.ts` to test Bun's bundler.9 10## Basic Usage11 12```typescript13import { describe } from "bun:test";14import { itBundled, dedent } from "./expectBundled";15 16describe("bundler", () => {17  itBundled("category/TestName", {18    files: {19      "index.js": `console.log("hello");`,20    },21    run: {22      stdout: "hello",23    },24  });25});26```27 28Test ID format: `category/TestName` (e.g., `banner/CommentBanner`, `minify/Empty`)29 30## File Setup31 32```typescript33{34  files: {35    "index.js": `console.log("test");`,36    "lib.ts": `export const foo = 123;`,37    "nested/file.js": `export default {};`,38  },39  entryPoints: ["index.js"],  // defaults to first file40  runtimeFiles: {             // written AFTER bundling41    "extra.js": `console.log("added later");`,42  },43}44```45 46## Bundler Options47 48```typescript49{50  outfile: "/out.js",51  outdir: "/out",52  format: "esm" | "cjs" | "iife",53  target: "bun" | "browser" | "node",54 55  // Minification56  minifyWhitespace: true,57  minifyIdentifiers: true,58  minifySyntax: true,59 60  // Code manipulation61  banner: "// copyright",62  footer: "// end",63  define: { "PROD": "true" },64  external: ["lodash"],65 66  // Advanced67  sourceMap: "inline" | "external",68  splitting: true,69  treeShaking: true,70  drop: ["console"],71}72```73 74## Runtime Verification75 76```typescript77{78  run: {79    stdout: "expected output",      // exact match80    stdout: /regex/,                // pattern match81    partialStdout: "contains this", // substring82    stderr: "error output",83    exitCode: 1,84    env: { NODE_ENV: "production" },85    runtime: "bun" | "node",86 87    // Runtime errors88    error: "ReferenceError: x is not defined",89  },90}91```92 93## Bundle Errors/Warnings94 95```typescript96{97  bundleErrors: {98    "/file.js": ["error message 1", "error message 2"],99  },100  bundleWarnings: {101    "/file.js": ["warning message"],102  },103}104```105 106## Dead Code Elimination (DCE)107 108Add markers in source code:109 110```javascript111// KEEP - this should survive112const used = 1;113 114// REMOVE - this should be eliminated115const unused = 2;116```117 118```typescript119{120  dce: true,121  dceKeepMarkerCount: 5,  // expected KEEP markers122}123```124 125## Capture Pattern126 127Verify exact transpilation with `capture()`:128 129```typescript130itBundled("string/Folding", {131  files: {132    "index.ts": `capture(\`\${1 + 1}\`);`,133  },134  capture: ['"2"'], // expected captured value135  minifySyntax: true,136});137```138 139## Post-Bundle Assertions140 141```typescript142{143  onAfterBundle(api) {144    api.expectFile("out.js").toContain("console.log");145    api.assertFileExists("out.js");146 147    const content = api.readFile("out.js");148    expect(content).toMatchSnapshot();149 150    const values = api.captureFile("out.js");151    expect(values).toEqual(["2"]);152  },153}154```155 156## Common Patterns157 158**Simple output verification:**159 160```typescript161itBundled("banner/Comment", {162  banner: "// copyright",163  files: { "a.js": `console.log("Hello")` },164  onAfterBundle(api) {165    api.expectFile("out.js").toContain("// copyright");166  },167});168```169 170**Multi-file CJS/ESM interop:**171 172```typescript173itBundled("cjs/ImportSyntax", {174  files: {175    "entry.js": `import lib from './lib.cjs'; console.log(lib);`,176    "lib.cjs": `exports.foo = 'bar';`,177  },178  run: { stdout: '{"foo":"bar"}' },179});180```181 182**Error handling:**183 184```typescript185itBundled("edgecase/InvalidLoader", {186  files: { "index.js": `...` },187  bundleErrors: {188    "index.js": ["Unsupported loader type"],189  },190});191```192 193## Test Organization194 195```text196test/bundler/197├── bundler_banner.test.ts198├── bundler_string.test.ts199├── bundler_minify.test.ts200├── bundler_cjs.test.ts201├── bundler_edgecase.test.ts202├── bundler_splitting.test.ts203├── css/204├── transpiler/205└── expectBundled.ts206```207 208## Running Tests209 210```bash211bun bd test test/bundler/bundler_banner.test.ts212BUN_BUNDLER_TEST_FILTER="banner/Comment" bun bd test bundler_banner.test.ts213BUN_BUNDLER_TEST_DEBUG=1 bun bd test bundler_minify.test.ts214```215 216## Key Points217 218- Use `dedent` for readable multi-line code219- File paths are relative (e.g., `/index.js`)220- Use `capture()` to verify exact transpilation results221- Use `.toMatchSnapshot()` for complex outputs222- Pass array to `run` for multiple test scenarios223