// Testing deep-dive for poku covering test structure, commands, patterns, fixtures, utils, Docker compatibility, and coverage. Use when writing, organizing, or running tests, adding fixtures, or working on coverage.
Documentation deep-dive for the poku website covering Docusaurus setup, language policy, feature-to-docs mapping, conventions, JSDoc, and the changelog. Use when editing or adding docs or mapping a feature to its page.
Run the mandatory pre-commit checks for the poku repository before staging a commit. Use this whenever the user asks to commit, prepare a commit, push, open a PR, or verify a change is ready. Runs typecheck, lint:fix, build, and the local test suite in order, plus runtime-sensitive suites when the change touches runtime detection, isolation, child-process spawning, environment-variable plumbing, or any Bun or Deno specific code path.
Architecture deep-dive for poku covering project structure, execution flow, config discovery, runtime detection, and competitive context. Use when navigating the codebase or understanding how components fit together.
Engineering deep-dive for poku covering performance, code, and security patterns, TypeScript config, build pipeline, developer experience, and CI/CD. Use when implementing or optimizing code, writing performance-sensitive logic, touching the build, or applying code-style and security rules.
| name | testing |
| description | Testing deep-dive for poku covering test structure, commands, patterns, fixtures, utils, Docker compatibility, and coverage. Use when writing, organizing, or running tests, adding fixtures, or working on coverage. |
How tests are organized and where to look. Read the actual test/ tree to confirm details, since test files change over time.
Tests live under test/, organized by purpose:
test/unit/: core services and utilitiestest/integration/: API surface by feature, with a subdirectory per feature (assertions, describe, it, test, strict assertions, before/after each, wait-for, etc.)test/e2e/: CLI workflows, service management, and watch modetest/compatibility/: Docker-based multi-version checkstest/__fixtures__/: scenario fixtures, mirroring the test structuretest/__utils__/: shared test helperstest/__docker__/: Docker infrastructure (compose plus Dockerfiles)Read the relevant directory to discover the current files. Poku tests itself, so these files also show how describe(), it(), test(), and assert are used in practice.
The package.json scripts are the source of truth. The main ones:
npm test: runs the unit, integration, and e2e suites on Node via tsxnpm run test:bun: same suites on the Bun runtimenpm run test:deno: same suites on Deno (with --denoAllow=all)npm run test:coverage: runs npm test with the --coverage flag (c8 plus monocart-coverage-reports via @pokujs/c8)npm run test:docker:node: runs the Docker compatibility matrixOpen a representative file in the relevant directory to learn the pattern:
Promise.all([it(...)])startService(), waitForPort(), and server.end()@pokujs/docker lifecycle to run a suite inside a containerComments are completely prohibited in tests. describe, it, test, assert, and strict all accept a message, so express intent through those instead.
Prefer value-preserving asserts over a derived boolean. assert(regex.test(x)) collapses failures to Actual: false / Expected: true. assert.match / assert.doesNotMatch print Value + RegExp, and assert.strictEqual / assert.deepStrictEqual print Actual + Expected. Split combined checks like a && b into independent assertions. A boolean assertion is acceptable only when no value-preserving form fits.
A bug-reproduction test asserts the correct expected behavior, so without a fix it MUST fail and pass only once the bug is fixed. Never write it to pass against the buggy behavior.
test/__utils__/)Shared helpers for writing tests:
inspectPoku(args, configs): run the CLI, capture stdout/stderr/exitCodeinspectCLI(command, args): generic CLI inspectionwatchCLI(args, configs): monitor watch mode via a getOutput() callbacklegacyFetch(host, port): HTTP fetch for Node 16 compatibilitytest/__fixtures__/)Fixtures provide controlled scenarios and mirror the test structure (unit/, integration/, e2e/). They cover cases such as config files, HTTP servers, pass/fail outcomes, fail-fast, file discovery, module types (CJS/ESM/TypeScript), reporters, and watch mode. Read test/__fixtures__/ to find an existing scenario or to add a new one next to its peers.
FILTER=node-<version> npm run test:docker:nodetest/__docker__/docker-compose.ymlci/ (NODE_ENV=build, .js).nycrc (checkCoverage, the source of truth). The goal is 100%watch usage