-
+
# 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]
-[![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)
+[![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) โข ๐งช [Examples](https://poku.io/docs/category/examples) โข ๐ฌ [Compare the Most Popular Test Runners](https://poku.io/docs/comparing)
+๐ท [Website](https://poku.io/) โข ๐ [Documentation](https://poku.io/docs/category/documentation) โข ๐งช [Examples](https://poku.io/docs/category/examples) โข ๐ง๐ปโ๐ [Quick Tutorials](https://poku.io/docs/tutorials)
@@ -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/tutorials) section.
+
+---
+
+### Common Issues
+
+- [Avoiding conflicts in environments with multiple platforms installed](https://poku.io/docs/roadmaps/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.
---
@@ -236,17 +258,3 @@ Please check the [**SECURITY.md**](https://github.com/wellwelwel/poku/blob/main/
[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
diff --git a/benchmark/README.md b/benchmark/README.md
index b44a2420..b9426e77 100644
--- a/benchmark/README.md
+++ b/benchmark/README.md
@@ -16,7 +16,7 @@ The testers to be compared are chosen based on the three most downloaded test ru
---
-**Poku** is continuously tested ([**CI**](https://github.com/wellwelwel/poku/blob/main/.github/workflows/ci_benchmark.yml)) to ensure the following expectations:
+**Poku** is continuously tested ([**CI**](https://github.com/wellwelwel/poku/blob/main/.github/workflows/ci_benchmark.yml)) to ensure the following expectations for basic usage:
- [x] **~4x** faster than [**Jest**](https://github.com/jestjs/jest) (v29.7.0)
- [x] **~3x** faster than [**Vitest**](https://github.com/vitest-dev/vitest) (v1.6.0)
@@ -26,7 +26,7 @@ The testers to be compared are chosen based on the three most downloaded test ru
## Running
-To run the benchmark tests, follow these steps:
+To run the benchmark tests, follow these steps in the `./poku` directory:
```sh
npm ci
diff --git a/website/docs/documentation/poku/include-files.mdx b/website/docs/documentation/poku/include-files.mdx
index 1500c000..a803d16d 100644
--- a/website/docs/documentation/poku/include-files.mdx
+++ b/website/docs/documentation/poku/include-files.mdx
@@ -10,29 +10,49 @@ sidebar_position: 1
## CLI
-By setting the directories as the **last argument**:
-
-> _Since **1.3.0**_
+### Common usage
```bash
-npx poku targetPath
+# Same as ./
+npx poku
```
+- Run all tests sequentially.
+
```bash
-npx poku targetPathA,targetPathB
+# Same as ./
+npx poku --parallel
```
+- Run all tests in parallel.
+
+:::tip
+You can pass both directories and files.
+:::
+
+:::note
+It's not possible to run tests in the `.git` and `node_modules` directories.
+:::
+
+
+
+### By setting the directories as the last argument
+
+> _Since **1.3.0**_
+
```bash
-# Same as ./
-npx poku
+npx poku targetPath
```
```bash
-# Same as ./
-npx poku --parallel
+npx poku targetPathA,targetPathB
```
-By using `--include` option, you can use it in any order:
+
+
+### By using `--include` flag
+
+Using the `--include` flag, you can use it in any order:
```bash
npx poku --include='targetPath'
@@ -46,26 +66,18 @@ npx poku --include='targetPathA,targetPathB'
npx poku --include='./'
```
+
+
## API (_in-code_)
```ts
-poku('targetPath');
+await poku('targetPath');
```
```ts
-poku(['targetPathA', 'targetPathB']);
+await poku(['targetPathA', 'targetPathB']);
```
```ts
-poku('./');
+await poku('./');
```
-
-
-
-:::tip
-The `targetPath` can be either a directory or a file.
-:::
-
-:::info
-It's not possible to run tests in the `.git` and `node_modules` directories.
-:::
diff --git a/website/docs/examples/cjs-esm.mdx b/website/docs/examples/cjs-esm.mdx
index 77f2d0cb..4ee1b39c 100644
--- a/website/docs/examples/cjs-esm.mdx
+++ b/website/docs/examples/cjs-esm.mdx
@@ -1,7 +1,3 @@
----
-sidebar_position: 4
----
-
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
diff --git a/website/docs/examples/promises.mdx b/website/docs/examples/promises.mdx
new file mode 100644
index 00000000..bce80d16
--- /dev/null
+++ b/website/docs/examples/promises.mdx
@@ -0,0 +1,135 @@
+---
+title: Promises
+tags: [examples, promise, beforeAll, afterAll, tutorial, roadmap]
+sidebar_position: 0
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import MidLevel from '@site/static/img/mid-level.svg';
+
+# Promises
+
+The use of native **JavaScript** syntax in tests is one of the major differences between Poku and other test runners, which is what makes it possible to use it on multiple platforms.
+
+Here are some examples of sequential and concurrent tests in the same file plus how to perform an action after all the tests have been completed:
+
+### Running async tests in the same file in parallel
+
+```js
+import { test, assert, sleep } from 'poku';
+
+test(async () => {
+ const actual = 1;
+ const expected = 1;
+
+ await sleep(2000);
+
+ assert.strictEqual(actual, expected);
+});
+
+test(async () => {
+ const actual = 2;
+ const expected = 2;
+
+ await sleep(1000);
+
+ assert.strictEqual(actual, expected);
+});
+```
+
+
+
+### Running async tests in the same file sequentially (await top-level)
+
+```js
+import { test, assert, sleep } from 'poku';
+
+await test(async () => {
+ const actual = 1;
+ const expected = 1;
+
+ await sleep(2000);
+
+ assert.strictEqual(actual, expected);
+});
+
+await test(async () => {
+ const actual = 2;
+ const expected = 2;
+
+ await sleep(1000);
+
+ assert.strictEqual(actual, expected);
+});
+```
+
+
+
+### Running async tests in the same file sequentially
+
+```js
+import { test, it, assert, sleep } from 'poku';
+
+test(async () => {
+ await it(async () => {
+ const actual = 1;
+ const expected = 1;
+
+ await sleep(2000);
+
+ assert.strictEqual(actual, expected);
+ });
+
+ await it(async () => {
+ const actual = 2;
+ const expected = 2;
+
+ await sleep(1000);
+
+ assert.strictEqual(actual, expected);
+ });
+});
+```
+
+
+
+## Waiting for all the tests to run a post step
+
+```js
+import { test, assert, sleep } from 'poku';
+
+console.log('Printing it before all tests ๐๐ปโโ๏ธ');
+
+await Promise.all([
+ test(async () => {
+ const actual = 1;
+ const expected = 1;
+
+ await sleep(2000);
+
+ assert.strictEqual(actual, expected);
+ }),
+
+ test(async () => {
+ const actual = 2;
+ const expected = 2;
+
+ await sleep(1000);
+
+ assert.strictEqual(actual, expected);
+ }),
+]);
+
+console.log('Printing it after all tests ๐ด');
+```
+
+:::tip
+The same goes for `describe` and `it`.
+:::
+
+
+
+:::note
+If you find any typos, feel free to open a **Pull Request** correcting them.
+:::
diff --git a/website/docs/index.mdx b/website/docs/index.mdx
index 9680c586..c6b44455 100644
--- a/website/docs/index.mdx
+++ b/website/docs/index.mdx
@@ -55,52 +55,17 @@ Enjoying **Poku**? [Consider giving him a star](https://github.com/wellwelwel/po
-## Why does Poku exist?
-
-**Poku** can show you how simple testing can be ๐ฑ
-
-
-
-
- Auto detect **ESM**, **CJS**, and **Typescript** files
-
-
-
- Run the same test suite for **Node.js**, **Bun**, and **Deno**
-
-
-
- Instantly re-run related tests in `watch` mode
-
-
-
- Run **CJS** _(**CommonJS**)_ files directly with **Deno**
-
-
-
-
- Write tests with the same [Native **JavaScript**
- Syntax](/docs/philosophy#javascript-essence-for-tests-)
-
-
-
-
- **Poku** brings human-friendly testing, assertion, and outputs
-
-
+### Recommended Roadmap ๐ง๐ปโ๐
-
+๐ฌ Start by seeing [how to use assert](/docs/tutorials/beginner).
+๐งช Then learn how to use [poku](/docs/documentation/poku/include-files) to run all your test files at once.
-### Recommended Roadmap ๐ง๐ปโ๐
+๐ง๐ปโ๐ฌ Need to test an API? Check the [startService](/docs/documentation/helpers/startService) and [startScript](/docs/documentation/helpers/startScript).
+๐ณ Need to mount and unmount containers before/after tests? Check the [dockerfile](/docs/documentation/helpers/containers#dockerfile) and [compose](/docs/documentation/helpers/containers#compose).
+๐ Also, need to check tests inside a container? Check the [dockerfile](/docs/documentation/helpers/containers#dockerfile) and [compose](/docs/documentation/helpers/containers#compose) too.
+๐ง๐ป So, just if you want to, go deeper into learning about **Poku**.
-> ๐ฌ Start by seeing how to use [assert](/docs/documentation/assert).
-> ๐งช Then learn how to use [poku](/docs/category/-poku) to run all your test files at once.
-> ๐ง๐ปโ๐ฌ Need to test an API? Check the [startService](/docs/documentation/helpers/startService) and [startScript](/docs/documentation/helpers/startScript).
-> ๐ณ Need to mount and unmount containers before/after tests? Check the [dockerfile](/docs/documentation/helpers/containers#dockerfile) and [compose](/docs/documentation/helpers/containers#compose).
-> ๐ Also, need to check tests inside a container? Check the [dockerfile](/docs/documentation/helpers/containers#dockerfile) and [compose](/docs/documentation/helpers/containers#compose) too.
-> ๐ง๐ป So, just if you want to, go deeper into learning about **Poku**.
->
-> ๐ฉต Take Your Time
+๐ฉต Take Your Time
- [**Compare Poku with the Most Popular Test Runners ๐งช**](/docs/comparing)
@@ -200,18 +165,22 @@ deno run npm:poku
### Helpers
- [**test**](/docs/documentation/helpers/test), [**describe**](/docs/documentation/helpers/describe) and [**it**](/docs/documentation/helpers/it) _(organize, group, and isolate tests)_
-- [**watch**](/docs/documentation/poku/options/watch) _(watch for changes and re-run related test files)_
- [**beforeEach**](/docs/category/-before-and-after-each) and [**afterEach**](/docs/category/-before-and-after-each) _(hooks for test setup and teardown)_
- [**docker**](/docs/documentation/helpers/containers) _(build, start, compose, stop, remove, and test containers)_
- [**startScript**](/docs/documentation/helpers/startScript) _(run **package.json** scripts in background)_
- [**startService**](/docs/documentation/helpers/startService) _(run files in background)_
- [**kill**](/docs/documentation/helpers/processes/kill) _(terminate ports, port ranges, and PIDs)_
- [**waitForPort**](/docs/documentation/helpers/processes/wait-for-port) _(wait for specified ports to become active)_
-- [**waitForExpectedResult**](/docs/documentation/helpers/processes/wait-for-expected-result)_(retry until an expected result or times out)_
+- [**waitForExpectedResult**](/docs/documentation/helpers/processes/wait-for-expected-result) _(retry until an expected result or times out)_
- [**getPIDs**](/docs/documentation/helpers/processes/get-pids) _(debug processes IDs using ports and port ranges)_
-- _and much more_ ๐๐ป
-[**See the complete documentation**](/docs/category/documentation).
+### Common Options
+
+- [**watch**](/docs/documentation/poku/options/watch) _(watch for changes and re-run related test files)_
+- [**parallel**](/docs/documentation/poku/options/parallel) _(run tests in parallel)_
+- [**debug**](/docs/documentation/poku/options/debug) _(shows all logs)_
+
+> _And much more_ ๐๐ป
@@ -221,6 +190,13 @@ deno run npm:poku
+## Common Issues
+
+- [Avoiding conflicts in environments with multiple platforms installed](/docs/tutorials/cross-platform#recommendations).
+- [Properly running asynchronous tests on the same file](/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) ๐
diff --git a/website/docs/philosophy.mdx b/website/docs/philosophy.mdx
index e0310b2a..8f5d5618 100644
--- a/website/docs/philosophy.mdx
+++ b/website/docs/philosophy.mdx
@@ -73,32 +73,65 @@ describe('My Test', async () => {
**Poku** doesn't use a global state, allowing you to use it how and where you want:
-```sh
-# Node.js + Poku
+
+
+
+```bash
npx poku test.js
+```
-# Node.js
-node test.js
+
+
-# Bun + Poku
+```bash
bunx poku test.js
+```
-# Bun
-bun test.js
+
+
-# Deno + Poku
+```bash
deno run npm:poku test.js
+```
+
+
+
+
+```bash
+node test.js
+```
+
+
+
+
+```bash
+bun test.js
+```
-# Deno
+
+
+
+```bash
deno run test.js
+```
-# Yarn + Poku
+
+
+
+```bash
yarn poku test.js
+```
+
+
+
-# pnpm + Poku
+```bash
pnpm poku test.js
```
+
+
+
- Same idea for **TypeScript**.
:::
diff --git a/website/docs/roadmaps/mid-level.mdx b/website/docs/roadmaps/mid-level.mdx
deleted file mode 100644
index c5f24aa0..00000000
--- a/website/docs/roadmaps/mid-level.mdx
+++ /dev/null
@@ -1,328 +0,0 @@
----
-title: Good Practices
-description: Organizing tests for different needs, requirements and approaches.
-tags: [assert, assertion, test, describe, it, tutorial, mid level, roadmap]
----
-
-import MidLevel from '@site/static/img/mid-level.svg';
-
-
-
-
-
-
-
-
-## Organizing the tests
-
-Let's create some dummy tests:
-
-### Declaring same variable names
-
-```js
-import { test, assert } from 'poku';
-
-test(() => {
- const actual = 1;
- const expected = 1;
-
- assert.strictEqual(actual, expected, 'Expects for the same number (1)');
-});
-
-test(() => {
- const actual = 2;
- const expected = 2;
-
- assert.strictEqual(actual, expected, 'Expects for the same number (2)');
-});
-```
-
-
-
-### Categorizing our tests
-
-```js
-import { test, assert } from 'poku';
-
-test('Testing numbers', () => {
- const actual = 1;
- const expected = 1;
-
- assert.strictEqual(actual, expected, 'Expects for the same number');
-});
-
-test('Testing strings' () => {
- const actual = 'poku';
- const expected = 'poku';
-
- assert.strictEqual(actual, expected, 'Expects for the same string');
-});
-```
-
-
-
-### Declaring same variable names and Categorizing our tests
-
-```js
-import { describe, it, assert } from 'poku';
-
-describe('Testing numbers', () => {
- it('Should be the same number', () => {
- const actual = 1;
- const expected = 1;
-
- assert.strictEqual(actual, expected, ' Number 1');
- });
-
- it('Should be the same number', () => {
- const actual = 1;
- const expected = 1;
-
- assert.strictEqual(actual, expected, 'Number 2');
- });
-});
-
-describe('Testing strings', () => {
- it('Should be the same string', () => {
- const actual = 'poku';
- const expected = 'poku';
-
- assert.strictEqual(actual, expected, ' String "poku"');
- });
-
- it('Should be the same string', () => {
- const actual = 'POKU';
- const expected = 'POKU';
-
- assert.strictEqual(actual, expected, 'String "POKU"');
- });
-});
-```
-
-:::tip
-Note that all messages are optional in **Poku** (from `test`, `describe`, `it` and `assert`).
-For example:
-
-```js
-import { describe, it, assert } from 'poku';
-
-describe(() => {
- it(() => {
- const actual = 1;
- const expected = 1;
-
- assert.strictEqual(actual, expected);
- });
-
- it(() => {
- const actual = 1;
- const expected = 1;
-
- assert.strictEqual(actual, expected);
- });
-});
-
-describe(() => {
- it(() => {
- const actual = 'poku';
- const expected = 'poku';
-
- assert.strictEqual(actual, expected);
- });
-
- it(() => {
- const actual = 'POKU';
- const expected = 'POKU';
-
- assert.strictEqual(actual, expected);
- });
-});
-```
-
-:::
-
-
-
-## Running "Promise Tests" in parallel in the same file
-
-```js
-import { test, assert, sleep } from 'poku';
-
-test(async () => {
- const actual = 1;
- const expected = 1;
-
- await sleep(2000);
-
- assert.strictEqual(actual, expected);
-});
-
-test(async () => {
- const actual = 2;
- const expected = 2;
-
- await sleep(1000);
-
- assert.strictEqual(actual, expected);
-});
-```
-
-
-
-## Running "Promise Tests" one-by-one in the same file (await top-level)
-
-```js
-import { test, assert, sleep } from 'poku';
-
-await test(async () => {
- const actual = 1;
- const expected = 1;
-
- await sleep(2000);
-
- assert.strictEqual(actual, expected);
-});
-
-await test(async () => {
- const actual = 2;
- const expected = 2;
-
- await sleep(1000);
-
- assert.strictEqual(actual, expected);
-});
-```
-
-
-
-## Running "Promise Tests" one-by-one in the same file (no await top-level)
-
-```js
-import { test, assert, sleep } from 'poku';
-
-test(async () => {
- await test(async () => {
- const actual = 1;
- const expected = 1;
-
- await sleep(2000);
-
- assert.strictEqual(actual, expected);
- });
-
- await test(async () => {
- const actual = 2;
- const expected = 2;
-
- await sleep(1000);
-
- assert.strictEqual(actual, expected);
- });
-});
-```
-
-:::tip
-You are free to choose to use `describe` + `it`, or `test` + `describe`, or `test` + `it` and so on, but note that if you use messages, they will only be properly formatted:
-
-- `test`
-- `test` + `assert`
-- `describe`
-- `describe` + `assert`
-- `it`
-- `it` + `assert`
-- `describe` + `it`
-- `describe` + `it` + `assert`
-
-:::
-
-:::note
-With the exception of the output formatting in the terminal, it doesn't matter how deep you go, everyone will always be executed correctly.
-:::
-
-
-
-## Waiting for all tests to running a "pos step"
-
-```js
-import { test, assert, sleep } from 'poku';
-
-await Promise.all([
- test(async () => {
- const actual = 1;
- const expected = 1;
-
- await sleep(2000);
-
- assert.strictEqual(actual, expected);
- }),
-
- test(async () => {
- const actual = 2;
- const expected = 2;
-
- await sleep(1000);
-
- assert.strictEqual(actual, expected);
- }),
-]);
-
-console.log("I've been waiting for everything ๐ด");
-```
-
-:::tip
-The same goes for `describe` and `it`.
-:::
-
-
-
-## Running tests in different ways
-
-```sh
-npx poku
-```
-
-```sh
-npx poku --parallel
-```
-
-```sh
-npx poku ./__test__
-```
-
-```sh
-npx poku --parallel ./__test__
-```
-
-```sh
-npx poku --include=./__test__ --parallel
-```
-
-```sh
-bun poku --parallel --debug --fail-fast --concurrency=3
-```
-
-```sh
-npx poku --platform=bun --parallel --debug
-```
-
-```sh
-bun poku --platform=bun --parallel --debug --watch
-```
-
-Etc.
-
-See all available options [here](/docs/category/-poku).
-
-
-
-:::note
-If you find any typos, feel free to open a **Pull Request** correcting them.
-:::
diff --git a/website/docs/roadmaps/beginner.mdx b/website/docs/tutorials/beginner.mdx
similarity index 99%
rename from website/docs/roadmaps/beginner.mdx
rename to website/docs/tutorials/beginner.mdx
index 5b6f10b1..3d696abc 100644
--- a/website/docs/roadmaps/beginner.mdx
+++ b/website/docs/tutorials/beginner.mdx
@@ -2,6 +2,7 @@
title: Beginner
description: From a basic assertion test to its execution.
tags: [assert, assertion, tutorial, beginner, roadmap]
+sidebar_position: 0
---
import Junior from '@site/static/img/junior.svg';
diff --git a/website/docs/tutorials/cross-platform.mdx b/website/docs/tutorials/cross-platform.mdx
new file mode 100644
index 00000000..afaa0270
--- /dev/null
+++ b/website/docs/tutorials/cross-platform.mdx
@@ -0,0 +1,198 @@
+---
+title: Testing Across Platforms
+description: Running the same test suite on different platforms.
+tags: [cross-platform, Node.js, Bun, Deno, tutorial, roadmap]
+sidebar_position: 3
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import Maintainer from '@site/static/img/maintainer.svg';
+
+
+
+
+
+
+
+
+## Running tests in specific platforms
+
+First, let's understand what each definition does:
+
+```sh
+npx poku
+```
+
+- It tries to identify the platform or run it in **Node.js** by default.
+
+```sh
+npx poku --platform=bun
+```
+
+- It calls **Poku** through **Node.js**, but runs all the tests using **Bun**.
+
+```sh
+npx poku --platform=deno
+```
+
+- It calls **Poku** through **Node.js**, but runs all the tests using **Deno**.
+
+:::note
+It's important to note that the **Poku** runtime is different from the test runtime (`node`, `npx tsx`, `bun`, or `deno`).
+:::
+
+
+
+- See the `platform` section [here](/docs/documentation/poku/options/platform).
+- See all available flags and options for `poku` command [here](/docs/category/-poku).
+
+
+
+### Recommendations
+
+To avoid conflicts in environments with multiple platforms installed (**Node.js** + **Bun**, **Deno** + **Bun**. etc.), see the following examples:
+
+```sh
+npx poku --platform=node
+```
+
+- It runs **Poku** through **Node.js** and ensures that all tests are run with **Node.js** (or **tsx** for **TypeScript** tests).
+
+```sh
+bun poku --platform=bun
+```
+
+- It runs **Poku** through **Bun** and ensures that all tests are run with **Bun**.
+
+```sh
+deno run npm:poku --platform=deno
+```
+
+- It runs **Poku** through **Deno** and ensures that all tests are run with **Deno**.
+
+:::tip
+For **TypeScript** users, there's no need to install **tsx** for **Bun** and **Deno**, as they both run **TypeScript** natively.
+:::
+
+
+
+### Running CommonJS with Deno
+
+> See all options for **Deno** [here](/docs/documentation/poku/options/deno).
+
+#### All files as CommonJS
+
+```sh
+deno run npm:poku --platform=deno --deno-cjs
+```
+
+#### A specific extension as CommonJS
+
+```sh
+deno run npm:poku --platform=deno --deno-cjs='.cjs'
+```
+
+#### Multiple extensions as CommonJS
+
+```sh
+deno run npm:poku --platform=deno --deno-cjs='.cjs,.js'
+```
+
+
+
+## Using Poku API _(advanced usage)_
+
+In **Poku**'s description, you can read _"Poku makes testing easy for Node.js, Bun, Deno, and you at the same time"_, and it's true:
+
+> This is more to demonstrate a point, not a recommendation ๐๐ปโโ๏ธ
+
+_./test/run.test.ts_:
+
+```ts
+import { describe, it, poku, exit } from 'poku';
+
+const parallel = true;
+const noExit = true;
+
+const codes: (0 | 1)[] = [];
+
+await describe('Running Tests on Different Platforms at the Same Time', async () => {
+ await Promise.all([
+ it('Test suite should pass on Node.js', async () => {
+ const exitCode = await poku(['./test/unit'], {
+ platform: 'node',
+ parallel,
+ noExit,
+ });
+
+ codes.push(exitCode);
+ }),
+
+ it('Test suite should pass on Bun', async () => {
+ const exitCode = await poku(['./test/unit'], {
+ platform: 'bun',
+ parallel,
+ noExit,
+ });
+
+ codes.push(exitCode);
+ }),
+
+ it('Test suite should pass on Deno', async () => {
+ const exitCode = await poku(['./test/unit'], {
+ platform: 'deno',
+ parallel,
+ noExit,
+ deno: {
+ cjs: ['.cjs'],
+ },
+ });
+
+ codes.push(exitCode);
+ }),
+ ]);
+});
+
+const code = codes.every((code) => code === 0) ? 0 : 1;
+
+exit(code);
+```
+
+Then, choose a platform:
+
+- **Node.js** (using **TypeScript**)
+
+```sh
+npx tsx test/run.test.ts
+```
+
+- **Bun**
+
+```sh
+bun test/run.test.ts
+```
+
+- **Deno**
+
+```sh
+deno run test/run.test.ts
+```
+
+:::tip
+It's usually beneficial to have an exclusive _CI_ for each platform, especially to ensure better control in error cases.
+:::
+
+
+
+:::note
+If you find any typos, feel free to open a **Pull Request** correcting them.
+:::
diff --git a/website/docs/tutorials/good-practices.mdx b/website/docs/tutorials/good-practices.mdx
new file mode 100644
index 00000000..41a04014
--- /dev/null
+++ b/website/docs/tutorials/good-practices.mdx
@@ -0,0 +1,167 @@
+---
+title: Good Practices
+description: Organizing tests for different needs, requirements and approaches.
+tags: [assert, assertion, test, describe, it, tutorial, roadmap]
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import MidLevel from '@site/static/img/mid-level.svg';
+
+
+
+
+
+
+
+
+## Organizing Tests
+
+There are various motivations for organizing tests better:
+
+- Different tests usually have their own files.
+- Use isolated scopes to declare the same variables or isolate one test from another in the same file.
+- Grouping multiple tests of the same method.
+
+Let's create two basic methods (**sum** and **sub**) to be tested:
+
+
+
+
+```js
+export const sum = (a, b) => a + b;
+export const sub = (a, b) => a - b;
+```
+
+
+
+
+### By separating tests with different responsibilities
+
+> Create a file to test the `sum` method and another for the `sub` method.
+
+
+
+
+```js
+import { test, assert } from 'poku';
+import { sum } from '../../src/calc.mjs';
+
+test('Testing "sum" method', () => {
+ assert(sum(0, 0), 0, 'should return zero');
+ assert(sum(0, 1), 1, 'should return one');
+ assert(sum(1, 1), 2, 'should return two');
+});
+```
+
+
+
+
+```js
+import { test, assert } from 'poku';
+import { sub } from '../../src/calc.mjs';
+
+test('Testing "sub" method', () => {
+ assert(sub(1, 1), 0, 'should return zero');
+ assert(sub(2, 1), 1, 'should return one');
+ assert(sub(3, 1), 2, 'should return two');
+});
+```
+
+
+
+
+
+
+### By categorizing tests with different responsibilities
+
+> Create a unique file to test both the `sum` and `sub` methods.
+
+
+
+
+```js
+import { test, assert } from 'poku';
+import { sum, sub } from '../../src/calc.mjs';
+
+test('Testing "sum" method', () => {
+ assert(sum(0, 0), 0, 'should return zero');
+ assert(sum(0, 1), 1, 'should return one');
+ assert(sum(1, 1), 2, 'should return two');
+});
+
+test('Testing "sub" method', () => {
+ assert(sub(1, 1), 0, 'should return zero');
+ assert(sub(2, 1), 1, 'should return one');
+ assert(sub(3, 1), 2, 'should return two');
+});
+```
+
+
+
+
+
+
+### By describing tests with different responsibilities
+
+> Create a unique file to test both the `sum` and `sub` methods.
+
+
+
+
+```js
+import { describe, it, assert } from 'poku';
+import { sum, sub } from '../../src/calc.mjs';
+
+describe('Testing calculation methods', () => {
+ it('"sum" method', () => {
+ assert(sum(0, 0), 0, 'should return zero');
+ assert(sum(0, 1), 1, 'should return one');
+ assert(sum(1, 1), 2, 'should return two');
+ });
+
+ it('"sub" method', () => {
+ assert(sub(1, 1), 0, 'should return zero');
+ assert(sub(2, 1), 1, 'should return one');
+ assert(sub(3, 1), 2, 'should return two');
+ });
+});
+```
+
+
+
+
+- When using `describe` + `it` with messages, it's common not to include the message in `assert`.
+
+
+
+:::tip
+You are free to choose to use `describe` + `it`, or `test` + `describe`, or `test` + `it` and so on, but note that if you use messages, they will only be properly formatted for:
+
+- `assert`
+- `test`
+- `test` + `assert`
+- `describe`
+- `describe` + `assert`
+- `it`
+- `it` + `assert`
+- `describe` + `it`
+- `describe` + `it` + `assert`
+- `describe` + `assert` + `it` + `assert`
+
+:::
+
+
+
+:::note
+If you find any typos, feel free to open a **Pull Request** correcting them.
+:::
diff --git a/website/sidebars.ts b/website/sidebars.ts
index f5fbd833..95b01ed5 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -30,7 +30,7 @@ const sidebars: SidebarsConfig = {
link: {
type: 'generated-index',
},
- items: [{ type: 'autogenerated', dirName: 'roadmaps' }],
+ items: [{ type: 'autogenerated', dirName: 'tutorials' }],
},
],
};
diff --git a/website/src/components/Confetti.tsx b/website/src/components/Confetti.tsx
index f7700b86..b88cf9e2 100644
--- a/website/src/components/Confetti.tsx
+++ b/website/src/components/Confetti.tsx
@@ -52,7 +52,12 @@ export const ConfettiButton: React.FC = ({ toCopy }) => {
}}
/>
)}
-