Skip to main content
Version: v4.x.x

isolation

Controls process isolation for test files.

History
VersionChanges
v4.2.0
Introduces test isolation modes.

By default, Poku runs each test file in a separate child process. This ensures full isolation between tests — each file gets its own process.exitCode, module cache, and global state.

Setting isolation to none runs all test files in the same process instead of spawning a new one for each file. This is useful for debugging with node --inspect or node --inspect-brk.

CLI​

npx poku --isolation=process ./test # default

Config File​

{
  // "$schema": "https://poku.io/schemas/configs.json",
  "isolation": "process" // default
}
const { defineConfig } = require('poku');

module.exports = defineConfig({
  isolation: 'process', // default
});

API​

await poku('./test', {
  isolation: 'process', // default
});

Debugging with --inspect​

When using isolation: 'none', you can attach a debugger to the Poku process and inspect your tests directly:

node --inspect-brk ./node_modules/.bin/poku --isolation=none ./test

This works because all tests run in the same process as the debugger. With the default process isolation, the debugger would only attach to the parent process, not to the child processes running each test file.

Intentional Limitations​

When running without isolation, all test files share the same process. This comes with some intentional limitations:

  • Tests always run sequentially. Concurrent execution is disabled because there is no way to isolate process.exitCode or stdout between files running in the same process at the same time.
  • Different module structures may conflict. .ts, .cjs, and .mjs files sharing the same process may not work depending on the runtime and version. With process isolation, each file runs in its own context and this is handled naturally.
  • Global state is shared. Environment variables, global objects, and module caches are shared across all test files.
  • process.exit() in a test file will terminate the entire run. With process isolation, only the child process is affected.
  • console.error() output is not captured by the reporter. Only stdout is intercepted. Any stderr output from test files will appear directly in the terminal, outside the reporter's formatted output.
  • Timed out tests may continue running in the background. Unlike process isolation where the child process is killed, there is no way to stop a module that is already being evaluated. Output from a timed out test may leak into the terminal after the timeout is reported.
tip

When debugging, you typically run a small number of test files. You can use --filter to narrow down the files, for example:

node --inspect-brk ./node_modules/.bin/poku --isolation=none --filter=my-test ./test
info

This option is inspired by Node.js' --test-isolation=none and Jest's --runInBand.