very-happy-dom

A blazingly fast, lightweight virtual DOM implementation powered by Bun. Drop-in replacement for happy-dom and jsdom in testing environments.

Features

• Comprehensive DOM - Full DOM manipulation, CSS selectors, XPath, events with bubbling/capturing
• Network APIs - Fetch, XMLHttpRequest, WebSocket, Server-Sent Events, BroadcastChannel, MessageChannel, request interception
• Browser APIs - Storage, Timers, Canvas 2D, Observers (Mutation/Intersection/Resize/Performance), Clipboard, History, Cookies, File API, IndexedDB, Web Storage
• Web Components - Custom Elements and Shadow DOM
• Framework Agnostic - Works with Bun, Vitest, or any testing framework
• jsdom-compatible - Real JSDOM class with .serialize(), .reconfigure(), .fromURL(), .fromFile(), .fragment(), VirtualConsole, CookieJar, ResourceLoader
• happy-dom-compatible - Drop-in for GlobalRegistrator, window.happyDOM API, virtual consoles
• Screenshot - Pure-JS PNG/JPEG/WebP rendering + optional Bun.WebView real-browser screenshots

Installation

bun add -d very-happy-dom

Or with npm/pnpm:

npm install --save-dev very-happy-dom
pnpm add -D very-happy-dom

Quick Start

import { Window } from 'very-happy-dom'

const window = new Window()
const document = window.document

document.body.innerHTML = '<h1>Hello World</h1>'
const heading = document.querySelector('h1')
console.log(heading?.textContent) // "Hello World"

Testing with Bun

The simplest way — create a Window per test:

import { describe, expect, test } from 'bun:test'
import { Window } from 'very-happy-dom'

describe('MyComponent', () => {
  test('renders correctly', () => {
    const window = new Window()
    const document = window.document

    document.body.innerHTML = '<div class="container">Test</div>'
    const element = document.querySelector('.container')

    expect(element?.textContent).toBe('Test')
  })
})

Global DOM Environment

For Testing Library, React, and other frameworks that expect browser globals (document, window, etc.), either use the one-line preload subpath or call GlobalRegistrator manually.

Easiest — the /register subpath:

# bunfig.toml
[test]
preload = ["very-happy-dom/register"]

You can override the URL with VERY_HAPPY_DOM_URL or HAPPY_DOM_URL env vars.

Manual — drop-in for @happy-dom/global-registrator:

// happy-dom.ts (preload script)
import { GlobalRegistrator } from 'very-happy-dom'

GlobalRegistrator.register()

# bunfig.toml
[test]
preload = ["./happy-dom.ts"]

That's it. All browser globals are now available in your tests:

import { test, expect } from 'bun:test'
import { screen, render } from '@testing-library/react'
import { MyComponent } from './MyComponent'

test('renders correctly', () => {
  render(<MyComponent />)
  expect(screen.getByTestId('my-component')).toBeInTheDocument()
})

Migrating from happy-dom

One-line change — the GlobalRegistrator API is the same:

-import { GlobalRegistrator } from '@happy-dom/global-registrator'
+import { GlobalRegistrator } from 'very-happy-dom'

GlobalRegistrator.register()

Advanced Usage

Browser Context

import { Browser } from 'very-happy-dom'

const browser = new Browser()
const context = browser.createContext()
const page = context.newPage()

page.goto('https://example.com')

Request Interception

import { Window } from 'very-happy-dom'

const window = new Window()

window.interceptor.addInterceptor({
  onRequest: (request) => {
    if (request.url.includes('/api/')) {
      return new Response(JSON.stringify({ mocked: true }))
    }
    return request
  }
})

Custom Window Configuration

import { Window } from 'very-happy-dom'

const window = new Window({
  url: 'https://example.com',
  width: 1920,
  height: 1080,
  settings: {
    navigator: {
      userAgent: 'MyCustomUserAgent/1.0'
    },
    device: {
      prefersColorScheme: 'dark'
    }
  }
})

Event Handling

const window = new Window()
const document = window.document

const button = document.createElement('button')
let clicked = false

