62 lines
2.5 KiB
Markdown
62 lines
2.5 KiB
Markdown
# setup/polyfills
|
|
|
|
<!-- begin:auto-docs -->
|
|
_(no submodules)_
|
|
<!-- end:auto-docs -->
|
|
## Purpose
|
|
|
|
The `setup/polyfills` module is a side-effect import that installs the globals test code expects to be present — `crypto`, `TextEncoder`, `TextDecoder` — when the host runtime (bare Node, happy-dom, jsdom, or Bun) doesn't already provide them. It's idempotent and safe to import multiple times.
|
|
|
|
## Features
|
|
|
|
- Installs `globalThis.crypto` from Node's `webcrypto` when missing
|
|
- Installs `TextEncoder` / `TextDecoder` from `node:util` when missing
|
|
- Guards every assignment with an existence check — never overwrites a populated global
|
|
- Exports nothing — side effects only
|
|
|
|
## Usage: Basic Example
|
|
|
|
```ts
|
|
// vitest.config.ts
|
|
import { defineConfig } from "vitest/config";
|
|
import { createVitestConfig } from "@suaveplan/testing-dom/config";
|
|
|
|
export default defineConfig(
|
|
createVitestConfig(__dirname, {
|
|
setupFiles: ["@suaveplan/testing-dom/polyfills"],
|
|
})
|
|
);
|
|
```
|
|
|
|
## Usage: Advanced Example
|
|
|
|
```ts
|
|
// bunfig.toml (bun-test)
|
|
// [test]
|
|
// preload = ["@suaveplan/testing-dom/polyfills", "./tests/install-matchers.ts"]
|
|
|
|
// Or programmatically via createBunTestConfig:
|
|
import { createBunTestConfig } from "@suaveplan/testing-dom/config";
|
|
|
|
const cfg = createBunTestConfig(__dirname, {
|
|
preload: ["./tests/install-matchers.ts"],
|
|
// createBunTestConfig adds the polyfills entry automatically.
|
|
});
|
|
```
|
|
|
|
## API Reference
|
|
|
|
No exports. Side effects:
|
|
|
|
- `globalThis.crypto ??= webcrypto` _(from `node:crypto`)_
|
|
- `globalThis.TextEncoder ??= NodeTextEncoder`
|
|
- `globalThis.TextDecoder ??= NodeTextDecoder`
|
|
|
|
## Implementation Notes
|
|
|
|
Modern Node (≥19) and Bun both ship `crypto` globally, so the `??=` short-circuits on those hosts. The module remains in the package for older Node versions and for happy-dom sandboxes that don't initialise `crypto`. Imports use `node:` specifiers so the code remains bundler-safe — Rollup/esbuild skip it when externalising node built-ins. Because the module exports nothing, consumers who mistakenly try `import { x } from "@suaveplan/testing-dom/polyfills"` get a useful TypeScript error rather than silent misbehaviour.
|
|
|
|
### Coverage
|
|
|
|
The polyfill bundle installs happy-dom's `DOMParser`, `XMLSerializer`, `fetch`, `Request`, `Response`, `Headers`, `URL`, `URLSearchParams`, and `crypto.getRandomValues` into the Node / Bun global scope when they are missing. Double-install is idempotent — the module tracks a `Symbol.for("suaveplan.testing-dom.polyfilled")` marker on `globalThis` so repeated imports are cheap.
|