poku

Poku

A flexible and easy-to-use Test Runner for Node.js, Bun and Deno that allows you to run parallel and sequential tests, plus high isolation level per test file.

---

Why Poku?

Poku starts from the premise where tests come to help, not overcomplicate: runs test files in an individual process per file, shows progress and exits 🧙🏻

• Supports ESM and CJS
• Designed to be highly intuitive
• No need to compile TypeScript
• Compatible with Coverage tools
• Allows both in-code and CLI usage
• Node.js, Bun and Deno compatibility
• Zero configurations, except you want
• No constraints or rules, code in your own signature style

---

• 
• Zero external dependencies
• Poku dive to the deepest depths to find tests in the specified directories
• Compatibility: Poku is tested across all Node 6+, Bun 0.5.3+ and Deno 1.30+ versions
• Poku uses itself to test its own tests using process.exit at several depths on the same process node

---

Sequential	Parallel
npx poku test/unit,test/integration	npx poku --parallel test/unit,test/integration

• By default, Poku searches for all .test. files, but you can customize it using the option filter.
• The same idea for Bun and Deno (see bellow).

---

Poku also includes the assert method, keeping everything as it is, but providing human readability:

import { assert } from 'poku'; // Node and Bun
import { assert } from 'npm:poku'; // Deno

assert(true);
assert.deepStrictEqual(1, '1', 'My optional custom message');

---

Install

Node.js

npm install --save-dev poku

TypeScript (Node.js)

npm install --save-dev poku tsx

Bun

bun add --dev poku

Deno

import { poku } from 'npm:poku';

• Poku requires these permissions by default: --allow-read, --allow-env and --allow-run.

---

Basic Usage

In-code

import { poku } from 'poku';

await poku(['targetDirA', 'targetDirB']);

import { poku } from 'npm:poku';

await poku(['targetDirA', 'targetDirB']);

CLI

npx poku targetDirA,targetDirB

bun poku targetDirA,targetDirB

deno run npm:poku targetDirA,targetDirB

---

Documentation

Website in Progress 🧑🏻‍🔧

Initially, the documentation is based on Node.js usage, but you can use all the options normally for both Bun and Deno.

poku(targetDirs: string | string[])

Include directories

• in-code

poku('targetDir');

poku(['targetDirA', 'targetDirB']);

• CLI

By setting the directories as the last argument:

Since 1.3.0

npx poku targetDir

npx poku targetDirA,targetDirB

By using --include option:

Since 1.0.0

npx poku --include='targetDir'

npx poku --include='targetDirA,targetDirB'

---

poku(targetDirs: string | string[], configs?: Configs)

parallel: boolean

Determines the mode of test execution across sequential or parallel modes.

• in-code

/**
 * @default
 *
 * Sequential mode
 */

poku(['...'], {
  parallel: false,
});

/**
 * Parallel mode
 */

poku(['...'], {
  parallel: true,
});

• CLI

Since 1.2.0

# Parallel mode

npx poku --parallel ./test

---

platform: "node" | "bun" | "deno"

Since 1.2.0

By default, Poku tries to identify the platform automatically, but you can set it manually:

• in-code

/**
 * Force Node.js (or tsx for TypeScript)
 *
 * @default 'node'
 */

poku('...', {
  platform: 'node',
});

/**
 * Force Bun
 */

poku('...', {
  platform: 'bun',
});

/**
 * Force Deno
 */

poku('...', {
  platform: 'deno',
});

• CLI

# Normal

npx      poku      --platform=node  ./test
bun      poku      --platform=bun   ./test
deno run npm:poku  --platform=deno  ./test

# Custom
# When you're developing using a platform, but maintain compatibility with others

npx      poku      --platform=bun   ./test
bun      poku      --platform=deno  ./test
deno run npm:poku  --platform=node  ./test

# ...

---

filter: RegExp

By default, Poku searches for .test. files, but you can customize it using the filter option.

