feat(test): support for Node.js familiar API usage (#352)

* feat: support for Node.js `test` familiar API usage

* refactor: better organize types and configs

* docs: include all `test` approaches

* ci: use imports from modules

benchmark/test/poku/failure.spec.js

@@ -1,6 +1,6 @@
 import { test, assert } from 'poku';
 import { sum } from '../../src/sum.js';
 
-test(() => {
-  assert.equal(sum(4, 4), 4, 'should add 4 + 4');
+test('should add 4 + 4', () => {
+  assert.equal(sum(4, 4), 4);
 });

benchmark/test/poku/success.spec.js

@@ -1,6 +1,6 @@
 import { test, assert } from 'poku';
 import { sum } from '../../src/sum.js';
 
-test(() => {
-  assert.equal(sum(2, 2), 4, 'should add 2 + 2');
+test('should add 2 + 2', () => {
+  assert.equal(sum(2, 2), 4);
 });

src/@types/describe.ts

@@ -0,0 +1,18 @@
+/* c8 ignore start */
+
+import { type backgroundColor } from '../helpers/format.js';
+
+export type DescribeOptions = {
+  background?: keyof typeof backgroundColor | boolean;
+  /**
+   * @default "☰"
+   */
+  icon?: string;
+  /** @deprecated */
+  pad?: boolean;
+  /**
+   * @default "grey"
+   */
+};
+
+/* c8 ignore stop */

src/configs/indentation.ts

@@ -3,6 +3,8 @@
 export const indentation = {
   test: '  ',
   stdio: '      ',
+  describeCounter: 0,
+  testCounter: 0,
 };
 
 /* c8 ignore stop */

src/helpers/parse-assertion.ts

@@ -6,7 +6,7 @@ import { format } from './format.js';
 import { hr } from './hr.js';
 import { findFile } from './find-file.js';
 import { each } from '../configs/each.js';
-import { describeCounter } from '../modules/describe.js';
+import { indentation } from '../configs/indentation.js';
 import { fromEntries, entries } from '../polyfills/object.js';
 import { nodeVersion } from './get-runtime.js';
 import { write } from './logs.js';
@@ -56,7 +56,7 @@ export const parseAssertion = async (
   const isPoku =
     typeof process.env?.FILE === 'string' && process.env?.FILE.length > 0;
   const FILE = process.env.FILE;
-  const preIdentation = describeCounter > 0 ? '  ' : '';
+  const preIdentation = indentation.describeCounter > 0 ? '  ' : '';
 
   try {
     if (typeof each.before.cb === 'function' && each.before.assert) {

src/index.ts

@@ -2,7 +2,8 @@
 export { poku } from './modules/poku.js';
 export { exit } from './modules/exit.js';
 export { assert } from './modules/assert.js';
-export { describe, log } from './modules/describe.js';
+export { describe } from './modules/describe.js';
+export { log } from './modules/log.js';
 export { assertPromise } from './modules/assert-promise.js';
 export { beforeEach, afterEach } from './modules/each.js';
 export { publicListFiles as listFiles } from './modules/list-files-sync.js';

src/modules/describe.ts

@@ -1,30 +1,8 @@
-/* c8 ignore start */
-
 import { format, backgroundColor } from '../helpers/format.js';
 import { write } from '../helpers/logs.js';
-
-export let describeCounter = 0;
-
-export type DescribeOptions = {
-  /** @deprecated */
-  pad?: boolean;
-  /**
-   * @default "grey"
-   */
-  background?: keyof typeof backgroundColor | boolean;
-  /**
-   * @default "☰"
-   */
-  icon?: string;
-};
-
-/**
- * By default **Poku** only shows outputs generated from itself.
- * This helper allows you to use an alternative to `console.log` with **Poku**.
- *
- * Need to debug? Just use the [`debug`](https://poku.io/docs/documentation/poku/options/debug) option from `poku`.
- */
-export const log = (message: string) => write(`\x1b[0m${message}\x1b[0m`);
+import { indentation } from '../configs/indentation.js';
+/* c8 ignore next */
+import type { DescribeOptions } from '../@types/describe.js';
 
 /**
  * On **Poku**, `describe` is just a pretty `console.log` to title your test suites in the terminal.
@@ -35,8 +13,9 @@ export const describe = (title: string, options?: DescribeOptions) => {
   const message = `${icon || '☰'} ${title}`;
   const noBackground = !background;
 
-  describeCounter++;
+  indentation.describeCounter++;
 
+  /* c8 ignore start */
   if (noBackground) {
     write(`${format.bold(message)}`);
     return;
@@ -45,6 +24,5 @@ export const describe = (title: string, options?: DescribeOptions) => {
   write(
     `${format.bg(backgroundColor[typeof background === 'string' ? background : 'grey'], message)}`
   );
+  /* c8 ignore stop */
 };
-
-/* c8 ignore stop */

src/modules/log.ts

@@ -0,0 +1,13 @@
+/* c8 ignore start */
+
+import { write } from '../helpers/logs.js';
+
+/**
+ * By default **Poku** only shows outputs generated from itself.
+ * This helper allows you to use an alternative to `console.log` with **Poku**.
+ *
+ * Need to debug? Just use the [`debug`](https://poku.io/docs/documentation/poku/options/debug) option from `poku`.
+ */
+export const log = (message: string) => write(`\x1b[0m${message}\x1b[0m`);
+
+/* c8 ignore stop */

src/modules/test.ts

@@ -1,18 +1,39 @@
 /* c8 ignore next */
 import { each } from '../configs/each.js';
+import { describe } from './describe.js';
 
+export async function test(
+  message: string,
+  cb: () => Promise<unknown>
+): Promise<void>;
+export async function test(message: string, cb: () => unknown): Promise<void>;
 export async function test(cb: () => Promise<unknown>): Promise<void>;
 export function test(cb: () => unknown): void;
 export async function test(
-  cb: () => unknown | Promise<unknown>
+  ...args: [
+    string | (() => unknown | Promise<unknown>),
+    (() => unknown | Promise<unknown>)?,
+  ]
 ): Promise<void> {
+  let message: string | undefined;
+  let cb: () => unknown | Promise<unknown>;
+
   if (typeof each.before.cb === 'function' && each.before.test) {
     const beforeResult = each.before.cb();
+
     /* c8 ignore next */
     if (beforeResult instanceof Promise) await beforeResult;
   }
 
+  if (typeof args[0] === 'string') {
+    message = args[0];
+    cb = args[1] as () => unknown | Promise<unknown>;
+  } else cb = args[0] as () => unknown | Promise<unknown>;
+
+  if (message) describe(message, { icon: '›' });
+
   const resultCb = cb();
+
   /* c8 ignore next */
   if (resultCb instanceof Promise) await resultCb;
 

test/ci.test.ts

@@ -1,4 +1,4 @@
-import { poku } from '../src/index.js';
+import { poku } from '../src/modules/poku.js';
 
 poku(['./test/compatibility'], {
   parallel: true,

test/e2e/background-process.test.ts

@@ -1,10 +1,7 @@
-import {
-  startService,
-  assert,
-  test,
-  describe,
-  startScript,
-} from '../../src/index.js';
+import { describe } from '../../src/modules/describe.js';
+import { test } from '../../src/modules/test.js';
+import { assert } from '../../src/modules/assert.js';
+import { startScript, startService } from '../../src/modules/create-service.js';
 import { legacyFetch } from '../helpers/legacy-fetch.test.js';
 import { ext, isProduction } from '../helpers/capture-cli.test.js';
 import { getRuntime } from '../../src/helpers/get-runtime.js';
@@ -57,7 +54,6 @@ import { getRuntime } from '../../src/helpers/get-runtime.js';
 
   await test(async () => {
     describe('Start Service (Multiple Ports)', {
-      background: false,
       icon: '🔀',
     });
 
@@ -81,7 +77,6 @@ import { getRuntime } from '../../src/helpers/get-runtime.js';
 
   await test(async () => {
     describe('Start Script (Multiple Ports)', {
-      background: false,
       icon: '🔀',
     });
 
@@ -107,7 +102,6 @@ import { getRuntime } from '../../src/helpers/get-runtime.js';
   if (runtime === 'node') {
     await test(async () => {
       describe('Start Service (No Ports)', {
-        background: false,
         icon: '🔀',
       });
 
@@ -133,7 +127,6 @@ import { getRuntime } from '../../src/helpers/get-runtime.js';
 
     await test(async () => {
       describe('Start Script (No Ports)', {
-        background: false,
         icon: '🔀',
       });
 

test/e2e/cli.test.ts

@@ -1,4 +1,6 @@
-import { assert, describe, test } from '../../src/index.js';
+import { describe } from '../../src/modules/describe.js';
+import { test } from '../../src/modules/test.js';
+import { assert } from '../../src/modules/assert.js';
 import { executeCLI, ext, isProduction } from '../helpers/capture-cli.test.js';
 import { getRuntime } from '../../src/helpers/get-runtime.js';
 

test/e2e/exit-code.test.ts

@@ -1,4 +1,7 @@
-import { poku, assert, describe, test } from '../../src/index.js';
+import { describe } from '../../src/modules/describe.js';
+import { test } from '../../src/modules/test.js';
+import { poku } from '../../src/modules/poku.js';
+import { assert } from '../../src/modules/assert.js';
 
 describe('Poku Runner Suite', { icon: '🐷' });
 

test/integration/assert/assert-promise-no-message.test.ts

@@ -2,7 +2,6 @@ import { nodeVersion } from '../../../src/helpers/get-runtime.js';
 import { assertPromise as assert, describe, test } from '../../../src/index.js';
 
 describe('Assert Promise Suite (No Message)', {
-  background: false,
   icon: '🔬',
 });
 

test/integration/describe/describe.test.ts

@@ -0,0 +1,2 @@
+// import { describe } from '../../../src/modules/describe.js';
+// import { test } from '../../../src/modules/test.js';

test/integration/each/each-promise.test.ts

@@ -1,13 +1,9 @@
-import {
-  describe,
-  assert,
-  beforeEach,
-  afterEach,
-  test,
-} from '../../../src/index.js';
+import { describe } from '../../../src/modules/describe.js';
+import { test } from '../../../src/modules/test.js';
+import { assert } from '../../../src/modules/assert.js';
+import { beforeEach, afterEach } from '../../../src/modules/each.js';
 
 describe('Asynchronous Before and After Each Suite', {
-  background: false,
   icon: '🔬',
 });
 

test/integration/each/each.test.ts

@@ -1,13 +1,9 @@
-import {
-  describe,
-  assert,
-  beforeEach,
-  afterEach,
-  test,
-} from '../../../src/index.js';
+import { describe } from '../../../src/modules/describe.js';
+import { test } from '../../../src/modules/test.js';
+import { assert } from '../../../src/modules/assert.js';
+import { beforeEach, afterEach } from '../../../src/modules/each.js';
 
 describe('Before and After Each Suite', {
-  background: false,
   icon: '🔬',
 });
 

test/integration/test/test.test.ts

@@ -1,11 +1,31 @@
-import { test } from '../../../src/index.js';
+import { describe } from '../../../src/modules/describe.js';
+import { test } from '../../../src/modules/test.js';
 
-(async () => {
+describe('Testing "test" method', {
+  icon: '🔬',
+});
+
+test(async () => {
+  test(() => {});
   test(() => true);
   test(() => false);
   test(() => undefined);
   test(() => new Promise((resolve) => resolve(undefined)));
   test(async () => await new Promise((resolve) => resolve(undefined)));
+
   await test(() => new Promise((resolve) => resolve(undefined)));
   await test(async () => await new Promise((resolve) => resolve(undefined)));
-})();
+});
+
+test(async () => {
+  test('', () => {});
+  test('', () => true);
+  test('', () => false);
+  test('', () => undefined);
+  test('', () => new Promise((resolve) => resolve(undefined)));
+  test('', async () => await new Promise((resolve) => resolve(undefined)));
+
+  await test('', () => new Promise((resolve) => resolve(undefined)));
+  await test('', async () =>
+    await new Promise((resolve) => resolve(undefined)));
+});

test/run.test.ts

@@ -1,4 +1,4 @@
-import { poku } from '../src/index.js';
+import { poku } from '../src/modules/poku.js';
 
 poku(['test/unit', 'test/integration', 'test/e2e'], {
   parallel: true,

test/unit/assert.result-type.test.ts

@@ -1,4 +1,6 @@
-import { test, assert, describe } from '../../src/index.js';
+import { describe } from '../../src/modules/describe.js';
+import { test } from '../../src/modules/test.js';
+import { assert } from '../../src/modules/assert.js';
 import { parseResultType } from '../../src/helpers/parse-assertion.js';
 import { nodeVersion } from '../../src/helpers/get-runtime.js';
 

test/unit/deno/allow.test.ts

@@ -1,4 +1,6 @@
-import { assert, describe, test } from '../../../src/index.js';
+import { describe } from '../../../src/modules/describe.js';
+import { test } from '../../../src/modules/test.js';
+import { assert } from '../../../src/modules/assert.js';
 import { runner } from '../../../src/helpers/runner.js';
 
 describe('Deno Permissions (Allow)', { icon: '🔬' });

test/unit/deno/deny.test.ts

@@ -1,4 +1,6 @@
-import { assert, describe, test } from '../../../src/index.js';
+import { describe } from '../../../src/modules/describe.js';
+import { test } from '../../../src/modules/test.js';
+import { assert } from '../../../src/modules/assert.js';
 import { runner } from '../../../src/helpers/runner.js';
 
 describe('Deno Permissions (Deny)', { icon: '🔬' });

test/unit/pad.test.ts

@@ -1,4 +1,4 @@
-import { assert } from '../../src/index.js';
+import { assert } from '../../src/modules/assert.js';
 import { padStart } from '../../src/polyfills/pad.js';
 
 assert.deepStrictEqual(padStart('', 0, ''), '');

test/unit/run-test-file.test.ts

@@ -1,5 +1,7 @@
 import process from 'node:process';
-import { assert, describe, test } from '../../src/index.js';
+import { describe } from '../../src/modules/describe.js';
+import { test } from '../../src/modules/test.js';
+import { assert } from '../../src/modules/assert.js';
 import { runTestFile } from '../../src/services/run-test-file.js';
 import { getRuntime } from '../../src/helpers/get-runtime.js';
 

test/unit/run-tests.test.ts

@@ -1,4 +1,6 @@
-import { assert, describe, test } from '../../src/index.js';
+import { describe } from '../../src/modules/describe.js';
+import { test } from '../../src/modules/test.js';
+import { assert } from '../../src/modules/assert.js';
 import { runTests } from '../../src/services/run-tests.js';
 
 describe('Service: runTests', { icon: '🔬' });

website/docs/documentation/helpers/before-after-each/_category_.json

@@ -4,5 +4,5 @@
   "link": {
     "type": "generated-index"
   },
-  "position": 2
+  "position": 3
 }