Skip to main content
Version: v4.x.x

🥷🏻 Using Plugins

History
VersionChanges
v3.0.3-canary.68e71482
Introduce the Plugin System.
2Stable

Extend Poku's behavior with plugins: hook into the test lifecycle, customize how test files are spawned, enable inter-process communication, and more.

What Can Plugins Do?​

  • Run setup logic before the test suite begins.
  • Intercept or customize file discovery.
  • Run teardown logic after the test suite completes.
  • Modify the command used to spawn each test file process.
  • Enable IPC channels between Poku and test processes.
  • React to each test process being spawned.
  • Customize output with custom reporters.

Quick Start​

Add plugins to your Poku configuration file via the plugins option:

// poku.config.ts
import { defineConfig } from 'poku';
import { myPlugin } from './my-plugin';

export default defineConfig({
  plugins: [myPlugin],
});

Plugin Lifecycle​

Plugins are executed in the following order:

  1. setup() is called for each plugin, sequentially in array order.
  2. discoverFiles() from the first plugin that defines it determines the test files (if no plugin defines it, Poku scans the configured directories).
  3. For each test file:
    • runner() modifies the spawn command (only the first plugin with a runner hook is used).
    • The process is spawned with an IPC channel if any plugin sets ipc: true.
    • onTestProcess() is called for every plugin that defines it.
  4. After all tests complete: teardown() is called for each plugin, sequentially in array order.

Official Plugins​

  • Coverage (@pokujs/c8, @pokujs/monocart, @pokujs/istanbul, @pokujs/one-double-zero): Collect code coverage with --coverage, choosing the reporter that best fits your project. See the documentation.
  • @pokujs/react: Render and assert on React components inside Poku tests, with a real DOM environment and zero config. See the documentation.
  • @pokujs/vue: Render and assert on Vue components inside Poku tests, with a real DOM environment and automatic Single File Component handling. See the documentation.
  • @pokujs/docker: Mount and unmount containers around your tests, with a minimal API for Docker Compose and Dockerfiles. See the documentation.
  • @pokujs/multi-suite: Run multiple independent test suites, each with its own configuration, as a single unified execution. See the documentation.
  • @pokujs/shared-resources: Share state, servers, database connections, and more between parallel test files. See the documentation.

Advanced Lifecycle: Test Scope Hooks​

Poku supports an optional per-test scope contract for plugin authors who need strict state isolation inside concurrent it executions.

  • Read the full guide: Test Scope Hooks
  • Use this when plugin internals track mutable state (Set, Map, registries, handles) that must never leak across test callbacks.
tip

Use definePlugin for type safety when creating plugins, and createReporter for custom output formatting.