poku 1.1.1 → 1.3.0

package/README.md

@@ -17,9 +17,7 @@
 
 <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**][node-version-url], [**Bun**][bun-version-url] and [**Deno**][deno-version-url], which allows parallel or sequential runs and high isolation level.
-
-> **Poku** starts from the premise where tests come to help, not overcomplicate.
+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**.
 
 [![Node.js Version][node-version-image]][node-version-url]
 [![Bun Version][bun-version-image]][bun-version-url]
@@ -33,25 +31,51 @@
 
 ## Why Poku?
 
-Runs test files in an individual process, shows progress and exits 🪄
+> **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 🧙🏻
 
-- **Poku** is designed to be highly intuitive
 - 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**][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
 
 ---
 
-- Totally **dependency-free**
+- <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
 
 ---
 
+| 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"> |
+
+- 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).
+
+---
+
+**Poku** also includes the `assert` method, keeping everything as it is, but providing human readability:
+
+```ts
+import { assert } from 'poku'; // Node and Bun
+import { assert } from 'npm:poku'; // Deno
+
+assert(true);
+assert.deepStrictEqual(1, '1', 'My optional custom message');
+```
+
+> <img src=".github/assets/readme/assert.png" width="468" />
+
+---
+
 ## Install
 
 ### **Node.js**
@@ -107,7 +131,7 @@ import { poku } from 'npm:poku';
 ```ts
 import { poku } from 'poku';
 
-await poku(['./a', './b']);
+await poku(['targetDirA', 'targetDirB']);
 ```
 
 > <img src=".github/assets/readme/deno.svg" width="24" />
@@ -115,7 +139,7 @@ await poku(['./a', './b']);
 ```ts
 import { poku } from 'npm:poku';
 
-await poku(['./a', './b']);
+await poku(['targetDirA', 'targetDirB']);
 ```
 
 ### CLI
@@ -123,54 +147,179 @@ await poku(['./a', './b']);
 > <img src=".github/assets/readme/node-js.svg" width="24" />
 
 ```bash
-npx poku --include='./a,./b'
+npx poku targetDirA,targetDirB
 ```
 
 > <img src=".github/assets/readme/bun.svg" width="24" />
 
 ```bash
-bun poku --include='./a,./b'
+bun poku targetDirA,targetDirB
 ```
 
 > <img src=".github/assets/readme/deno.svg" width="24" />
 
 ```bash
-deno run npm:poku --include='./a,./b'
+deno run npm:poku targetDirA,targetDirB
 ```
 
 ---
 
 ## Documentation
 
-> Documentation in Progress 🧑🏻‍🔧
+> 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(string | string[])`
+### `poku(targetDirs: string | string[])`
 
 #### Include directories
 
+- **in-code**
+
 ```ts
-poku('./targetDir');
+poku('targetDir');
 ```
 
 ```ts
-poku(['./targetDirA', './targetDirB']);
+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'
+npx poku --include='targetDir'
 ```
 
 ```bash
-npx poku --include='./targetDirA,./targetDirB'
+npx poku --include='targetDirA,targetDirB'
 ```
 
 ---
 
-### `poku(string | string[], configs: Configs)`
+### `poku(targetDirs: string | string[], configs?: Configs)`
+
+#### `parallel: boolean`
+
+Determines the mode of test execution across **sequential** or **parallel** modes.
 
-#### `filter`
+- **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.
 
@@ -194,7 +343,7 @@ poku(['...'], {
  */
 
 poku(['...'], {
-  filter: /\.(m)?(j|t)?s$/,
+  filter: /\.(m)?(j|t)s$/,
   // filter: /\.(js|ts|mjs|mts)$/,
 });
 ```