Filter by path using Regex to match only the files that should be performed.

• in-code

/**
 * @default
 *
 * Testing all `*.test.*` files.
 */

poku(['...'], {
  filter: /\.test\./,
});

/**
 * Testing all `ts`, `js`, `mts` and `mjs` files
 */

poku(['...'], {
  filter: /\.(m)?(j|t)s$/,
  // filter: /\.(js|ts|mjs|mts)$/,
});

• CLI

# Testing only a specific file

npx poku --filter='some-file' ./test

# Testing only a specific file

npx poku --filter='some-file|other-file' ./test

# Testing only paths that contains "unit"

npx poku --filter='unit' ./test

• Environment Variable

By using FILTER from Environment Variable, it will overwrite the filter option.

# Testing only a specific file

FILTER='some-file' npx poku ./test

# Testing only a specific file

FILTER='some-file|other-file' npx poku ./test

# Testing only paths that contains "unit"

FILTER='unit' npx poku ./test

---

exclude: RegExp | RegExp[]

Exclude by path using Regex to match only the files that should be performed.

Since 1.2.0

• in-code:

/**
 * Excluding  directories from tests
 */

poku(['...'], {
  exclude: /\/(helpers|tools)\//,
});

/**
 * Excluding  directories from tests
 */

poku(['...'], {
  exclude: [/\/helpers\//, /\/tools\//],
});

/**
 * Excluding specific files from tests
 */

poku(['...'], {
  exclude: /(index|common).test.ts/,
});

/**
 * Excluding specific files from tests
 */

poku(['...'], {
  exclude: [/index.test.ts/, /common.test.ts/],
});

/**
 * Excluding directories and files from tests
 */

poku(['...'], {
  exclude: /\/(helpers|tools)\/|(index|common).test.ts/,
});

/**
 * Excluding directories and files from tests
 */

poku(['...'], {
  exclude: [/\/helpers\//, /\/tools\//, /index.test.ts/, /common.test.ts/],
});

• CLI

# Excluding directories and files from tests

npx poku --exclude='some-file-or-dir' ./test

# Excluding directories and files from tests

npx poku --exclude='some-file-or-dir|other-file-or-dir' ./test

---

Assert

Since 1.3.0

Node.js, Bun and Deno compatible.

Poku includes the assert method, keeping everything as it is, but providing human readability.

Available methods:

• assert(value[, message])
• assert.deepEqual(actual, expected[, message])
• assert.deepStrictEqual(actual, expected[, message])
• assert.doesNotMatch(string, regexp[, message])
• assert.doesNotReject(asyncFn[, error][, message])
• assert.doesNotThrow(fn[, error][, message])
• assert.equal(actual, expected[, message])
• assert.fail([message])
• assert.ifError(value)
• assert.match(string, regexp[, message])
• assert.notDeepEqual(actual, expected[, message])
• assert.notDeepStrictEqual(actual, expected[, message])
• assert.notEqual(actual, expected[, message])
• assert.notStrictEqual(actual, expected[, message])
• assert.ok(value[, message])
• assert.rejects(asyncFn[, error][, message])
• assert.strictEqual(actual, expected[, message])
• assert.throws(fn[, error][, message])

You can follow the assert documentation from Node.js's documentation.

---

listFiles(targetDir: string, configs?: ListFilesConfigs)

Since 1.2.0

Returns all files in a directory, independent of their depth.

listFiles('some-dir');

• You can use the filter and exclude options, as well as they are for poku method.

---

Community

I'm continuously working to improve Poku. If you've got something interesting to share, feel free to submit a Pull Request. If you notice something wrong, I'd appreciate if you'd open an Issue.

---

Acknowledgements

• Contributors

Changelog

1.3.0 (2024-02-19)

Features

• assert: human readability assert (#14) (66e5a52)
• CLI: flexible include (#12) (ec63f28)