poku 1.21.0 → 1.22.0

package/README.md

@@ -1,20 +1,20 @@
 <div align="center">
-<img width="125" height="125" alt="Logo" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/poku.svg">
+<img height="180" alt="Poku's Logo" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/poku.svg">
 
 # Poku
 
 Enjoying **Poku**? Give him a star to show your support 🌟
 
-[![NPM Downloads][downloads-image]][downloads-url]
-[![Coverage][coverage-image]][coverage-url]
-[![License][license-image]][license-url]<br />
-[![GitHub Workflow Status (with event)][ci-linux-image]][ci-linux-url]
-[![GitHub Workflow Status (with event)][ci-osx-image]][ci-osx-url]
-[![GitHub Workflow Status (with event)][ci-windows-image]][ci-windows-url]
+[![NPM Downloads](https://img.shields.io/npm/dt/poku.svg?logo=npm&logoColor=white&color=1e90ff)](https://www.npmjs.com/package/poku)
+[![Coverage](https://img.shields.io/codecov/c/github/wellwelwel/poku)](https://app.codecov.io/github/wellwelwel/poku)
+[![License](https://img.shields.io/npm/l/poku?maxAge=2592000&color=9c88ff)](https://github.com/wellwelwel/poku/blob/main/LICENSE)<br />
+[![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=white)](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=white)](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=windows&logoColor=white)](https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-windows.yml?query=branch%3Amain)
 
 ---
 
-🐷 [Documentation](https://poku.io)<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>🧪 [Examples](https://poku.io/docs/category/examples)<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>🔬 [Compare the Most Popular Test Runners](https://poku.io/docs/comparing)
+🐷 [Website](https://poku.io/)<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>📒 [Documentation](https://poku.io/docs/category/documentation)<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>🧪 [Examples](https://poku.io/docs/category/examples)<span>&nbsp;&nbsp;•&nbsp;&nbsp;</span>🧑🏻‍🎓 [Quick Tutorials](https://poku.io/docs/category/quick-tutorials)
 
 </div>
 
@@ -22,7 +22,7 @@ Enjoying **Poku**? Give him a star to show your support 🌟
 
 ## Why does Poku exist?
 
-💡 **Poku** makes testing easy and brings the [native **JavaScript** syntax back to tests](https://poku.io/docs/philosophy), letting you to write tests intuitively — _just like in real **JavaScript** code_.
+💡 **Poku** makes testing easy and brings the [native **JavaScript** syntax back to tests](https://poku.io/docs/philosophy#javascript-essence-for-tests-), letting you to write tests intuitively — _just like in real **JavaScript** code_.
 
 <img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> No configurations<br />
 <span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span><img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Auto detect **ESM**, **CJS**, and **TypeScript** files<br />
@@ -154,7 +154,6 @@ deno run npm:poku
 ### Helpers
 
 - [**test**](https://poku.io/docs/documentation/helpers/test), [**describe**](https://poku.io/docs/documentation/helpers/describe) and [**it**](https://poku.io/docs/documentation/helpers/it) _(organize, group, and isolate tests)_
-- [**watch**](https://poku.io/docs/documentation/poku/options/watch) _(watch for changes and re-run related test files)_
 - [**beforeEach**](https://poku.io/docs/category/-before-and-after-each) and [**afterEach**](https://poku.io/docs/category/-before-and-after-each) _(hooks for test setup and teardown)_
 - [**docker**](https://poku.io/docs/documentation/helpers/containers) _(build, start, compose, stop, remove, and test containers)_
 - [**startScript**](https://poku.io/docs/documentation/helpers/startScript) _(run **package.json** scripts in background)_
@@ -163,7 +162,14 @@ deno run npm:poku
 - [**waitForPort**](https://poku.io/docs/documentation/helpers/processes/wait-for-port) _(wait for specified ports to become active)_
 - [**waitForExpectedResult**](https://poku.io/docs/documentation/helpers/processes/wait-for-expected-result) _(retry until an expected result or times out)_
 - [**getPIDs**](https://poku.io/docs/documentation/helpers/processes/get-pids) _(debug processes IDs using ports and port ranges)_
-- _and much more_ 👇🏻
+
+### Common Options
+
+- [**watch**](https://poku.io/docs/documentation/poku/options/watch) _(watch for changes and re-run related test files)_
+- [**parallel**](https://poku.io/docs/documentation/poku/options/parallel) _(run tests in parallel)_
+- [**debug**](https://poku.io/docs/documentation/poku/options/debug) _(shows all logs)_
+
+> _and much more_ 👇🏻
 
 ---
 
@@ -173,6 +179,19 @@ To see the detailed documentation, please visit the [**Documentation**](https://
 
 ---
 
+### 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).
+
+---
+
 ## 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) 🚀
@@ -181,7 +200,7 @@ See the [**Contributing Guide**](https://github.com/wellwelwel/poku/blob/main/CO
 
 ## Security Policy
 
-[![GitHub Workflow Status (with event)][ql-image]][ql-url]
+[![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)](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).
 
@@ -191,7 +210,7 @@ Please check the [**SECURITY.md**](https://github.com/wellwelwel/poku/blob/main/
 
 ### Performance
 
-**Poku** is [continuously tested](https://github.com/wellwelwel/poku/blob/main/.github/workflows/ci_benchmark.yml) to ensure the following expectations:
+**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)
 - **~3x** faster than [**Vitest**](https://github.com/vitest-dev/vitest) (v1.6.0)
@@ -215,8 +234,11 @@ Please check the [**SECURITY.md**](https://github.com/wellwelwel/poku/blob/main/
 
 ### Limitations
 
-- Although it has no external dependencies, **Poku** is not _all-in-one_, so it doesn't have features such as _mocks_, _spies_, _coverage reports_, etc., where you can use your favorite packages or native solutions.
-- **Poku** community is gradually building up.
+- Although it has no external dependencies, **Poku** is not _all-in-one_, so it doesn't have integrated features such as _mocks_, _spies_, _coverage reports_, etc., where you can use your favorite packages or native solutions.
+  - See a [mock example](https://poku.io/docs/category/mock).
+- **Poku** doesn't render components (such as **Angular**, **React**, etc.).
+  - See an [_end-to-end_ test example](https://poku.io/docs/examples/browser/react).
+- Our community is gradually building up.
 
 ---
 
@@ -235,18 +257,3 @@ Please check the [**SECURITY.md**](https://github.com/wellwelwel/poku/blob/main/
 [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
-[typescript-url]: https://github.com/microsoft/TypeScript
-[ci-linux-url]: https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-linux.yml?query=branch%3Amain
-[ci-linux-image]: https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_coverage-linux.yml?event=push&label=&branch=main&logo=ubuntu&logoColor=white
-[ci-osx-url]: https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-osx.yml?query=branch%3Amain
-[ci-osx-image]: https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_coverage-osx.yml?event=push&label=&branch=main&logo=apple&logoColor=white
-[ci-windows-url]: https://github.com/wellwelwel/poku/actions/workflows/ci_coverage-windows.yml?query=branch%3Amain
-[ci-windows-image]: https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_coverage-windows.yml?event=push&label=&branch=main&logo=windows&logoColor=white
-[ql-url]: https://github.com/wellwelwel/poku/actions/workflows/ci_codeql.yml?query=branch%3Amain
-[ql-image]: https://img.shields.io/github/actions/workflow/status/wellwelwel/poku/ci_codeql.yml?event=push&label=&branch=main&logo=github&logoColor=white
-[coverage-image]: https://img.shields.io/codecov/c/github/wellwelwel/poku
-[coverage-url]: https://app.codecov.io/github/wellwelwel/poku
-[downloads-image]: https://img.shields.io/npm/dt/poku.svg?logo=npm&logoColor=white&color=1e90ff
-[downloads-url]: https://www.npmjs.com/package/poku
-[license-url]: https://github.com/wellwelwel/poku/blob/main/LICENSE
-[license-image]: https://img.shields.io/npm/l/poku?maxAge=2592000&color=9c88ff

package/lib/configs/poku.d.ts

@@ -1,4 +1,5 @@
 export declare const results: {
     success: number;
     fail: number;
+    skipped: number;
 };

package/lib/configs/poku.js

@@ -4,4 +4,5 @@ exports.results = void 0;
 exports.results = {
     success: 0,
     fail: 0,
+    skipped: 0,
 };

package/lib/modules/essentials/assert.d.ts

@@ -24,7 +24,7 @@ export declare const assert: ((value: unknown, message?: ProcessAssertionOptions
     notDeepStrictEqual: (actual: unknown, expected: unknown, message?: ProcessAssertionOptions["message"]) => void;
     match: (value: string, regExp: RegExp, message?: ProcessAssertionOptions["message"]) => void;
     ifError: (value: unknown, message?: ProcessAssertionOptions["message"]) => void;
-    fail: (message?: ProcessAssertionOptions["message"]) => void;
+    fail: (message?: ProcessAssertionOptions["message"]) => never;
     rejects: typeof rejects;
 };
 export {};

package/lib/modules/essentials/assert.js

@@ -94,6 +94,7 @@ const fail = (message) => {
         defaultMessage: 'Test failed intentionally',
         hideDiff: true,
     });
+    process.exit(1);
 };
 function doesNotThrow(block, errorOrMessage, message) {
     (0, assert_js_1.processAssert)(() => {

package/lib/modules/helpers/assert-promise.d.ts

@@ -24,7 +24,7 @@ export declare const assertPromise: ((value: unknown, message?: ProcessAssertion
     notDeepStrictEqual: (actual: unknown, expected: unknown, message?: ProcessAssertionOptions["message"]) => Promise<void>;
     match: (value: string, regExp: RegExp, message?: ProcessAssertionOptions["message"]) => Promise<void>;
     ifError: (value: unknown, message?: ProcessAssertionOptions["message"]) => Promise<void>;
-    fail: (message?: ProcessAssertionOptions["message"]) => Promise<void>;
+    fail: (message?: ProcessAssertionOptions["message"]) => Promise<never>;
     rejects: typeof rejects;
 };
 export {};

package/lib/modules/helpers/assert-promise.js

@@ -100,6 +100,7 @@ const fail = (message) => __awaiter(void 0, void 0, void 0, function* () {
         defaultMessage: 'Test failed intentionally',
         hideDiff: true,
     });
+    process.exit(1);
 });
 function doesNotThrow(block, errorOrMessage, message) {
     return __awaiter(this, void 0, void 0, function* () {

package/lib/modules/helpers/exit.js

@@ -20,7 +20,7 @@ const exit = (code, quiet) => {
                 write_js_1.Write.log(`    ${(0, format_js_1.format)('Duration ›').dim()} ${(0, format_js_1.format)(`${files_js_1.finalResults.time}ms`).bold().dim()} ${(0, format_js_1.format)(`(±${(0, time_js_1.parseTimeToSecs)(files_js_1.finalResults.time)} seconds)`).dim()}`);
                 write_js_1.Write.log(`  ${(0, format_js_1.format)(`Test Files › ${(0, format_js_1.format)(String(files_js_1.fileResults.success.size + files_js_1.fileResults.fail.size)).bold()}`).dim()}`);
                 write_js_1.Write.hr();
-                write_js_1.Write.log(`${(0, format_js_1.format)(` PASS › ${poku_js_1.results.success} `).bg('green')} ${(0, format_js_1.format)(` FAIL › ${poku_js_1.results.fail} `).bg(poku_js_1.results.fail === 0 ? 'grey' : 'red')}`);
+                write_js_1.Write.log(`${(0, format_js_1.format)(` PASS › ${poku_js_1.results.success - poku_js_1.results.skipped} `).bg('green')} ${(0, format_js_1.format)(` FAIL › ${poku_js_1.results.fail} `).bg(poku_js_1.results.fail === 0 ? 'grey' : 'red')} ${poku_js_1.results.skipped > 0 ? (0, format_js_1.format)(` SKIPPED › ${poku_js_1.results.skipped} `).bg(poku_js_1.results.skipped === 0 ? 'grey' : 'blue') : ''}`);
                 write_js_1.Write.hr();
             }
             write_js_1.Write.log(`${(0, format_js_1.format)('Exited with code').dim()} ${(0, format_js_1.format)(String(code)).bold()[code === 0 ? 'success' : 'fail']()}\n`);

package/lib/modules/helpers/skip.d.ts

@@ -0,0 +1 @@
+export declare const skip: (message?: string) => never;

package/lib/modules/helpers/skip.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.skip = void 0;
+const node_process_1 = require("process");
+const write_js_1 = require("../../services/write.js");
+const format_js_1 = require("../../services/format.js");
+const skip = (message) => {
+    const isPoku = typeof (node_process_1.env === null || node_process_1.env === void 0 ? void 0 : node_process_1.env.FILE) === 'string' && (node_process_1.env === null || node_process_1.env === void 0 ? void 0 : node_process_1.env.FILE.length) > 0;
+    const FILE = node_process_1.env.FILE;
+    if (message) {
+        write_js_1.Write.log((0, format_js_1.format)(isPoku
+            ? `ℹ ${message} ${(0, format_js_1.format)('›').dim()} ${(0, format_js_1.format)(`${FILE}`).italic().gray().dim()}`
+            : `ℹ ${message}`)
+            .info()
+            .bold());
+    }
+    (0, node_process_1.exit)(0);
+};
+exports.skip = skip;

package/lib/modules/helpers/wait-for.js

@@ -52,7 +52,6 @@ const waitForExpectedResult = (callback, expectedResult, options) => __awaiter(v
     /* c8 ignore stop */
     yield (0, exports.sleep)(delay);
     const startTime = Date.now();
-    // eslint-disable-next-line no-constant-condition
     while (true) {
         const result = yield callback();
         if (typeof expectedResult === 'function') {

package/lib/modules/index.d.ts

@@ -3,6 +3,7 @@ export { assert } from './essentials/assert.js';
 export { test } from './helpers/test.js';
 export { describe } from './helpers/describe.js';
 export { it } from './helpers/it.js';
+export { skip } from './helpers/skip.js';
 export { beforeEach, afterEach } from './helpers/each.js';
 export { docker } from './helpers/container.js';
 export { startScript, startService } from './helpers/create-service.js';

package/lib/modules/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.assertPromise = exports.listFiles = exports.log = exports.exit = exports.getPIDs = exports.kill = exports.sleep = exports.waitForPort = exports.waitForExpectedResult = exports.startService = exports.startScript = exports.docker = exports.afterEach = exports.beforeEach = exports.it = exports.describe = exports.test = exports.assert = exports.poku = void 0;
+exports.assertPromise = exports.listFiles = exports.log = exports.exit = exports.getPIDs = exports.kill = exports.sleep = exports.waitForPort = exports.waitForExpectedResult = exports.startService = exports.startScript = exports.docker = exports.afterEach = exports.beforeEach = exports.skip = exports.it = exports.describe = exports.test = exports.assert = exports.poku = void 0;
 var poku_js_1 = require("./essentials/poku.js");
 Object.defineProperty(exports, "poku", { enumerable: true, get: function () { return poku_js_1.poku; } });
 var assert_js_1 = require("./essentials/assert.js");
@@ -11,6 +11,8 @@ var describe_js_1 = require("./helpers/describe.js");
 Object.defineProperty(exports, "describe", { enumerable: true, get: function () { return describe_js_1.describe; } });
 var it_js_1 = require("./helpers/it.js");
 Object.defineProperty(exports, "it", { enumerable: true, get: function () { return it_js_1.it; } });
+var skip_js_1 = require("./helpers/skip.js");
+Object.defineProperty(exports, "skip", { enumerable: true, get: function () { return skip_js_1.skip; } });
 var each_js_1 = require("./helpers/each.js");
 Object.defineProperty(exports, "beforeEach", { enumerable: true, get: function () { return each_js_1.beforeEach; } });
 Object.defineProperty(exports, "afterEach", { enumerable: true, get: function () { return each_js_1.afterEach; } });

package/lib/parsers/output.js

@@ -1,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parserOutput = exports.isDebug = exports.isQuiet = void 0;
+const poku_js_1 = require("../configs/poku.js");
 const regex = {
     newLine: /\n/,
     ansi: /u001b\[0m|\n/i,
+    skipped: /^"\\u001b\[94m\\u001b\[1mℹ/i,
 };
 const isQuiet = (configs) => typeof (configs === null || configs === void 0 ? void 0 : configs.quiet) === 'boolean' && Boolean(configs === null || configs === void 0 ? void 0 : configs.quiet);
 exports.isQuiet = isQuiet;
@@ -13,6 +15,10 @@ exports.isDebug = isDebug;
 /* c8 ignore next */ // ?
 const parserOutput = (options) => {
     const { output, result, configs } = options;
+    const normalizedOutput = JSON.stringify(output);
+    if (regex.skipped.test(normalizedOutput)) {
+        ++poku_js_1.results.skipped;
+    }
     const debug = (0, exports.isDebug)(configs);
     const pad = (configs === null || configs === void 0 ? void 0 : configs.parallel) ? '  ' : '    ';
     const splittedOutput = output.split(regex.newLine);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poku",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "🐷 Poku makes testing easy for Node.js, Bun, Deno, and you at the same time.",
   "main": "./lib/modules/index.js",
   "license": "MIT",
@@ -26,7 +26,7 @@
     "node": ">=6.0.0",
     "bun": ">=1.0.0",
     "deno": ">=1.30.0",
-    "typescript": ">=5.0.2"
+    "typescript": ">=4.7.2"
   },
   "scripts": {
     "test": "npm run test:parallel && npm run test:sequential",
@@ -63,7 +63,7 @@
     "c8": "^10.1.2",
     "packages-update": "^2.0.0",
     "shx": "^0.3.4",
-    "tsx": "4.16.0",
+    "tsx": "4.16.2",
     "typescript": "^5.5.3"
   },
   "keywords": [