docs: add examples and use cases (#619)

website/docs/documentation/poku/include-files.mdx

@@ -67,6 +67,30 @@ npx poku targetPathA targetPathB
 
 <hr />
 
+### By extending Glob patterns from shell
+
+You can also extend **Glob patterns** with `npx`, `bun`, `yarn`, etc.
+
+For example, by running all the unit tests of a _monorepo_:
+
+```sh
+npx poku ./packages/**/test/unit
+```
+
+Now, listing all `.js` files instead of the default `.test.|.spec.`:
+
+```sh
+npx poku --filter='.js' ./packages/**/test/unit
+```
+
+Also, by bypassing the filter:
+
+```sh
+npx poku --filter='' ./packages/**/test/unit/*.js
+```
+
+<hr />
+
 ### `--include`
 
 <Stability

website/docs/examples/parameterized-tests.mdx

@@ -0,0 +1,82 @@
+---
+tags: [examples, promise, tutorial, parameterized, parametrized]
+sidebar_position: 0.5
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import MidLevel from '@site/static/img/mid-level.svg';
+
+# Parameterized Tests
+
+Parameterized tests allow you to run the same test logic with different inputs and expected results. This helps to test across various scenarios without writing repetitive tests.
+
+For example:
+
+```ts
+import { assert, test } from 'poku';
+
+const testCases = [
+  {
+    expected: true,
+    input: { name: 'Alice', role: 'admin' },
+    testCase: 'is admin',
+  },
+  {
+    expected: false,
+    input: { name: 'Bob', role: 'user' },
+    testCase: 'is not admin',
+  },
+];
+
+const isAdmin = (user) => user.role === 'admin';
+
+for (const { expected, input, testCase } of testCases) {
+  test(testCase, () => {
+    const actual = isAdmin(input);
+
+    assert.strictEqual(actual, expected);
+  });
+}
+```
+
+## Using promises
+
+Handling asynchronous operations sequentially within parameterized tests using promises:
+
+```ts
+import { assert, test } from 'poku';
+
+const testCases = [
+  {
+    expected: true,
+    input: { name: 'Alice', role: 'admin' },
+    testCase: 'is admin',
+  },
+  {
+    expected: false,
+    input: { name: 'Bob', role: 'user' },
+    testCase: 'is not admin',
+  },
+];
+
+const isAdmin = (user) => Promise.resolve(user.role === 'admin');
+
+for (const { expected, input, testCase } of testCases) {
+  await test(testCase, async () => {
+    const actual = await isAdmin(input);
+
+    assert.strictEqual(actual, expected);
+  });
+}
+```
+
+:::tip
+To run asynchronous operations in parallel, simply remove `await` from `test` or `it`.
+:::
+
+<hr />
+
+:::info
+These examples were based on [this comment](https://github.com/wellwelwel/poku/issues/566#issuecomment-2241496155).
+:::

website/docs/examples/promises.mdx

@@ -12,6 +12,10 @@ import MidLevel from '@site/static/img/mid-level.svg';
 
 The use of [native **JavaScript** syntax in tests](/docs/philosophy#javascript-essence-for-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.
 
+:::tip
+It's not necessary to use `await` for tests that aren't asynchronous.
+:::
+
 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
@@ -132,6 +136,10 @@ For multiple asynchronous `describe` or `test`, you can also use `await` to run
 
 <hr />
 
+:::danger Be careful
+When using asynchronous `beforeEach` or `afterEach`, it's necessary to use `await` even if the `test` or `it` helpers doesn't have any asynchronous events.
+:::
+
 :::note
 If you find any typos, feel free to open a **Pull Request** correcting them.
 :::

website/docs/philosophy.mdx

@@ -39,6 +39,7 @@ describe('My Test', { concurrency: 1 }, () => {
     console.log('Done');
   });
 
+  // Asynchronous tests, but they will be executed sequentially even without the use of `await`
   it(async () => {
     // async test
   });

website/docs/tutorials/good-practices.mdx

@@ -150,14 +150,21 @@ You are free to choose to use `describe` + `it`, or `test` + `describe`, or `tes
 - `assert`
 - `test`
 - `test` + `assert`
-- `describe`
-- `describe` + `assert`
 - `it`
 - `it` + `assert`
+- `describe`
+- `describe` + `assert`
 - `describe` + `it`
 - `describe` + `it` + `assert`
 - `describe` + `assert` + `it` + `assert`
+- `describe` + `test`
+- `describe` + `test` + `assert`
+- `describe` + `assert` + `test` + `assert`
+
+:::
 
+:::danger Be careful
+Avoid coupling `test` and `it` when using hooks such as `beforeEach` (e.g., `test + test`, `it + it`, `test + it`, etc.).
 :::
 
 <hr />