🛠️ Plugin Utilities

Poku provides utility functions via poku/plugins to help with plugin development and testing.

import {
  definePlugin,
  composeScopeHooks,
  createReporter,
  inspectPoku,
  findFileFromStack,
} from 'poku/plugins';

definePlugin

definePlugin(plugin: PokuPlugin): PokuPlugin

An identity function that provides type checking and IDE autocompletion when creating plugins. Returns the plugin object as-is — no runtime transformation.

import { definePlugin } from 'poku/plugins';

export default definePlugin({
  name: 'my-plugin',
  setup({ configs, runtime, cwd }) {
    // fully typed
  },
});

See Creating Plugins for the full guide.

🚧 composeScopeHooks

composeScopeHooks(provider: ScopeHookProvider): ScopeHooks

History

Version	Changes
v4.3.0	Introduce composeScopeHooks utility for plugins.

Composes a per-test scope hook provider into the active runtime chain used by it execution.

Use this when your plugin needs scoped async context or scoped cleanup logic under concurrent test callbacks.

import { composeScopeHooks } from 'poku/plugins';

composeScopeHooks({
  name: '@acme/my-plugin.scope-hooks',
  createHolder: () => ({ scope: undefined }),
  runScoped: async (holder, fn) => {
    const result = fn();
    if (result instanceof Promise) await result;
  },
});

Behavior guarantees:

• Deterministic order: providers compose in registration order.
• Idempotent by provider name: duplicate names are ignored.
• Backward-safe: if a legacy provider was already present, it is treated as the first provider in the composed chain.

This is the supported API for scope-provider registration in plugins.

createReporter

createReporter(events: ReporterEvents): ReporterPlugin

Creates a reporter plugin by merging your event handlers with the default poku reporter. Only override the events you need.

import { createReporter } from 'poku/plugins';

export const myReporter = createReporter({
  onFileResult({ status }) {
    process.stdout.write(status ? '.' : 'F');
  },
});

See Custom Reporters for the full guide and event reference.

inspectPoku

inspectPoku(options: { command: string; spawnOptions?: SpawnOptionsWithoutStdio; bin?: string }): Promise<InspectCLIResult>

Runs a Poku CLI execution programmatically and returns the result. Useful for plugin authors who need to test their plugins against real test runs.

type InspectCLIResult = {
  stdout: string;
  stderr: string;
  exitCode: number;
  process: ChildProcessWithoutNullStreams;
  PID: number;
  kill: () => Promise<void>;
};

Example

import { inspectPoku } from 'poku/plugins';

const result = await inspectPoku({
  command: '--sequential ./test',
  spawnOptions: { cwd: './fixtures' },
});

console.log(result.stdout);
console.log(result.exitCode); // 0 or 1
await result.kill();

Options

Option	Type	Description
command	string	CLI arguments to pass to Poku (e.g., '--sequential ./test')
spawnOptions	SpawnOptionsWithoutStdio	Options passed to child_process.spawn (e.g., { cwd })
bin	string	Path to the Poku binary. Auto-detected by default

findFileFromStack

findFileFromStack(stack: string | undefined, options?: { skipInternal?: boolean }): string

Parses a stack trace string and extracts the first file path found. Supports file:// URLs, Unix absolute paths, and Windows absolute paths.

When skipInternal is true, lines containing poku/lib/ are skipped — useful for finding the caller's file instead of Poku internals.

Returns the file path string, or an empty string if no path is found.

Example

import { findFileFromStack } from 'poku/plugins';

const file = findFileFromStack(new Error().stack, {
  skipInternal: true,
});

console.log(file); // '/path/to/your/test-file.ts'

Exported Types

All types are available from poku/plugins:

import type {
  PokuPlugin,
  PluginContext,
  ReporterPlugin,
  ReporterEvents,
  InspectCLIResult,
  ScopeHookProvider,
  ScopeHooks,
} from 'poku/plugins';