https://github.com/pokujs/dom
Shared DOM testing core for Poku framework adapters.
https://github.com/pokujs/dom
Last synced: 2 months ago
JSON representation
Shared DOM testing core for Poku framework adapters.
- Host: GitHub
- URL: https://github.com/pokujs/dom
- Owner: pokujs
- License: mit
- Created: 2026-04-05T14:24:11.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-05T16:01:28.000Z (3 months ago)
- Last Synced: 2026-04-05T17:27:59.178Z (3 months ago)
- Language: TypeScript
- Homepage:
- Size: 89.8 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# @pokujs/dom
Shared DOM testing core for Poku framework adapters.
---
@pokujs/dom centralizes cross-framework testing infrastructure used by adapter libraries such as @pokujs/react and @pokujs/vue.
Use this package when building or maintaining framework adapters that need:
- Runtime command injection for Node, Bun, and Deno.
- In-process test environment setup.
- Metrics normalization and reporting.
- happy-dom/jsdom environment bootstrap.
- Shared testing runtime primitives.
## Installation
```bash
npm i @pokujs/dom
```
## Usage
### 1) Build runtime option prefixes and parse flags
```ts
import {
createRuntimeOptionArgPrefixes,
parseRuntimeOptions,
} from '@pokujs/dom';
const prefixes = createRuntimeOptionArgPrefixes('poku-react');
const runtimeOptions = parseRuntimeOptions(prefixes);
```
### 2) Create a framework plugin factory
```ts
import {
createFrameworkTestingPluginFactory,
type FrameworkDescriptor,
} from '@pokujs/dom';
const descriptor: FrameworkDescriptor = {
pluginName: 'react-testing',
packageTag: '@pokujs/react',
runtimeArgBase: 'poku-react',
metricMessageType: 'POKU_REACT_RENDER_METRIC',
metricBatchMessageType: 'POKU_REACT_RENDER_METRIC_BATCH',
};
const { createTestingPlugin } = createFrameworkTestingPluginFactory(
descriptor,
import.meta.url
);
export const createReactTestingPlugin = createTestingPlugin;
```
### 3) Reuse DOM setup helpers
```ts
import { setupHappyDomEnvironment, setupJsdomEnvironment } from '@pokujs/dom';
```
### 4) Reuse shared testing runtime helpers
```ts
import {
createRenderMetricsEmitter,
createScreen,
getNow,
} from '@pokujs/dom';
```
## Contracts
Adapter packages should follow these contracts.
### FrameworkDescriptor contract
- pluginName: Plugin registration name.
- packageTag: Human-readable package tag for messages.
- runtimeArgBase: Prefix base used to generate runtime CLI flags.
- metricMessageType: IPC type for single render metrics.
- metricBatchMessageType: IPC type for batch render metrics.
- testFileExtensions (optional): Test file extensions the runner should intercept.
### Runtime options contract
parseRuntimeOptions returns:
- domUrl: DOM URL used by happy-dom/jsdom setup.
- metricsEnabled: Whether metrics collection is active.
- minMetricMs: Drop metrics below this threshold.
- metricBatchSize: Batch size before immediate flush.
- metricFlushMs: Flush interval while buffering.
### Metrics contract
createMetricsSummary returns either null or:
- totalCaptured: Number of collected metrics.
- totalReported: Number of top metrics reported.
- topSlowest: Sorted metrics by duration descending.
### Testing runtime contract
createRenderMetricsEmitter provides:
- emitRenderMetric(componentName, durationMs)
- flushMetricBuffer()
- clearMetricFlushTimer()
These APIs are framework-agnostic. Adapter packages remain responsible for framework-specific semantics such as act, nextTick, render lifecycle, and hook/composable harness behavior.
## Release and CI/CD
This package includes:
- CI build and lint workflows.
- Node, Bun, and Deno compatibility workflows.
- CodeQL workflow and config.
- Release Please + npm publish workflow.
## Development
```bash
npm ci
npm run check
npm run build
```
## Testing
```bash
npm test
npm run test:bun
npm run test:deno
```
## License
MIT