poku 1.3.1 → 1.5.0

package/README.md

@@ -4,75 +4,102 @@
 [bun-version-image]: https://img.shields.io/badge/Bun->=0.5.3-f471b5
 [deno-version-url]: https://github.com/denoland/deno
 [deno-version-image]: https://img.shields.io/badge/Deno->=1.30.0-70ffaf
-[npm-image]: https://img.shields.io/npm/v/poku.svg?color=3dc1d3
-[npm-url]: https://npmjs.org/package/poku
+[typescript-url]: https://github.com/microsoft/TypeScript
+[typescript-version-image]: https://img.shields.io/badge/TypeScript->=5.0.2-3077c6
 [ci-url]: https://github.com/wellwelwel/poku/actions/workflows/ci.yml?query=branch%3Amain
 [ci-image]: https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci.yml?event=push&style=flat&label=CI&branch=main
 [ql-url]: https://github.com/wellwelwel/poku/actions/workflows/codeql.yml?query=branch%3Amain
 [ql-image]: https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/codeql.yml?event=push&style=flat&label=Code%20QL&branch=main
-[license-url]: https://github.com/wellwelwel/poku/blob/main/LICENSE
-[license-image]: https://img.shields.io/npm/l/poku.svg?maxAge=2592000&color=9c88ff
 
 # Poku
 
 <img align="right" width="128" height="128" alt="Logo" src=".github/assets/readme/poku.svg">
 
-A flexible and easy-to-use **Test Runner** for [Node.js][node-version-url], [Bun][bun-version-url] and [Deno][deno-version-url] that allows you to run **parallel** and **sequential** tests, plus **high isolation level per test file**.
+**Poku** is your test runner pet for [**Node.js**][node-version-url], [**Bun**][bun-version-url] and [**Deno**][deno-version-url] combining **flexibility**, **parallel** and **sequential** runs, **human-friendly assertion errors** and **high isolation level**.
 
 [![Node.js Version][node-version-image]][node-version-url]
 [![Bun Version][bun-version-image]][bun-version-url]
 [![Deno Version][deno-version-image]][deno-version-url]
-[![NPM Version][npm-image]][npm-url]
-[![License][license-image]][license-url]
+[![TypeScript Version][typescript-version-image]][typescript-url]
 [![GitHub Workflow Status (with event)][ci-image]][ci-url]
 [![GitHub Workflow Status (with event)][ql-image]][ql-url]
 
