DOM Testing

Test browser APIs, DOM elements, and React components in Bun using happy-dom and React Testing Library.

Bun’s test runner is compatible with popular DOM and component testing libraries. The recommended setup uses happy-dom to simulate a browser environment.

Setting up happy-dom

happy-dom implements a complete set of HTML and DOM APIs in JavaScript, making it possible to run browser-targeting code in Bun without a real browser.

1. Install the package

   bun add -d @happy-dom/global-registrator
   
2. Create a preload file

   Create happydom.ts at the root of your project to register the browser globals:

   happydom.ts

   import { GlobalRegistrator } from "@happy-dom/global-registrator";
   
   GlobalRegistrator.register();
   
3. Register the preload in bunfig.toml

   bunfig.toml

   [test]
   preload = ["./happydom.ts"]
   

   This executes happydom.ts before any test file runs, making document, window, and other browser globals available.

Writing DOM tests

Once happy-dom is registered, you can use browser APIs directly in your tests:

dom.test.ts

/// <reference lib="dom" />

import { test, expect } from "bun:test";

test("renders a button", () => {
  document.body.innerHTML = `<button id="submit">Submit</button>`;
  const button = document.querySelector("button");
  expect(button?.textContent).toBe("Submit");
});

test("handles click events", () => {
  let clicked = false;
  document.body.innerHTML = `<button id="btn">Click</button>`;
  const btn = document.getElementById("btn");

  btn?.addEventListener("click", () => { clicked = true; });
  btn?.click();

  expect(clicked).toBe(true);
});

Add /// <reference lib="dom" /> at the top of test files to get TypeScript type checking for browser APIs like document and window.

React Testing Library

After setting up happy-dom, install React Testing Library:

bun add -d @testing-library/react @testing-library/jest-dom

Button.test.tsx

/// <reference lib="dom" />

import { test, expect } from "bun:test";
import { render, screen, fireEvent } from "@testing-library/react";
import "@testing-library/jest-dom";

function Counter() {
  const [count, setCount] = React.useState(0);
  return (
    <div>
      <span data-testid="count">{count}</span>
      <button onClick={() => setCount(c => c + 1)}>Increment</button>
    </div>
  );
}

test("increments counter on click", () => {
  render(<Counter />);

  expect(screen.getByTestId("count")).toHaveTextContent("0");
  fireEvent.click(screen.getByRole("button", { name: "Increment" }));
  expect(screen.getByTestId("count")).toHaveTextContent("1");
});

Testing custom elements

happy-dom supports the Custom Elements API:

custom-element.test.ts

/// <reference lib="dom" />

import { test, expect } from "bun:test";

test("custom element renders content", () => {
  class AlertBox extends HTMLElement {
    constructor() {
      super();
      this.innerHTML = `<div class="alert">${this.getAttribute("message")}</div>`;
    }
  }

  customElements.define("alert-box", AlertBox);

  document.body.innerHTML = `<alert-box message="Something went wrong"></alert-box>`;
  const box = document.querySelector("alert-box");
  expect(box?.querySelector(".alert")?.textContent).toBe("Something went wrong");
});

Advanced setup

For projects that need additional globals polyfilled (e.g., ResizeObserver, matchMedia), create a more comprehensive preload file:

test-setup.ts

import { GlobalRegistrator } from "@happy-dom/global-registrator";
import "@testing-library/jest-dom";
import { afterEach } from "bun:test";
import { cleanup } from "@testing-library/react";

// Register all browser globals
GlobalRegistrator.register();

// Polyfill APIs not in happy-dom
global.ResizeObserver = class ResizeObserver {
  observe() {}
  unobserve() {}
  disconnect() {}
};

// Clean up after each test
afterEach(() => {
  cleanup();
  document.body.innerHTML = "";
});

bunfig.toml

[test]
preload = ["./test-setup.ts"]

JSDOM as an alternative

If you prefer jsdom, install it and register it similarly:

bun add -d jsdom

jsdom-setup.ts

import { JSDOM } from "jsdom";

const dom = new JSDOM("<!DOCTYPE html><html><body></body></html>");

global.window = dom.window as unknown as Window & typeof globalThis;
global.document = dom.window.document;
global.navigator = dom.window.navigator;

bunfig.toml

[test]
preload = ["./jsdom-setup.ts"]

Troubleshooting

TypeScript errors for document or window

Add the triple-slash DOM reference to the top of the file:

/// <reference lib="dom" />

Alternatively, add "lib": ["dom"] to your tsconfig.json.

Globals not available in tests

Ensure your preload file is registered in bunfig.toml and that GlobalRegistrator.register() is called before any tests run.

React component rendering issues

Confirm that both @testing-library/react and @happy-dom/global-registrator are installed as dev dependencies, and that the preload file is loaded before test files.

State leaking between tests

Reset the DOM in afterEach to prevent state from one test affecting the next:

import { afterEach } from "bun:test";
import { cleanup } from "@testing-library/react";

afterEach(() => {
  cleanup();
  document.body.innerHTML = "";
});