feat(describe): support for Node.js familiar API usage

benchmark/README.md

@@ -4,7 +4,7 @@ The benchmark is performed by comparing a simple success and a failure test, eac
 
 > [!important]
 >
-> **Poku** doesn't intend to be the best, but to offer a balance between high performance, compatibility, lightness and ease of use.
+> **Poku** doesn't intend to be "the best", but to offer a balance between high performance, isolation, compatibility, lightness and ease of use.
 
 ---
 

src/modules/describe.ts

@@ -5,24 +5,55 @@ import { indentation } from '../configs/indentation.js';
 import type { DescribeOptions } from '../@types/describe.js';
 
 /**
- * On **Poku**, `describe` is just a pretty `console.log` to title your test suites in the terminal.
+ * On **Poku**, `describe` also can be used just as a pretty `console.log` to title your test suites in the terminal.
  */
-export const describe = (title: string, options?: DescribeOptions) => {
-  const { background, icon } = options || {};
+export async function describe(
+  title: string,
+  cb: () => Promise<unknown>
+): Promise<void>;
+export function describe(title: string, cb: () => unknown): void;
+export async function describe(cb: () => Promise<unknown>): Promise<void>;
+export function describe(cb: () => unknown): unknown;
+export function describe(title: string, options?: DescribeOptions): void;
+export async function describe(
+  arg1: string | (() => unknown | Promise<unknown>),
+  arg2?: (() => unknown | Promise<unknown>) | DescribeOptions
+): Promise<void> {
+  let title: string | undefined;
+  let cb: (() => unknown | Promise<unknown>) | undefined;
+  let options: DescribeOptions | undefined;
 
-  const message = `${icon || '☰'} ${title}`;
-  const noBackground = !background;
+  if (typeof arg1 === 'string') {
+    title = arg1;
 
-  indentation.describeCounter++;
+    if (typeof arg2 === 'function') cb = arg2;
+    else options = arg2;
+  } else if (typeof arg1 === 'function') {
+    cb = arg1;
+    options = arg2 as DescribeOptions;
+  }
 
   /* c8 ignore start */
-  if (noBackground) {
-    write(`${format.bold(message)}`);
-    return;
-  }
+  if (title) {
+    const { background, icon } = options || {};
+    const message = `${cb ? '›' : icon || '☰'} ${title || ''}`;
+    const noBackground = !background;
 
-  write(
-    `${format.bg(backgroundColor[typeof background === 'string' ? background : 'grey'], message)}`
-  );
+    indentation.describeCounter++;
+
+    if (noBackground) write(`${format.bold(message)}`);
+    else {
+      write(
+        `${format.bg(backgroundColor[typeof background === 'string' ? background : 'grey'], message)}`
+      );
+    }
+  }
   /* c8 ignore stop */
-};
+
+  if (typeof cb !== 'function') return;
+
+  const resultCb = cb();
+
+  /* c8 ignore next */
+  if (resultCb instanceof Promise) await resultCb;
+}

test/integration/describe/describe.test.ts

@@ -1,2 +1,38 @@
-// import { describe } from '../../../src/modules/describe.js';
-// import { test } from '../../../src/modules/test.js';
+import { describe } from '../../../src/modules/describe.js';
+import { test } from '../../../src/modules/test.js';
+
+describe('Testing "describe" method', {
+  icon: '🔬',
+});
+
+test('Using as titles', () => {
+  describe('');
+  describe('', {});
+});
+
+test('Using as functions', async () => {
+  describe(() => {});
+  describe(() => true);
+  describe(() => false);
+  describe(() => undefined);
+  describe(() => new Promise((resolve) => resolve(undefined)));
+  describe(async () => await new Promise((resolve) => resolve(undefined)));
+
+  await describe(() => new Promise((resolve) => resolve(undefined)));
+  await describe(
+    async () => await new Promise((resolve) => resolve(undefined))
+  );
+});
+
+test('Using as groups', async () => {
+  describe('', () => {});
+  describe('', () => true);
+  describe('', () => false);
+  describe('', () => undefined);
+  describe('', () => new Promise((resolve) => resolve(undefined)));
+  describe('', async () => await new Promise((resolve) => resolve(undefined)));
+
+  await describe('', () => new Promise((resolve) => resolve(undefined)));
+  await describe('', async () =>
+    await new Promise((resolve) => resolve(undefined)));
+});

website/docs/documentation/helpers/describe.mdx

@@ -3,36 +3,35 @@ sidebar_position: 2
 ---
 
 import { FAQ } from '@site/src/components/FAQ';
-import Example from '@site/static/img/describe-example.png';
 
 # describe
 
-On **Poku**, `describe` is just a pretty `console.log` to title your test suites in the terminal.
+## Using as test titles
+
+On **Poku**, `describe` can be used just as a pretty `console.log` to title your test suites in the terminal.
 
 ```ts
 import { describe, assert } from 'poku';
 
-describe('Group A');
-assert(true, '1');
-assert(true, '2');
+describe('Test Title');
 
-describe('Group B');
 assert(true, '1');
 assert(true, '2');
 ```
 
-## Personalization
+### Personalization
 
 > `describe(title: string, options?: DescribeOptions)`
 
-### background
+#### background
 
 Change the background color for your personal title.
 
 ```ts
 import { describe, assert } from 'poku';
 
-describe('Group A', { background: 'blue' });
+describe('Test Title', { background: 'blue' });
+
 assert.ok(true, '1');
 assert.ok(true, '2');
 ```
@@ -57,7 +56,7 @@ assert.ok(true, '2');
 
 </FAQ>
 
-### icon (prefix)
+#### icon (prefix)
 
 **Poku** also allows the prefix customization.
 
@@ -66,42 +65,37 @@ assert.ok(true, '2');
 ```ts
 import { describe, assert } from 'poku';
 
-describe('Group A', { icon: '🚀' });
+describe('Test Title', { icon: '🔬' });
+
 assert.ok(true, '1');
 assert.ok(true, '2');
 ```
 
-<hr />
+## Grouping tests (usual)
 
-## Overview
-
-<FAQ title='Source'>
-
-    ```ts
-    import { assert, describe } from 'poku';
-
-    describe('Needs to Succeed', {
-      icon: '🚀',
-    });
+```ts
+import { describe, assert } from 'poku';
 
-    assert.ok(true, 'Test 1');
-    assert.ok(true, 'Test 2');
+describe(() => {
+  assert.equal(1 + 1, 2, '1 + 1 should be 2');
+  assert.equal(2 + 2, 4, '2 + 2 should be 4');
+});
+```
 
-    describe('Needs to Fail', {
-      background: 'yellow',
-      icon: '🚫',
-    });
+```ts
+import { describe, assert } from 'poku';
 
-    assert.throws(() => { throw new Error() }, 'Test 1');
-    assert.throws(() => { throw new Error() }, 'Test 2');
-    ```
+describe('Sum tests', () => {
+  assert.equal(1 + 1, 2);
+  assert.equal(2 + 2, 4);
+});
+```
 
-</FAQ>
+```ts
+import { describe, assert } from 'poku';
 
-<table>
-  <tr>
-    <td>
-      <img src={Example} />
-    </td>
-  </tr>
-</table>
+describe('Sum tests', () => {
+  assert.equal(1 + 1, 2, '1 + 1 should be 2');
+  assert.equal(2 + 2, 4, '2 + 2 should be 4');
+});
+```