feat(it): support for Node.js familiar API usage (#354)

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

* ci: add `beforeEach` and `afterEach` tests to `it` method

src/index.ts

@@ -1,15 +1,16 @@
 /* c8 ignore start */
 export { poku } from './modules/poku.js';
-export { exit } from './modules/exit.js';
 export { assert } from './modules/assert.js';
+export { test } from './modules/test.js';
 export { describe } from './modules/describe.js';
+export { it } from './modules/it.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';
-export { test } from './modules/test.js';
 export { startService, startScript } from './modules/create-service.js';
 export { getPIDs, kill } from './modules/processes.js';
+export { exit } from './modules/exit.js';
 export type { Code } from './@types/code.js';
 export type { Configs } from './@types/poku.js';
 export type { Configs as ListFilesConfigs } from './@types/list-files.js';

src/modules/it.ts

@@ -0,0 +1,45 @@
+/* c8 ignore next */
+import { each } from '../configs/each.js';
+import { describe } from './describe.js';
+
+export async function it(
+  message: string,
+  cb: () => Promise<unknown>
+): Promise<void>;
+export async function it(message: string, cb: () => unknown): Promise<void>;
+export async function it(cb: () => Promise<unknown>): Promise<void>;
+export function it(cb: () => unknown): void;
+export async function it(
+  ...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;
+
+  if (typeof each.after.cb === 'function' && each.after.test) {
+    const afterResult = each.after.cb();
+    /* c8 ignore next */
+    if (afterResult instanceof Promise) await afterResult;
+  }
+}

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

@@ -0,0 +1,80 @@
+import { describe } from '../../../../src/modules/describe.js';
+import { it } from '../../../../src/modules/it.js';
+import { assert } from '../../../../src/modules/assert.js';
+import { beforeEach, afterEach } from '../../../../src/modules/each.js';
+
+let counter = 0;
+
+const asyncPreIncrement = async () =>
+  await new Promise((resolve) => resolve(++counter));
+
+const beforeEachHelper = beforeEach(asyncPreIncrement, { immediate: true });
+
+const afterEachHelper = afterEach(asyncPreIncrement, {});
+
+describe('Asynchronous Before and After Each Suite (it)', () => {
+  it(() => {
+    assert.equal(
+      counter,
+      2,
+      'value incremented by 1 from beforeEach with immediate option should be 2'
+    );
+  });
+
+  it(() => {
+    assert.equal(
+      counter,
+      4,
+      'value incremented by 1 from beforeEach with immediate option and by 1 from previous test with afterEach should be 4'
+    );
+  });
+
+  afterEachHelper.pause();
+  beforeEachHelper.pause();
+
+  it(() => {
+    assert.equal(
+      counter,
+      5,
+      'value should still 5 by pausing both beforeEach and afterEach, considering the abscence of beforeEach effect'
+    );
+  });
+
+  it(() => {
+    assert.equal(
+      counter,
+      5,
+      'value should still 5 by pausing both beforeEach and afterEach, considering the the abscence of beforeEach and afterEach (from previous test) effects'
+    );
+  });
+
+  afterEachHelper.continue();
+  beforeEachHelper.continue();
+
+  it(() => {
+    assert.equal(
+      counter,
+      6,
+      'value incremented by 1 from unpausing beforeEach should be 6'
+    );
+  });
+
+  it(() => {
+    assert.equal(
+      counter,
+      8,
+      'value incremented by 1 from beforeEach and 1 by previous test with afterEach should be 8'
+    );
+  });
+
+  beforeEachHelper.reset();
+  afterEachHelper.reset();
+
+  it(() => {
+    assert.equal(
+      counter,
+      9,
+      'value should still 9 by reseting both beforeEach and afterEach'
+    );
+  });
+});

test/integration/it/each/each.test.ts

@@ -0,0 +1,84 @@
+import { describe } from '../../../../src/modules/describe.js';
+import { it } from '../../../../src/modules/it.js';
+import { assert } from '../../../../src/modules/assert.js';
+import { beforeEach, afterEach } from '../../../../src/modules/each.js';
+
+let counter = 0;
+
+const beforeEachHelper = beforeEach(
+  () => {
+    ++counter;
+  },
+  { immediate: true }
+);
+
+const afterEachHelper = afterEach(() => {
+  ++counter;
+}, {});
+
+describe('Before and After Each Suite (it)', () => {
+  it(() => {
+    assert.equal(
+      counter,
+      2,
+      'value incremented by 1 from beforeEach with immediate option should be 2'
+    );
+  });
+
+  it(() => {
+    assert.equal(
+      counter,
+      4,
+      'value incremented by 1 from beforeEach with immediate option and by 1 from previous test with afterEach should be 4'
+    );
+  });
+
+  afterEachHelper.pause();
+  beforeEachHelper.pause();
+
+  it(() => {
+    assert.equal(
+      counter,
+      5,
+      'value should still 5 by pausing both beforeEach and afterEach, considering the abscence of beforeEach effect'
+    );
+  });
+
+  it(() => {
+    assert.equal(
+      counter,
+      5,
+      'value should still 5 by pausing both beforeEach and afterEach, considering the the abscence of beforeEach and afterEach (from previous test) effects'
+    );
+  });
+
+  afterEachHelper.continue();
+  beforeEachHelper.continue();
+
+  it(() => {
+    assert.equal(
+      counter,
+      6,
+      'value incremented by 1 from unpausing beforeEach should be 6'
+    );
+  });
+
+  it(() => {
+    assert.equal(
+      counter,
+      8,
+      'value incremented by 1 from beforeEach and 1 by previous test with afterEach should be 8'
+    );
+  });
+
+  beforeEachHelper.reset();
+  afterEachHelper.reset();
+
+  it(() => {
+    assert.equal(
+      counter,
+      9,
+      'value should still 9 by reseting both beforeEach and afterEach'
+    );
+  });
+});

test/integration/it/it.test.ts

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

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

@@ -1,9 +1,9 @@
-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';
+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', {
+describe('Asynchronous Before and After Each Suite (test)', {
   icon: '🔬',
 });
 

test/integration/each/each.test.ts → test/integration/test/each/each.test.ts

@@ -1,9 +1,9 @@
-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';
+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', {
+describe('Before and After Each Suite (test)', {
   icon: '🔬',
 });
 

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

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

website/docs/documentation/helpers/describe.mdx

@@ -6,6 +6,8 @@ import { FAQ } from '@site/src/components/FAQ';
 
 # describe
 
+> `describe(title: string, options?: DescribeOptions)` | `describe(message: string, cb: () => void)` | `describe(cb: () => void)`
+
 ## Using as test titles
 
 On **Poku**, `describe` can be used just as a pretty `console.log` to title your test suites in the terminal.
@@ -21,8 +23,6 @@ assert(true, '2');
 
 ### Personalization
 
-> `describe(title: string, options?: DescribeOptions)`
-
 #### background
 
 Change the background color for your personal title.