button.addEventListener('click', () => {
  clicked = true
})

button.click()
console.log(clicked) // true

Storage APIs

const window = new Window()

// localStorage
window.localStorage.setItem('key', 'value')
console.log(window.localStorage.getItem('key')) // "value"

// sessionStorage
window.sessionStorage.setItem('session', 'data')

Observers

const window = new Window()
const document = window.document

// MutationObserver
const observer = new window.MutationObserver((mutations) => {
  mutations.forEach((mutation) => {
    console.log('DOM changed:', mutation.type)
  })
})

observer.observe(document.body, {
  childList: true,
  attributes: true,
  subtree: true
})

// IntersectionObserver
const io = new window.IntersectionObserver((entries) => {
  entries.forEach((entry) => {
    console.log('Visibility changed:', entry.isIntersecting)
  })
})

// ResizeObserver
const ro = new window.ResizeObserver((entries) => {
  entries.forEach((entry) => {
    console.log('Size changed:', entry.contentRect)
  })
})

Canvas API

const window = new Window()
const document = window.document

const canvas = document.createElement('canvas')
const ctx = canvas.getContext('2d')

ctx.fillStyle = 'red'
ctx.fillRect(0, 0, 100, 100)
ctx.strokeStyle = 'blue'
ctx.strokeRect(10, 10, 80, 80)

// Export canvas data
const dataUrl = canvas.toDataURL()
const blob = await canvas.toBlob()

Performance

vs happy-dom vs jsdom

Note: "Faster by" compares very-happy-dom to the next-fastest result. Benchmarks run on Apple M3 Pro with Bun 1.3.11. Run them yourself:

bun run bench

Migration

From happy-dom

One-line change — the API is compatible:

// Before
import { Window } from 'happy-dom'

// After
import { Window } from 'very-happy-dom'

From jsdom

very-happy-dom ships a jsdom-compatible JSDOM class — the exact idiom works unchanged:

// Before (jsdom)
import { JSDOM } from 'jsdom'

// After (very-happy-dom) — one-line change
import { JSDOM } from 'very-happy-dom'
// or: import { JSDOM } from 'very-happy-dom/jsdom'

const dom = new JSDOM('<!DOCTYPE html><html><body><h1>Hi</h1></body></html>', {
  url: 'https://example.com/',
  runScripts: 'dangerously',
})
const { window } = dom
const { document } = window

dom.serialize()                       // full HTML string
dom.reconfigure({ url: '...' })       // change URL mid-test
JSDOM.fragment('<p>x</p>')            // DocumentFragment
await JSDOM.fromFile('./page.html')   // parse a local file
await JSDOM.fromURL('https://x.test') // fetch + parse

Full surface: JSDOM, VirtualConsole, CookieJar, ResourceLoader — each with the same method names and overloads as jsdom.

See the drop-in compatibility guide for the complete migration reference.

API Reference

Core Classes

• Window - Main window/global object with all browser APIs
• Document - DOM document with querySelector, createElement, etc.
• Element - DOM elements with full manipulation API
• Browser - Browser instance for advanced scenarios
• BrowserContext - Isolated browser contexts
• BrowserPage - Individual pages with navigation

Supported APIs

Testing

bun test                  # Run all tests
bun test --coverage      # Run with coverage

Contributing

We welcome contributions! Please see CONTRIBUTING for details.

Changelog

Please see our releases page for more information on what has changed recently.

Community

For help, discussion about best practices, or any other conversation that would benefit from being searchable:

Discussions on GitHub

For casual chit-chat with others using this package:

Join the Stacks Discord Server

Postcardware

Very Happy DOM is free and open-source, but we'd love to receive a postcard from you! Send one to:

Stacks.js, 12665 Village Ln #2306, Playa Vista, CA 90094, United States 🌎

We showcase postcards from around the world on our website!

Sponsors

We would like to extend our thanks to the following sponsors for funding Stacks development. If you are interested in becoming a sponsor, please reach out to us.

• JetBrains
• The Solana Foundation

License

The MIT License (MIT). Please see LICENSE for more information.

Made with 💙