diff --git a/README.md b/README.md index 818a6c46..f18fa8f3 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,20 @@
-Poku's Logo +Poku's Logo # 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 }) => { }} /> )} - diff --git a/website/src/pages/index.tsx b/website/src/pages/index.tsx index 34413e48..e4fd5739 100644 --- a/website/src/pages/index.tsx +++ b/website/src/pages/index.tsx @@ -99,7 +99,7 @@ const Home = () => { .
- + Start Here @@ -137,13 +137,15 @@ const Home = () => { using npx poku.

- + Beginner Assertion Tutorial
- Mid Level + + Mid Level (Intermediary) +
@@ -154,8 +156,8 @@ const Home = () => { approaches with Poku.

- - (Beta) Organizing Tests and Good Practices + + Organizing Tests and Good Practices
@@ -197,8 +199,8 @@ const Home = () => { ESM or TypeScript.

- - (Soon) Cross-Platform Tutorial + + Testing Across Platforms