feat(assert): automatic describe it (#29)

* feat(assert): auto describe it

* fix(listFiles): force node_modules removal

* docs: improve description

* docs: improve documentation

* docs: fix broken links

* docs: improve documentation

* docs: improve documentation

* docs: improve description

* docs: improve image examples

* docs: improve installation examples

* docs: improve overview

* chore: remove marked goals

* feat: add debug option

* docs: improve documentation

.gitignore

@@ -2,4 +2,5 @@ node_modules
 .DS_Store
 /lib
 /ci
+/playground
 .env

README.md

@@ -28,13 +28,15 @@ Enjoying **Poku**? Consider giving him a star ⭐️
 
 ---
 
-🐷 [**Documentation Website**](https://poku.dev) • 🔬 [**Comparing Test Runners** (**Poku**, **Jest**, **Mocha**, **Vitest** and **AVA**)](https://poku.dev/docs/comparing)
+🐷 [**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
@@ -43,132 +45,130 @@ Enjoying **Poku**? Consider giving him a star ⭐️
 - 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
+- <img src="https://img.shields.io/bundlephobia/min/poku">
+- **Zero** external dependencies 🌱
 
 ---
 
 ## Documentation
 
-- See detailed specifications and usage in [**Documentation**](https://poku.dev/docs/category/documentation) section for queries, advanced concepts and much more.
+- 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.
 
 ---
 
 ## Overview
 
-| 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"> |
+| 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.
 
-- 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).
+> 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:
+**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).
 
 ---
 
 ## Install
 
 ### **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`.
-
 ---
 
 ## 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
 
 > <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
 ```
 
 ---

goals.md

@@ -1,11 +1,12 @@
-# Goals
+# 🧑🏻‍🎓 Goals
 
-## `fix:`
+## 🧑🏻‍🔧 `fix`
+
+- **assert:** improve logs for regex and functions inside arrays
 
 ---
 
-## `feat:`
+## 🚀 `feat`
 
-- **feat:** show message from `assert` like in popular "describe" and "it" if `describe` option is `true`
-- **feat:** show individual test execution time
-- **feat:** allow to limit concurrency in parallel runs
+- **cli:** show individual test execution time
+- **poku:** allow to limit concurrency in parallel runs

src/@types/poku.ts

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

src/bin/index.ts

@@ -4,6 +4,7 @@ import { escapeRegExp } from '../modules/list-files.js';
 import { getArg, getLastParam, hasArg } from '../helpers/get-arg.js';
 import { poku } from '../index.js';
 import { platformIsValid } from '../helpers/get-runtime.js';
+import { format } from '../helpers/format.js';
 
 const dirs =
  (hasArg('include')
@@ -14,15 +15,18 @@ const filter = getArg('filter');
 const exclude = getArg('exclude');
 const parallel = hasArg('parallel');
 const quiet = hasArg('quiet');
-const logSuccess = hasArg('log-success');
+const debug = hasArg('debug');
+
+if (hasArg('log-success'))
+ console.log(
+ `The flag ${format.bold('--log-success')} is deprecated. Use ${format.bold('--debug')} instead.`
+ );
 
 poku(dirs, {
  platform: platformIsValid(platform) ? platform : undefined,
  filter: filter ? new RegExp(escapeRegExp(filter)) : undefined,
  exclude: exclude ? new RegExp(escapeRegExp(exclude)) : undefined,
  parallel,
  quiet,
- log: {
- success: logSuccess,
- },
+ debug,
 });

src/helpers/format.ts

@@ -8,9 +8,15 @@ export const format = {
  dim: (value: string) => `\x1b[2m${value}\x1b[0m`,
  bold: (value: string) => `\x1b[1m${value}\x1b[0m`,
  underline: (value: string) => `\x1b[4m${value}\x1b[0m`,
- info: (value: string) => `\x1b[36m${value}\x1b[0m`,
+ info: (value: string) => `\x1b[94m${value}\x1b[0m`,
  success: (value: string) => `\x1b[32m${value}\x1b[0m`,
- fail: (value: string) => `\x1b[31m${value}\x1b[0m`,
+ fail: (value: string) => `\x1b[91m${value}\x1b[0m`,
+ bg: (bg: number, text: string) => {
+ const padding = ' '.repeat(1);
+ const paddedText = `${padding}${text}${padding}`;
+
+ return `\x1b[${bg}m\x1b[1m${paddedText}\x1b[0m`;
+ },
 };
 
 export const getLargestStringLength = (arr: string[]): number =>

src/helpers/hr.ts

@@ -1,20 +1,8 @@
 import { EOL } from 'node:os';
 import process from 'node:process';
 
-let lastLenght: number = 0;
+export const hr = () => {
+ const line = '⎯'.repeat(process.stdout.columns - 10);
 
-export const hr = (size?: number) => {
- const pad = 10;
- const limit = process.stdout.columns - pad;
- const fileLenght = typeof size === 'number' ? Math.floor(size / 2) + pad : 0;
- const columns =
- fileLenght > 0 && fileLenght <= limit
- ? fileLenght
- : lastLenght > 0
- ? lastLenght
- : limit;
- const line = '⎯'.repeat(columns);
- lastLenght = columns;
-
- console.log(`${EOL}\x1b[2m${line}\x1b[0m${EOL}`);
+ console.log(`${EOL}\x1b[2m\x1b[90m${line}\x1b[0m${EOL}`);
 };

src/helpers/logs.ts

@@ -3,8 +3,4 @@ import { Configs } from '../@types/poku.js';
 export const isQuiet = (configs?: Configs): boolean =>
  typeof configs?.quiet === 'boolean' && Boolean(configs?.quiet);
 
-export const showSuccesses = (configs?: Configs): boolean =>
- Boolean(configs?.log?.success);
-
-export const showFailures = (configs?: Configs): boolean =>
- typeof configs?.log?.fail === 'undefined' || Boolean(configs?.log?.fail);
+export const isDebug = (configs?: Configs): boolean => Boolean(configs?.debug);