@stencil/mock-doc

A minimal mock DOM implementation for SSR and testing

Source

npm

Version: 5.0.0-alpha.30

Version published: 3 weeks ago

Weekly downloads: 542

Maintainers: 6

Weekly downloads

Created: 6 months ago

Source

@stencil/mock-doc

A minimal mock DOM implementation for server-side rendering and unit testing of Stencil components.

Install

npm install --save-dev @stencil/mock-doc

Usage

`createDocument(html?)` — lightweight document only

Use this when you only need a Document with no surrounding window object:

import { createDocument, serializeNodeToHtml } from '@stencil/mock-doc';

const doc = createDocument('<div class="greeting">Hello</div>');
const el = doc.querySelector('.greeting');
el.textContent = 'Hello, world!';

console.log(serializeNodeToHtml(el, { outerHtml: true }));
// <div class="greeting">Hello, world!</div>

`MockWindow(html?)` — full window environment

Use this when your code accesses window, location, navigator, localStorage, etc.:

import { MockWindow, serializeNodeToHtml } from '@stencil/mock-doc';

const win = new MockWindow('<html><body><my-comp></my-comp></body></html>');
const doc = win.document;

const el = doc.querySelector('my-comp');
el.setAttribute('label', 'Hello');

const html = serializeNodeToHtml(doc);

`parseHtmlToDocument` / `parseHtmlToFragment`

Parse an HTML string into a Document or a DocumentFragment:

import { parseHtmlToDocument, parseHtmlToFragment } from '@stencil/mock-doc';

const doc = parseHtmlToDocument('<p>Hello</p>');
const frag = parseHtmlToFragment('<li>one</li><li>two</li>');

`serializeNodeToHtml(node, options?)`

Serialize any node back to an HTML string. Useful for snapshot tests and SSR output.

import { serializeNodeToHtml } from '@stencil/mock-doc';

// Pretty-printed output
const pretty = serializeNodeToHtml(doc, { prettyHtml: true });

// Outer HTML of a single element (includes the element's own tag)
const outer = serializeNodeToHtml(el, { outerHtml: true });

// Serialize shadow roots as Declarative Shadow DOM
const dsd = serializeNodeToHtml(doc, {
  serializeShadowRoot: 'declarative-shadow-dom',
});

Key options:

Option	Default	Description
`prettyHtml`	`false`	Indent and add newlines
`indentSpaces`	`2` (when pretty)	Spaces per indent level
`outerHtml`	`false`	Include the root element's own tag
`removeEmptyAttributes`	`true`	Strip attributes with empty string values
`removeHtmlComments`	`false`	Strip HTML comments
`serializeShadowRoot`	—	`'declarative-shadow-dom'` or `'scoped'`
`fullDocument`	`false`	Always emit a full `<!DOCTYPE html>` document

`setupGlobal` / `teardownGlobal` — test framework integration

Installs a MockWindow onto global so that window, document, customElements, etc. are available without a browser. Call in beforeEach/afterEach to get a fresh environment per test:

import { setupGlobal, teardownGlobal } from '@stencil/mock-doc';

beforeEach(() => setupGlobal(global));
afterEach(() => teardownGlobal(global));

it('reads document.title', () => {
  document.title = 'My Page';
  expect(document.title).toBe('My Page');
});

setupGlobal returns the MockWindow it created, which you can use to reach window-level APIs directly if needed.

`patchWindow(win)` — fill gaps in a partial window

Useful when running in an environment that has some browser globals but is missing others (e.g. a custom SSR runtime):

import { patchWindow } from '@stencil/mock-doc';

patchWindow(globalThis); // fills in any missing window APIs with mock implementations

Fetch mocks

Use MockRequest, MockResponse, and MockHeaders to test code that calls fetch without hitting the network:

import { MockRequest, MockResponse, MockHeaders } from '@stencil/mock-doc';

// Simulate an incoming request
const req = new MockRequest('/api/data', { method: 'POST' });
console.log(req.method); // 'POST'
console.log(req.url);    // 'http://localhost/api/data'

// Build a response your handler returns
const res = new MockResponse(JSON.stringify({ ok: true }), {
  status: 200,
  headers: new MockHeaders({ 'content-type': 'application/json' }),
});

const body = await res.json(); // { ok: true }