https://github.com/wellwelwel/poku

🐷 Poku makes testing easy for Node.js, Bun, Deno, and you at the same time.
https://github.com/wellwelwel/poku

assert assertion bdd bun cross-platform deno dependency-free e2e e2e-testing integration-testing javascript kill-port nodejs tdd test-runner testing typescript unit-testing watch zero-dependency

Last synced: 13 days ago
JSON representation

🐷 Poku makes testing easy for Node.js, Bun, Deno, and you at the same time.

Host: GitHub
URL: https://github.com/wellwelwel/poku
Owner: wellwelwel
License: mit
Created: 2024-02-13T06:36:15.000Z (about 1 year ago)
Default Branch: main
Last Pushed: 2025-04-11T06:24:31.000Z (15 days ago)
Last Synced: 2025-04-13T04:00:00.805Z (13 days ago)
Topics: assert, assertion, bdd, bun, cross-platform, deno, dependency-free, e2e, e2e-testing, integration-testing, javascript, kill-port, nodejs, tdd, test-runner, testing, typescript, unit-testing, watch, zero-dependency
Language: TypeScript
Homepage: https://poku.io
Size: 12.2 MB
Stars: 901
Watchers: 5
Forks: 18
Open Issues: 5
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md

Awesome Lists containing this project

awesome-made-by-brazilians - poku

README

        




# 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)



> [!IMPORTANT]

>

> **Poku `v3`** is here! 🎉

>

> - To check out what's changed, follow the [**Issue #801**](https://github.com/wellwelwel/poku/issues/801).

> - For `v2` documentation, see the [**previous version's documentation**](https://poku.io/docs/2.x.x) and [**README**](https://github.com/wellwelwel/poku/tree/2.x.x?tab=readme-ov-file#readme).


---

## 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-).

 High **isolation** level per file


 **Performant** and **lightweight**


 Auto detect **ESM**, **CJS**, and **TypeScript** files


 Run the **same test suite** for [**Node.js**][node-version-url], [**Bun**][bun-version-url], and [**Deno**][deno-version-url]


 Easily handle **servers**, **processes**, **ports**, and even **containers** ✨

---

## Quickstart

###  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

```

---

###  Test

test/file.test.mjs


```ts

import { assert } from 'poku';

assert(true, 'Poku will describe it 🐷');

```

---

###  Run

Node.js (and TypeScript)

Bun

Deno


```bash

npx poku

```

```bash

bun poku

```

```bash

deno run npm:poku

```

---

## Features

###  Essentials

  

    poku

    🧪 Test runner.

  

  

    assert

    🔍 Test assertion (Node.js familiar API).

  

  

    strict

    🔬 Strict test assertion (Node.js familiar API).

  

###  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.

  

###  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.

  

> _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

- [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 on **Deno** and alternatives to **JSR**](https://github.com/wellwelwel/poku/discussions/565).

- [Migrating from version **2.x** to version **3.x**](https://github.com/wellwelwel/poku/issues/801).

---

## Quick Comparisons

### Performance

**Poku** is [continuously tested](https://github.com/wellwelwel/poku/blob/main/.github/workflows/ci_benchmark.yml) to ensure the following expectations for basic usage:

- ~**4x** faster than [**Jest**](https://github.com/jestjs/jest) (v29.7.0)

- ~**4x** faster than [**Vitest**](https://github.com/vitest-dev/vitest) (v3.0.6)

- ~**1x** faster than [**Mocha**](https://github.com/mochajs/mocha) (v11.1.0) — _even with test file isolation_

> - 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)

- [~**230x** lighter than **Vitest**](https://pkg-size.dev/vitest)

- [~**130x** lighter than **Jest**](https://pkg-size.dev/jest)

- [~**30x** lighter than **Mocha** + **Chai**](https://pkg-size.dev/mocha%20chai)

> **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

[![Contributors](https://img.shields.io/github/contributors/wellwelwel/poku?color=9c88ff)](https://github.com/wellwelwel/poku/graphs/contributors)

[![Contributors](https://opencollective.com/poku/contributors.svg?width=890&button=false)](https://opencollective.com/poku/contributors.svg?button=false)

### Sponsors

[![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

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/wellwelwel/poku

Awesome Lists containing this project

README