πͺ Scoped Test Lifecycle Hooks
Poku provides an optional, generic hook contract that lets plugins execute test callbacks inside a plugin-managed scope.
History
| Version | Changes |
|---|---|
| v4.3.0 |
This is designed for plugins that keep mutable state in memory and need strict per-test boundaries under concurrency.
Why This Existsβ
Inside a describe block, multiple it callbacks can run concurrently when they are registered synchronously.
If a plugin stores resources in module-level state (Set, Map, registries), one test can accidentally mutate or clean up resources created by another test.
Typical failure modes:
- cross-test state leakage
- flaky concurrency behavior
- cleanup races
- non-deterministic failures
Contractβ
Poku checks for a global symbol key:
Symbol.for('@pokujs/poku.test-scope-hooks');
If a provider exists, beforeEach, the test callback, and afterEach run through it in the same scope. If not, Poku uses the default execution path.
Shape of the provider:
type ScopeHooks = {
createHolder: () => { scope: unknown };
runScoped: (
holder: { scope: unknown },
fn: (params?: Record<string, unknown>) => Promise<unknown> | unknown
) => Promise<void>;
};
π§ Registration APIβ
Scope providers should be attached via composeScopeHooks from @pokujs/scope-hooks.
import { composeScopeHooks } from '@pokujs/scope-hooks';
composeScopeHooks({
name: '@acme/my-plugin.scope-hooks',
createHolder: () => ({ scope: undefined }),
runScoped: async (holder, fn) => {
const result = fn();
if (result instanceof Promise) await result;
},
});
Composition rules:
- providers compose in registration order
- duplicate provider
namevalues are ignored - existing legacy single-provider hooks are treated as the first provider in the chain
How Core Uses Itβ
Equivalent flow inside it execution:
const hooks = getScopeHooks();
const execute = async (params?: Record<string, unknown>) => {
try {
await beforeEachCallback?.();
await testCallback(params);
} finally {
await afterEachCallback?.();
}
};
if (hooks) {
const holder = hooks.createHolder();
await hooks.runScoped(holder, execute);
} else {
await execute();
}
The provider receives one holder for the complete test lifecycle. afterEach runs once, including when setup or the test body fails. The provider should dispose its resources after the callback settles.
An error from the scope provider marks the test as failed and still produces its end event, so the following test can run. Errors from beforeEach and afterEach retain their existing propagation behavior. The test callback receives any parameters forwarded by the provider.
This keeps core plugin-agnostic while enabling plugin-managed async context and teardown strategies.
Plugin Example (AsyncLocalStorage)β
import { AsyncLocalStorage } from 'node:async_hooks';
import { composeScopeHooks } from '@pokujs/scope-hooks';
type ScopeHooks = {
createHolder: () => { scope: unknown };
runScoped: (
holder: { scope: unknown },
fn: (params?: Record<string, unknown>) => Promise<unknown> | unknown
) => Promise<void>;
};
const SCOPE_HOOKS_KEY = Symbol.for('@pokujs/poku.test-scope-hooks');
const als = new AsyncLocalStorage<{ id: number }>();
let idSeed = 0;
composeScopeHooks({
name: '@acme/my-plugin.scope-hooks',
createHolder: () => ({ scope: undefined }),
runScoped: async (holder, fn) => {
const id = ++idSeed;
holder.scope = { id };
await als.run({ id }, async () => {
const result = fn();
if (result instanceof Promise) await result;
});
},
});
Recommendations For Plugin Authorsβ
- Register providers once during plugin bootstrap with
composeScopeHooks. - Keep
createHoldercheap and synchronous. - Ensure
runScopedalways awaitsfnbefore returning. - Keep scope state test-local. Never reuse mutable holders across tests.
- Run cleanup in
finallysemantics inside your scope runtime.
Important Notesβ
- Backward compatible: no provider means old behavior.
- Optional and additive: plugins can adopt incrementally.
- This contract is advanced and intended for plugin/runtime authors, not regular test authors.
- Scope provider hot-swapping during a test run is not supported and should be avoided.
Validationβ
The scope lifecycle behavior is covered by unit tests:
- fallback path works with no hooks
- concurrent executions receive independent stores
- store identity remains stable across async boundaries
- setup, test body, and teardown share one scope
- teardown runs once after setup or body failures
- provider disposal errors fail the test, report its end once, and allow subsequent tests to run
See the related test coverage in test/unit/scope-hooks.test.ts in the Poku package.