@@ -204,13 +353,19 @@ poku(['...'], {
 ```bash
 # Testing only a specific file
 
-npx poku --include='...' --filter='some-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 --include='...' --filter='unit'
+npx poku --filter='unit' ./test
 ```
 
 - **Environment Variable**
@@ -220,45 +375,160 @@ npx poku --include='...' --filter='unit'
 ```bash
 # Testing only a specific file
 
-FILTER='some-file' npx poku --include='...'
+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 --include='...'
+FILTER='unit' npx poku ./test
 ```
 
 ---
 
-#### `parallel`
+#### `exclude: RegExp | RegExp[]`
 
-Determines the mode of test execution across **parallelism** or **sequential** modes.
+> Exclude by path using Regex to match only the files that should be performed.
+>
+> _Since **1.2.0**_
+
+- **in-code**:
 
 ```ts
 /**
- * @default
- *
- * Sequential mode
+ * Excluding  directories from tests
  */
 
 poku(['...'], {
-  parallel: false,
+  exclude: /\/(helpers|tools)\//,
 });
 ```
 
 ```ts
 /**
- * Parallel mode
+ * Excluding  directories from tests
  */
 
 poku(['...'], {
-  parallel: true,
+  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
+```
+
+---
+
+### 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, 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**](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.
+
+---
+
+## Community
+
+I'm continuously working to improve **Poku**. If you've got something interesting to share, feel free to submit a [**Pull Request**](https://github.com/wellwelwel/poku/compare). If you notice something wrong, I'd appreciate if you'd open an [**Issue**](https://github.com/wellwelwel/poku/issues/new).
+
 ---
 
-## Documentation in Progress...
+## Acknowledgements
 
-> 🧑🏻‍🎓 Soon documenting all options and **Poku**'s usage variations.
+- [**Contributors**](https://github.com/wellwelwel/poku/graphs/contributors)

package/lib/@types/list-files.d.ts

@@ -0,0 +1,14 @@
+export type Configs = {
+    /**
+     * Filter by path to match only the files that should be performed.
+     *
+     * @default /\.test\./i
+     */
+    filter?: RegExp;
+    /**
+     * Exclude by path to match only the files that should be performed.
+     *
+     * @default undefined
+     */
+    exclude?: RegExp | RegExp[];
+};

package/lib/@types/list-files.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,3 +1,4 @@
+import type { Configs as ListFilesConfigs } from './list-files.js';
 export type Configs = {
     /**
      * By setting `true`, **Poku** won't exit the process and will return the exit code (`0` or `1`).
@@ -26,16 +27,16 @@ export type Configs = {
      * @default false
      */
     quiet?: boolean;
-    /**
-     * Filter by path to match only the files that should be performed.
-     *
-     * @default /\.test\./i
-     */
-    filter?: RegExp;
     /**
      * Determines the mode of test execution.
      *
      * @default false
      */
     parallel?: boolean;
-};
+    /**
+     * Determines the platform for test execution.
+     *
+     * @default 'node'
+     */
+    platform?: 'node' | 'bun' | 'deno';
+} & ListFilesConfigs;

package/lib/bin/index.js

@@ -1,12 +1,21 @@
 #! /usr/bin/env node
 "use strict";
+var _a, _b;
 Object.defineProperty(exports, "__esModule", { value: true });
-const get_files_js_1 = require("../helpers/get-files.js");
+const list_files_js_1 = require("../modules/list-files.js");
 const get_arg_js_1 = require("../helpers/get-arg.js");
 const index_js_1 = require("../index.js");
-const rawDirs = (0, get_arg_js_1.getArg)('include');
-const rawFilter = (0, get_arg_js_1.getArg)('filter');
-const dirs = (rawDirs === null || rawDirs === void 0 ? void 0 : rawDirs.split(',')) || [];
+const get_runtime_js_1 = require("../helpers/get-runtime.js");
+const dirs = ((0, get_arg_js_1.hasArg)('include')
+    ? (_a = (0, get_arg_js_1.getArg)('include')) === null || _a === void 0 ? void 0 : _a.split(',')
+    : (_b = (0, get_arg_js_1.getLastParam)()) === null || _b === void 0 ? void 0 : _b.split(',')) || [];
+const platform = (0, get_arg_js_1.getArg)('platform');
+const filter = (0, get_arg_js_1.getArg)('filter');
+const parallel = (0, get_arg_js_1.hasArg)('parallel');
+const exclude = (0, get_arg_js_1.getArg)('exclude');
 (0, index_js_1.poku)(dirs, {
-    filter: rawFilter ? new RegExp((0, get_files_js_1.escapeRegExp)(rawFilter)) : undefined,
+    platform: (0, get_runtime_js_1.platformIsValid)(platform) ? platform : undefined,
+    filter: filter ? new RegExp((0, list_files_js_1.escapeRegExp)(filter)) : undefined,
+    exclude: exclude ? new RegExp((0, list_files_js_1.escapeRegExp)(exclude)) : undefined,
+    parallel,
 });

package/lib/helpers/format.d.ts

@@ -1,5 +1,6 @@
 export declare const format: {
     counter: (current: number, total: number, pad?: string) => string;
+    dim: (value: string) => string;
     bold: (value: string) => string;
     underline: (value: string) => string;
     info: (value: string) => string;

package/lib/helpers/format.js

@@ -7,6 +7,7 @@ exports.format = {
         const totalDigits = String(total).length;
         return (0, pad_js_1.padStart)(String(current), totalDigits, pad);
     },
+    dim: (value) => `\x1b[2m${value}\x1b[0m`,
     bold: (value) => `\x1b[1m${value}\x1b[0m`,
     underline: (value) => `\x1b[4m${value}\x1b[0m`,
     info: (value) => `\x1b[36m${value}\x1b[0m`,

package/lib/helpers/get-arg.d.ts

@@ -1 +1,3 @@
 export declare const getArg: (arg: string) => string | undefined;
+export declare const hasArg: (arg: string) => boolean;
+export declare const getLastParam: () => string;

package/lib/helpers/get-arg.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getArg = void 0;
+exports.getLastParam = exports.hasArg = exports.getArg = void 0;
 const node_process_1 = __importDefault(require("process"));
 const [, , ...args] = node_process_1.default.argv;
 const getArg = (arg) => {
@@ -14,3 +14,9 @@ const getArg = (arg) => {
     return undefined;
 };
 exports.getArg = getArg;
+const hasArg = (arg) => args.some((a) => a.startsWith(`--${arg}`));
+exports.hasArg = hasArg;
+const getLastParam = () => {
+    return args[args.length - 1];
+};
+exports.getLastParam = getLastParam;

package/lib/helpers/get-runtime.d.ts

@@ -1 +1,4 @@
-export declare const getRuntime: () => "deno" | "bun" | "node";
+import type { Configs } from '../@types/poku.ts';
+export declare const supportedPlatforms: ReadonlyArray<Configs['platform']>;
+export declare const platformIsValid: (platform: unknown) => platform is "node" | "bun" | "deno" | undefined;
+export declare const getRuntime: (configs?: Configs) => (typeof supportedPlatforms)[number];

package/lib/helpers/get-runtime.js

@@ -1,7 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getRuntime = void 0;
-const getRuntime = () => {
+exports.getRuntime = exports.platformIsValid = exports.supportedPlatforms = void 0;
+exports.supportedPlatforms = [
+    'node',
+    'bun',
+    'deno',
+];
+const platformIsValid = (platform) => {
+    if (typeof platform === 'string' &&
+        exports.supportedPlatforms.some((supportedPlatform) => supportedPlatform === platform))
+        return true;
+    return false;
+};
+exports.platformIsValid = platformIsValid;
+const getRuntime = (configs) => {
+    if ((configs === null || configs === void 0 ? void 0 : configs.platform) && (0, exports.platformIsValid)(configs.platform))
+        return configs.platform;
     if (typeof Deno !== 'undefined')
         return 'deno';
     if (typeof Bun !== 'undefined')

package/lib/helpers/hr.js

@@ -8,7 +8,7 @@ const node_os_1 = require("os");
 const node_process_1 = __importDefault(require("process"));
 const hr = () => {
     const columns = node_process_1.default.stdout.columns;
-    const line = '_'.repeat(columns - 10 || 0);
+    const line = '_'.repeat(columns - 10 || 30);
     console.log(`\x1b[2m${line}\x1b[0m${node_os_1.EOL}`);
 };
 exports.hr = hr;

package/lib/helpers/parseAsssetion.d.ts

@@ -0,0 +1,9 @@
+export type ParseAssertionOptions = {
+    message?: string | Error;
+    defaultMessage?: string;
+    actual?: string;
+    expected?: string;
+    throw?: boolean;
+    hideDiff?: boolean;
+};
+export declare const parseAssertion: (cb: () => void, options: ParseAssertionOptions) => void;