+Enjoying **Poku**? Consider giving him a star ⭐️
+
+---
+
+🐷 [**Documentation Website**](https://poku.dev) • 🔬 [**Compare Poku with the Most Popular Test Runners**](https://poku.dev/docs/comparing)
+
 ---
 
 ## 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 🧙🏻
+Don't worry about `describe`, `it`, `beforeEach` and everything else 🚀
+
+> You don't need to learn what you already know ✨
 
 - Supports **ESM** and **CJS**
 - Designed to be highly intuitive
-- No need to compile **TypeScript**
+- No need to compile [**TypeScript**][typescript-url] \*
 - Compatible with **Coverage** tools
 - Allows both **in-code** and **CLI** usage
 - [**Node.js**][node-version-url], [**Bun**][bun-version-url] and [**Deno**][deno-version-url] compatibility
 - Zero configurations, except you want
-- No constraints or rules, code in your own signature style
+- Poku adapts to your test, not the other way around
+- [**And much more!**](https://poku.dev)
 
 ---
 
-- <img src="https://img.shields.io/bundlephobia/min/poku?label=Final%20Size">
-- **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
+- <img src="https://img.shields.io/bundlephobia/min/poku">
+- **Zero** external dependencies 🌱
 
 ---
 
-| Sequential                                                   | Parallel                                                   |
-| ------------------------------------------------------------ | ---------------------------------------------------------- |
-| `npx poku test/unit,test/integration`                        | `npx poku --parallel test/unit,test/integration`           |
-| <img src=".github/assets/readme/sequential.png" width="360"> | <img src=".github/assets/readme/parallel.png" width="360"> |
+## Documentation
 
-- By default, **Poku** searches for all _`.test.`_ files, but you can customize it using the option [`filter`](https://github.com/wellwelwel/poku#filter-rexexp).
-- The same idea for [**Bun**][bun-version-url] and [**Deno**][deno-version-url] (see bellow).
+- See detailed usage in [**Documentation**](https://poku.dev/docs/category/documentation) section for **Poku**'s **CLI**, **API (_in-code_)** and **assert**, advanced concepts and much more.
 
 ---
 
-**Poku** also includes the `assert` method, keeping everything as it is, but providing human readability:
+## Overview
+
+| Sequential                                         | Concurrent                                       |
+| -------------------------------------------------- | ------------------------------------------------ |
+| <img src=".github/assets/readme/sequential.png" /> | <img src=".github/assets/readme/parallel.png" /> |
+
+- By default, **Poku**:
+  - Searches for all _`.test.`_ and `.spec.` files, but you can customize it using the option [**`filter`**](https://poku.dev/docs/documentation/poku/configs/filter).
+  - Uses `sequential` mode.
+- You can use concurrecy by use the flag `--parallel` for **CLI** or the option `parallel` to `true` in **API** (_in-code_) usage.
+
+> Follow the same idea for [**Bun**][bun-version-url] and [**Deno**][deno-version-url].
+
+---
+
+**Poku** also includes the `assert` method, keeping everything as it is, but providing human readability and automatic `describe` and `it`:
+
+> Compatible with **Node.js**, **Bun** and **Deno**.
 
 ```ts
 import { assert } from 'poku'; // Node and Bun
 import { assert } from 'npm:poku'; // Deno
 
-assert(true);
-assert.deepStrictEqual(1, '1', 'My optional custom message');
+const actual = '1';
+
+assert(actual, 'My first assert');
+assert.deepStrictEqual(actual, 1, 'My first assert error');
 ```
 
-> <img src=".github/assets/readme/assert.png" width="468" />
+| Using `poku`                                        | Using `node`                                        |
+| --------------------------------------------------- | --------------------------------------------------- |
+| <img src=".github/assets/readme/assert-poku.png" /> | <img src=".github/assets/readme/assert-node.png" /> |
+
+- ❌ Both cases finish with `code 1`, as expected
+- 🧑🏻‍🎓 The `message` param is optional, as it's in **Node.js**
+- 💚 Yes, you can use **Poku**'s `assert` running `node ./my-file.js`
+- 🐷 Unlike most, **Poku** adapts to your test, not the other way around
+
+> [**See the complete assert's documentation**](https://poku.dev/docs/documentation/assert).
 
 ---
 
@@ -80,66 +107,48 @@ assert.deepStrictEqual(1, '1', 'My optional custom message');
 
 ### **Node.js**
 
-> <img src=".github/assets/readme/node-js.svg" width="24" />
-
 ```bash
-npm install --save-dev poku
+npm i -D poku
 ```
 
 ### TypeScript (Node.js)
 
-> <img src=".github/assets/readme/node-js.svg" width="24" />
-> <img src=".github/assets/readme/plus.svg" width="24" />
-> <img src=".github/assets/readme/typescript.svg" width="24" />
-
 ```bash
-npm install --save-dev poku tsx
+npm i -D poku tsx
 ```
 
 ### Bun
 
-> <img src=".github/assets/readme/bun.svg" width="24" />
-> <img src=".github/assets/readme/plus.svg" width="24" />
-> <img src=".github/assets/readme/typescript.svg" width="24" />
-
 ```bash
-bun add --dev poku
+bun add -d poku
 ```
 
 ### **Deno**
 
-> <img src=".github/assets/readme/deno.svg" width="24" />
-> <img src=".github/assets/readme/plus.svg" width="24" />
-> <img src=".github/assets/readme/typescript.svg" width="24" />
-
 ```ts
 import { poku } from 'npm:poku';
 ```
 
-- **Poku** requires these permissions by default: `--allow-read`, `--allow-env` and `--allow-run`.
-
 ---
 
-## Basic Usage
+## Quick Start
 
 ### In-code
 
-> <img src=".github/assets/readme/node-js.svg" width="24" />
-> <img src=".github/assets/readme/plus.svg" width="24" />
-> <img src=".github/assets/readme/bun.svg" width="24" />
+#### Node.js and Bun
 
 ```ts
 import { poku } from 'poku';
 
-await poku(['targetDirA', 'targetDirB']);
+await poku(['targetDir']);
 ```
 
-> <img src=".github/assets/readme/deno.svg" width="24" />
+#### Deno
 
 ```ts
 import { poku } from 'npm:poku';
 
-await poku(['targetDirA', 'targetDirB']);
+await poku(['targetDir']);
 ```
 
 ### CLI
@@ -147,454 +156,24 @@ await poku(['targetDirA', 'targetDirB']);
 > <img src=".github/assets/readme/node-js.svg" width="24" />
 
 ```bash
-npx poku targetDirA,targetDirB
+npx poku targetDir
 ```
 
 > <img src=".github/assets/readme/bun.svg" width="24" />
 
 ```bash
-bun poku targetDirA,targetDirB
+bun poku targetDir
 ```
 
 > <img src=".github/assets/readme/deno.svg" width="24" />
 
 ```bash
-deno run npm:poku targetDirA,targetDirB
+deno run npm:poku targetDir
 ```
 
 ---
 
-## 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**
-
-```ts
-poku('targetDir');
-```
-
-```ts
-poku(['targetDirA', 'targetDirB']);
-```
-
-- **CLI**
-
-By setting the directories as the last argument:
-
-> _Since **1.3.0**_
-
-```bash
-npx poku targetDir
-```
-
-```bash
-npx poku targetDirA,targetDirB
-```
-
-By using `--include` option:
-
-> _Since **1.0.0**_
-
-```bash
-npx poku --include='targetDir'
-```
-
-```bash
-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**
-
-```ts
-/**
- * @default
- *
- * Sequential mode
- */
-
-poku(['...'], {
-  parallel: false,
-});
-```
-
-```ts
-/**
- * Parallel mode
- */
-
-poku(['...'], {
-  parallel: true,
-});
-```
-
-- **CLI**
-
-> _Since **1.2.0**_
-
-```bash
-# 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**
-
-```ts
-/**
- * Force Node.js (or tsx for TypeScript)
- *
- * @default 'node'
- */
-
-poku('...', {
-  platform: 'node',
-});
-```
-
-```ts
-/**
- * Force Bun
- */
-
-poku('...', {
-  platform: 'bun',
-});
-```
-
-```ts
-/**
- * Force Deno
- */
-
-poku('...', {
-  platform: 'deno',
-});
-```
-
-- **CLI**
-
-```bash
-# Normal
-
-npx      poku      --platform=node  ./test
-bun      poku      --platform=bun   ./test
-deno run npm:poku  --platform=deno  ./test
-```
-
-```bash
-# 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**
-
-```ts
-/**
- * @default
- *
- * Testing all `*.test.*` files.
- */
-
-poku(['...'], {
-  filter: /\.test\./,
-});
-```
-
-```ts
-/**
- * Testing all `ts`, `js`, `mts` and `mjs` files
- */
-
-poku(['...'], {
-  filter: /\.(m)?(j|t)s$/,
-  // filter: /\.(js|ts|mjs|mts)$/,
-});
-```
-
-- **CLI**
-
-```bash
-# Testing only a specific file
-
-npx poku --filter='some-file' ./test
-```
-
-```bash
-# Testing only a specific file
-
-npx poku --filter='some-file|other-file' ./test
-```
-
-```bash
-# 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.
-
-```bash
-# Testing only a specific file
-
-FILTER='some-file' npx poku ./test
-```
-
-```bash
-# Testing only a specific file
-
-FILTER='some-file|other-file' npx poku ./test
-```
-
-```bash
-# 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**:
-
-```ts
-/**
- * Excluding  directories from tests
- */
-
-poku(['...'], {
-  exclude: /\/(helpers|tools)\//,
-});
-```
-
-```ts
-/**
- * Excluding  directories from tests
- */
-
-poku(['...'], {
-  exclude: [/\/helpers\//, /\/tools\//],
-});
-```
-
-```ts
-/**
- * Excluding specific files from tests
- */
-
-poku(['...'], {
-  exclude: /(index|common).test.ts/,
-});
-```
-
-```ts
-/**
- * Excluding specific files from tests
- */
-
-poku(['...'], {
-  exclude: [/index.test.ts/, /common.test.ts/],
-});
-```
-
-```ts
-/**
- * Excluding directories and files from tests
- */
-
-poku(['...'], {
-  exclude: /\/(helpers|tools)\/|(index|common).test.ts/,
-});
-```
-
-```ts
-/**
- * Excluding directories and files from tests
- */
-
-poku(['...'], {
-  exclude: [/\/helpers\//, /\/tools\//, /index.test.ts/, /common.test.ts/],
-});
-```
-
-- **CLI**
-
-```bash
-# Excluding directories and files from tests
-
-npx poku --exclude='some-file-or-dir' ./test
-```
-
-```bash
-# Excluding directories and files from tests
-
-npx poku --exclude='some-file-or-dir|other-file-or-dir' ./test
-```
-
----
-
-#### `quiet`
-
-Perform tests with no logs.
-
-> This option overwrites all `log` settings by exiting with code and no logs (see bellow).
-
-- **in-code**
-
-```ts
-poku(['...'], {
-  quiet: true,
-});
-```
-
-- **CLI**
-
-> _Since **1.3.1**_
-
-```bash
-npx poku --quiet ./test
-```
-
----
-
-#### `log`
-
-##### `success`
-
-By default **Poku** doesn't shows succes logs, but you can enable it:
-
-- **in-code**
-
-```ts
-poku(['...'], {
-  log: {
-    success: true,
-  },
-});
-```
-
-- **CLI**
-
-> _Since **1.3.1**_
-
-```bash
-npx poku --log-success ./test
-```
-
----
-
-### Assert
-
-> _Since **1.3.0**_
->
-> [**Node.js**][node-version-url], [**Bun**][bun-version-url] and [**Deno**][deno-version-url] compatible.
-
-**Poku** includes the `assert` method native from [**Node.js**][node-version-url], keeping everything as it is, but providing human readability.<br/>
-It supports both [**Bun**][bun-version-url] and [**Deno**][deno-version-url].
-
-#### Migrating to **Poku**'s assert
-
-_But only if you want to, of course._
-
-> <img src=".github/assets/readme/node-js.svg" width="24" />
-> <img src=".github/assets/readme/plus.svg" width="24" />
-> <img src=".github/assets/readme/bun.svg" width="24" />
-
-```diff
-- import assert from 'node:assert';
-+ import { assert } from 'poku';
-
-assert(true);
-```
-
-> <img src=".github/assets/readme/deno.svg" width="24" />
-
-```diff
-- import assert from 'node:assert';
-+ import { assert } from 'npm:poku';
-
-assert(true);
-```
-
-#### 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**](https://nodejs.org/api/assert.html) from **Node.js**'s documentation.
-
----
-
-### `listFiles(targetDir: string, configs?: ListFilesConfigs)`
-
-> _Since **1.2.0**_
-
-Returns all files in a directory, independent of their depth.
-
-```ts
-listFiles('some-dir');
-```
-
-- You can use the `filter` and `exclude` options, as well as they are for **`poku`** method.
+To see the detailed documentation, please visit the [**Documentation**](https://poku.dev/docs/category/documentation) section in the [**Poku**'s website](https://poku.dev).
 
 ---
 

package/lib/@types/poku.d.ts

@@ -9,14 +9,19 @@ export type Configs = {
      */
     noExit?: boolean;
     /**
+     * @deprecated
      * Customize `stdout` options.
      */
     log?: {
         /**
+         * @deprecated
+         *
          * @default false
          */
         success?: boolean;
         /**
+         * @deprecated
+         *
          * @default true
          */
         fail?: boolean;
@@ -26,6 +31,12 @@ export type Configs = {
      *
      * @default false
      */
+    debug?: boolean;
+    /**
+     * This option overwrites the `debug` settings.
+     *
+     * @default false
+     */
     quiet?: boolean;
     /**
      * Determines the mode of test execution.