Poku's Logo # Poku Enjoying **Poku**? Give him a star to show your support 🌟 [![NPM Version](https://img.shields.io/npm/v/poku.svg?label=&color=70a1ff&logo=npm&logoColor=white)](https://www.npmjs.com/package/poku) [![NPM Downloads](https://img.shields.io/npm/dm/poku.svg?label=&logo=npm&logoColor=white&color=45aaf2)](https://www.npmjs.com/package/poku) [![Coverage](https://img.shields.io/codecov/c/github/wellwelwel/poku?label=&logo=codecov&logoColor=white&color=98cc00)](https://github.com/wellwelwel/poku/tree/main/.nycrc)
[![GitHub Workflow Status (Linux)](https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_coverage-linux.yml?event=push&label=&branch=main&logo=ubuntu&logoColor=8897a9&color=dfe4ea)](https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-linux.yml?query=branch%3Amain) [![GitHub Workflow Status (OSX)](https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_coverage-osx.yml?event=push&label=&branch=main&logo=apple&logoColor=8897a9&color=dfe4ea)](https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-osx.yml?query=branch%3Amain) [![GitHub Workflow Status (Windows)](https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_coverage-windows.yml?event=push&label=&branch=main&logo=data:image/svg+xml;base64,PHN2ZyByb2xlPSJpbWciIHZpZXdCb3g9IjAgMCAxMjggMTI4IiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPjx0aXRsZT5XaW5kb3dzIDExPC90aXRsZT48cGF0aCBmaWxsPSIjODg5N2E5IiBkPSJNMTI2IDEuNjM3bC02NyA5LjgzNHY0OS44MzFsNjctLjUzNHpNMS42NDcgNjYuNzA5bC4wMDMgNDIuNDA0IDUwLjc5MSA2Ljk4My0uMDQtNDkuMDU3em01Ni44Mi42OGwuMDk0IDQ5LjQ2NSA2Ny4zNzYgOS41MDkuMDE2LTU4Ljg2M3pNMS42MSAxOS4yOTdsLjA0NyA0Mi4zODMgNTAuNzkxLS4yODktLjAyMy00OS4wMTZ6Ij48L3BhdGg+PC9zdmc+&color=dfe4ea)](https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-windows.yml?query=branch%3Amain) --- 🐷 [Website](https://poku.io/)  β€’  πŸ“˜ [Documentation](https://poku.io/docs)  β€’  πŸ§ͺ [Examples](https://poku.io/docs/category/examples)  β€’  πŸ§‘πŸ»β€πŸŽ“ [Tutorials](https://poku.io/docs/category/quick-tutorials)
--- ## Why does Poku exist? πŸ’‘ **Poku** is a cross-platform test runner that brings the [**JavaScript** essence back to testing](https://poku.io/docs/philosophy#javascript-essence-for-tests-). check High **isolation** level per file
check **Performant** and **lightweight**
check Auto detect **ESM**, **CJS**, and **TypeScript** files
check Run the **same test suite** for [**Node.js**][node-version-url], [**Bun**][bun-version-url], and [**Deno**][deno-version-url]
check Easily handle **servers**, **processes**, **ports**, and even **containers** ✨ --- ## Quickstart ### check Install
```bash # Node.js npm i -D poku ``` ```bash # TypeScript (Node.js) npm i -D poku tsx ``` ```bash # Bun bun add -d poku ``` ```bash # Deno (optional) deno add npm:poku ```
--- ### check Test
test/file.test.mjs
```ts import { assert } from 'poku'; assert(true, 'Poku will describe it 🐷'); ```
--- ### check Run
Node.js (and TypeScript)
Bun
Deno
```bash npx poku ``` ```bash bun poku ``` ```bash deno run npm:poku ```
--- ## Features ### check Essentials
poku πŸ§ͺ Test runner.
assert πŸ” Test assertion (Node.js familiar API).
strict πŸ”¬ Strict test assertion (Node.js familiar API).
### check Helpers
test β€’ describe β€’ it πŸ€ΉπŸ»β€β™€οΈ Organize, group, and isolate tests.
envFile βš™οΈ Process an environment file (out-of-box).
beforeEach β€’ afterEach πŸƒ Hooks for test setup and teardown.
startScript 🌐 Run package.json scripts in background.
startService 🌐 Run files in background.
docker 🐳 Build, start, compose, stop, remove, and test containers.
kill πŸ”Œ Terminate ports, port ranges, and PIDs.
waitForPort 😴 Wait for specified ports to become active.
waitForExpectedResult πŸ₯± Retry until an expected result or times out.
skip ⏭️ Skip tests when necessary.
only 🌌 Debug tests by enabling selective runs.
getPIDs πŸ•΅πŸ» Debug processes IDs using ports and port ranges.
### check Common Options
watch 🍿 Watch for changes and re-run related test files.
debug πŸ•΅πŸ» Shows all logs.
config βš™οΈ Customize your Poku options in a config file.
coverage β˜”οΈ Enable coverage collection using a coverage plugin.
> _and much more_ πŸ‘‡πŸ» --- ## Documentation and Examples To see the detailed documentation, please visit the [**Documentation**](https://poku.io/docs/category/documentation) and [**Examples**](https://poku.io/docs/category/examples) sections in the [**Poku**'s website](https://poku.io). --- ### Tutorials **Poku** offers _mini-lessons_ for different users needs in the [**Quick Tutorials**](https://poku.io/docs/category/quick-tutorials) section. --- ### Common Issues (FAQ) - [Avoiding conflicts in environments with multiple platforms installed](https://poku.io/docs/tutorials/cross-platform#recommendations). - [Properly running asynchronous tests on the same file](https://poku.io/docs/examples/promises). - [Using **Poku** without installing it on **Deno**](https://github.com/wellwelwel/poku/discussions/565). - Migrating: - [From version **3.x.x** to version **4.x.x**](https://github.com/wellwelwel/poku/issues/1006). - [From version **2.x.x** to version **3.x.x**](https://github.com/wellwelwel/poku/issues/801). - [From version **1.x.x** to version **2.x.x**](https://github.com/wellwelwel/poku/issues/533). --- ## Quick Comparisons ### Performance **Poku** is [continuously tested](https://github.com/wellwelwel/poku/blob/main/.github/workflows/ci_benchmark.yml) to ensure the following average expectations for basic usage: - ~**4.6x** faster than [**Jest**](https://github.com/jestjs/jest) (v30.3.0) - ~**3.5x** faster than [**Vitest**](https://github.com/vitest-dev/vitest) (v4.1.2) > - You can see how the tests are run and compared in the [benchmark](https://github.com/wellwelwel/poku/tree/main/benchmark) directory. > - [Comparing **Poku** and native test runners _(discussion)_](https://github.com/wellwelwel/poku/discussions/740). --- ### Installation Size [![Install Size](https://packagephobia.com/badge?p=poku)](https://pkg-size.dev/poku) - [~**206x** lighter than **Vitest**](https://pkg-size.dev/vitest@3.2.4) - [~**165x** lighter than **Jest**](https://pkg-size.dev/jest@30.0.5) - [~**52x** lighter than **Mocha**](https://pkg-size.dev/mocha@11.7.1) > **Poku** size ensures _cost-saving_ **CI** for services that charge for storage and usage. --- ## Security Policy [![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_codeql.yml?event=push&label=&branch=main&logo=github&logoColor=white&color=f368e0)](https://github.com/wellwelwel/poku/actions/workflows/ci_codeql.yml?query=branch%3Amain) Please check the [**SECURITY.md**](https://github.com/wellwelwel/poku/blob/main/SECURITY.md). --- ## Contributing See the [**Contributing Guide**](https://github.com/wellwelwel/poku/blob/main/CONTRIBUTING.md) and please follow our [**Code of Conduct**](https://github.com/wellwelwel/poku/blob/main/CODE_OF_CONDUCT.md) πŸš€ --- ## Acknowledgements ### Contributors My thanks to everyone who has dedicated their time and effort to improving **Poku**. [![Contributors](https://opencollective.com/poku/contributors.svg?width=890&button=false)](https://opencollective.com/poku/contributors.svg?button=false) ### Sponsors Really thanks to everyone who has supported and keeps supporting my work. > _Also for the private ones, who don't appear here_ πŸ•΅ [![Sponsors](https://wellwelwel.github.io/wellwelwel/sponsors.svg?v=1)](https://github.com/sponsors/wellwelwel) --- ## License **Poku** is under the [**MIT License**](https://github.com/wellwelwel/poku/blob/main/LICENSE).
Copyright Β© 2024-present [Weslley AraΓΊjo](https://github.com/wellwelwel) and **Poku** [contributors](https://github.com/wellwelwel/poku/graphs/contributors). [node-version-url]: https://github.com/nodejs/node [bun-version-url]: https://github.com/oven-sh/bun [deno-version-url]: https://github.com/denoland/deno