feat: add .todo helper for describe, it, and test (#633)

* ci: add `todo` tdd * refactor: adjusts unreached lines * chore: adjust ignored paths * feat: add `.todo` helper for `describe`, `it`, and `test` * ci: add failure tests * ci: improve Windows timeout * ci: improve coverage * ci: improve coverage * docs: improve documentation * chore: adjust table size * docs: improve docs guides * docs: add `.todo` documentation and examples
wellwelwel · Aug 1, 2024 · 526112c · 526112c
1 parent 03005a5
commit 526112c
Show file tree

Hide file tree

Showing 44 changed files with 433 additions and 80 deletions.
diff --git a/.github/workflows/ci_coverage-windows.yml b/.github/workflows/ci_coverage-windows.yml
@@ -10,7 +10,7 @@ on:
 jobs:
   windows:
     runs-on: windows-latest
-    timeout-minutes: 5
+    timeout-minutes: 10
     strategy:
       fail-fast: false
     name: Windows

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -48,13 +48,23 @@ It's better to discuss an **API** before actually start implementing it. You can
 
 Check if there is an existing section or feel free to create a new one. You can find the wesite source code at [./website](https://github.com/wellwelwel/poku/tree/main/website).
 
+- Feel free to open PRs fixing typos or adding support for other languages 🤝
+
 <blockquote>
 
 Before commiting, consider to run:
 
 ```sh
 cd website
+
+# Installing dependencies
+npm ci
+
+# Fixing lint rules
 npm run lint:fix
+
+# Testing
+npm run test
 ```
 
 </blockquote>

diff --git a/README.md b/README.md
@@ -29,28 +29,51 @@ Enjoying **Poku**? Give him a star to show your support 🌟
 <img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Run **CommonJS** files directly with [**Deno**][deno-version-url]<br />
 <img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Auto detect **ESM**, **CJS**, and **TypeScript** files<br />
 <img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Run the **same test suite** for [**Node.js**][node-version-url], [**Bun**][bun-version-url], and [**Deno**][deno-version-url]<br />
-<img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Easily handle **servers**, **processes**, **ports**, and **containers** ✨
+<img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Easily handle **servers**, **processes**, **ports**, and even **containers** ✨
 
 ---
 
 ## Quickstart
 
 ### <img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Install
 
+<table>
+<tr>
+<td width="225">
+
 ```bash
 # Node.js
 npm i -D poku
+```
+
+</td>
+<td width="225">
 
+```bash
 # TypeScript (Node.js)
 npm i -D poku tsx
+```
 
+</td>
+<td width="225">
+
+```bash
 # Bun
 bun add -d poku
+```
+
+</td>
+<td width="225">
 
-# Deno
+```bash
+# Deno (optional)
 deno add npm:poku
 ```
 
+</td>
+</tr>
+</table>
+
 ---
 
 ### <img width="16" height="16" alt="check" src="https://raw.githubusercontent.com/wellwelwel/poku/main/.github/assets/readme/check.svg"> Test
@@ -220,8 +243,8 @@ To see the detailed documentation, please visit the [**Documentation**](https://
 
 - [Avoiding conflicts in environments with multiple platforms installed](https://poku.io/docs/tutorials/cross-platform#recommendations).
 - [Properly running asynchronous tests on the same file](https://poku.io/docs/examples/promises).
-- [Migrating from version **1.x** to version **2.x**](https://github.com/wellwelwel/poku/issues/533).
 - [Using **Poku** without installing on **Deno** and alternatives to **JSR**](https://github.com/wellwelwel/poku/discussions/565).
+- [Migrating from version **1.x** to version **2.x**](https://github.com/wellwelwel/poku/issues/533).
 
 ---
 

diff --git a/fixtures/final-results/skip-and-todo/skip.test.ts b/fixtures/final-results/skip-and-todo/skip.test.ts
@@ -0,0 +1,3 @@
+import { skip } from '../../../src/modules/helpers/skip.js';
+
+skip('Some skip');
diff --git a/fixtures/final-results/skip-and-todo/todo.test.ts b/fixtures/final-results/skip-and-todo/todo.test.ts
@@ -0,0 +1,3 @@
+import { test } from '../../../src/modules/helpers/test.js';
+
+test.todo('Some todo');
diff --git a/fixtures/final-results/skip-todo-and-failure/failure.test.ts b/fixtures/final-results/skip-todo-and-failure/failure.test.ts
@@ -0,0 +1,3 @@
+import { exit } from 'node:process';
+
+exit(1);
diff --git a/fixtures/final-results/skip-todo-and-failure/skip.test.ts b/fixtures/final-results/skip-todo-and-failure/skip.test.ts
@@ -0,0 +1,3 @@
+import { skip } from '../../../src/modules/helpers/skip.js';
+
+skip('Some skip');
diff --git a/fixtures/final-results/skip-todo-and-failure/todo.test.ts b/fixtures/final-results/skip-todo-and-failure/todo.test.ts
@@ -0,0 +1,3 @@
+import { test } from '../../../src/modules/helpers/test.js';
+
+test.todo('Some todo');
diff --git a/fixtures/final-results/skip/skip.test.ts b/fixtures/final-results/skip/skip.test.ts
@@ -0,0 +1,3 @@
+import { skip } from '../../../src/modules/helpers/skip.js';
+
+skip('Some skip');
diff --git a/fixtures/final-results/todo/todo.test.ts b/fixtures/final-results/todo/todo.test.ts
@@ -0,0 +1,3 @@
+import { test } from '../../../src/modules/helpers/test.js';
+
+test.todo('Some todo');
diff --git a/fixtures/schemas/options.json b/fixtures/schemas/options.json
@@ -13,7 +13,7 @@
       "items": {
         "type": "string"
       },
-      "description": "Specify the path(s) to include in the configuration.\nhttps://poku.io/docs/documentation/poku/include-files",
+      "description": "Specify the path(s) to include in the configuration. Doesn't support glob patterns.\nhttps://poku.io/docs/documentation/poku/include-files",
       "default": "."
     },
     "parallel": {

diff --git a/src/bin/index.ts b/src/bin/index.ts
@@ -20,7 +20,8 @@ import { getConfigs } from '../parsers/options.js';
   const defaultConfigs = await getConfigs(configFile);
 
   const dirs: string[] = (() => {
-    const includeArg = getArg('include'); // deprecated
+    /* c8 ignore next 4 */ // Deprecated
+    const includeArg = getArg('include');
     if (includeArg !== undefined) {
       return includeArg.split(',');
     }
@@ -38,6 +39,7 @@ import { getConfigs } from '../parsers/options.js';
   const killPort = getArg('kill-port');
   const killRange = getArg('kill-range');
   const killPID = getArg('kill-pid');
+  /* c8 ignore start */ // Deno
   const denoAllow = argToArray('deno-allow') ?? defaultConfigs?.deno?.allow;
   const denoDeny = argToArray('deno-deny') ?? defaultConfigs?.deno?.deny;
   const denoCJS =
@@ -47,6 +49,7 @@ import { getConfigs } from '../parsers/options.js';
       .filter((a) => a) ||
     hasArg('deno-cjs') ||
     defaultConfigs?.deno?.cjs;
+  /* c8 ignore stop */
   const parallel =
     hasArg('parallel') || hasArg('p', '-') || defaultConfigs?.parallel;
   const quiet = hasArg('quiet') || hasArg('q', '-') || defaultConfigs?.quiet;
@@ -70,6 +73,7 @@ import { getConfigs } from '../parsers/options.js';
 
   const tasks: Promise<unknown>[] = [];
 
+  /* c8 ignore start */ // Process-based
   if (killPort || defaultConfigs?.kill?.port) {
     const ports =
       killPort?.split(',').map(Number) || defaultConfigs?.kill?.port || [];
@@ -96,6 +100,7 @@ import { getConfigs } from '../parsers/options.js';
 
     tasks.push(kill.pid(PIDs));
   }
+  /* c8 ignore stop */
 
   if (hasEnvFile || defaultConfigs?.envFile) {
     const envFilePath = getArg('env-file') ?? defaultConfigs?.envFile;
@@ -104,6 +109,7 @@ import { getConfigs } from '../parsers/options.js';
   }
 
   const options: Configs = {
+    /* c8 ignore next 11 */ // Varies Platform
     platform: platformIsValid(platform)
       ? platform
       : hasArg('node')
@@ -152,6 +158,7 @@ import { getConfigs } from '../parsers/options.js';
 
   let isRunning = false;
 
+  /* c8 ignore start */ // Process-based
   const listenStdin = (input: Buffer | string) => {
     if (isRunning || executing.size > 0) {
       return;
@@ -167,6 +174,7 @@ import { getConfigs } from '../parsers/options.js';
       startTests();
     }
   };
+  /* c8 ignore stop */
 
   const resultsClear = () => {
     fileResults.success.clear();
@@ -184,6 +192,7 @@ import { getConfigs } from '../parsers/options.js';
       poku(dirs, options)
         .then(() => {
           if (watchMode) {
+            /* c8 ignore next 2 */ // Process-based
             process.stdin.removeListener('data', listenStdin);
             process.removeListener('SIGINT', onSigint);
             resultsClear();
@@ -245,6 +254,7 @@ import { getConfigs } from '../parsers/options.js';
               `${format('Watching:').bold()} ${format(dirs.join(', ')).underline()}`
             );
 
+            /* c8 ignore next 2 */ // Process-based
             process.stdin.setEncoding('utf-8');
             process.stdin.on('data', listenStdin);
           }

diff --git a/src/configs/poku.ts b/src/configs/poku.ts
@@ -1,5 +1,6 @@
 export const results = {
   success: 0,
   fail: 0,
-  skipped: 0,
+  skip: 0,
+  todo: 0,
 };
diff --git a/src/modules/essentials/poku.ts b/src/modules/essentials/poku.ts
@@ -8,13 +8,13 @@ import { format, showTestResults } from '../../services/format.js';
 import { isQuiet } from '../../parsers/output.js';
 import { finalResults } from '../../configs/files.js';
 
-/* c8 ignore next 3 */ // Process-based
+/* c8 ignore start */ // Process-based
 export const onSigint = () => {
   process.stdout.write('\u001B[?25h');
 };
 
-/* c8 ignore next */ // Process-based
 process.once('SIGINT', onSigint);
+/* c8 ignore stop */
 
 export async function poku(
   targetPaths: string | string[],
@@ -33,8 +33,7 @@ export async function poku(
   finalResults.started = new Date();
 
   const start = process.hrtime();
-  const prepareDirs = Array.prototype.concat(targetPaths);
-  const dirs = prepareDirs.length > 0 ? prepareDirs : ['.'];
+  const dirs = Array.prototype.concat(targetPaths);
   const showLogs = !isQuiet(configs);
 
   // Sequential
@@ -62,7 +61,6 @@ export async function poku(
     showLogs && showTestResults();
 
     exit(code, configs?.quiet);
-    return;
   }
 
   // Parallel

diff --git a/src/modules/helpers/describe.ts b/src/modules/helpers/describe.ts
@@ -3,16 +3,17 @@ import { hrtime, env } from 'node:process';
 import { format } from '../../services/format.js';
 import { Write } from '../../services/write.js';
 import { indentation } from '../../configs/indentation.js';
+import { todo } from './it/todo.js';
 
-export async function describe(
+async function describeCore(
   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(
+function describeCore(title: string, cb: () => unknown): void;
+async function describeCore(cb: () => Promise<unknown>): Promise<void>;
+function describeCore(cb: () => unknown): unknown;
+function describeCore(title: string, options?: DescribeOptions): void;
+async function describeCore(
   arg1: string | (() => unknown | Promise<unknown>),
   arg2?: (() => unknown | Promise<unknown>) | DescribeOptions
 ): Promise<void> {
@@ -76,3 +77,7 @@ export async function describe(
     );
   }
 }
+
+export const describe = Object.assign(describeCore, {
+  todo,
+});
diff --git a/src/modules/helpers/exit.ts b/src/modules/helpers/exit.ts
@@ -6,8 +6,35 @@ import { Write } from '../../services/write.js';
 import { fileResults, finalResults } from '../../configs/files.js';
 import { parseTime, parseTimeToSecs } from '../../parsers/time.js';
 
-export const exit = (code: Code, quiet?: boolean) => {
+export const exit = (code: Code, quiet?: boolean): never => {
   const isPoku = results.success > 0 || results.fail > 0;
+  const success = ` PASS › ${results.success - results.skip || 0} `;
+  const failure = ` FAIL › ${results.fail} `;
+  const skips = ` SKIP › ${results.skip} `;
+  const plans = ` TODO › ${results.todo} `;
+  const inline = results.skip === 0 || results.todo === 0;
+
+  let message = '';
+
+  if (inline) {
+    message += `${format(success).bg('green')} ${format(failure).bg(results.fail === 0 ? 'grey' : 'brightRed')}`;
+
+    if (results.skip) {
+      message += ` ${format(skips).bg('brightBlue')}`;
+    }
+
+    if (results.todo) {
+      message += ` ${format(plans).bg('brightBlue')}`;
+    }
+  } else {
+    message += `${format(success).success().bold()}\n`;
+    message +=
+      results.fail === 0
+        ? format(`${failure}\n`).bold()
+        : `${format(failure).fail().bold()}\n`;
+    message += `${format(skips).info().bold()}\n`;
+    message += `${format(plans).info().bold()}`;
+  }
 
   !quiet &&
     process.on('exit', (code) => {
@@ -23,9 +50,7 @@ export const exit = (code: Code, quiet?: boolean) => {
           `  ${format(`Test Files › ${format(String(fileResults.success.size + fileResults.fail.size)).bold()}`).dim()}`
         );
         Write.hr();
-        Write.log(
-          `${format(` PASS › ${results.success - results.skipped} `).bg('green')} ${format(` FAIL › ${results.fail} `).bg(results.fail === 0 ? 'grey' : 'red')} ${results.skipped > 0 ? format(` SKIPPED › ${results.skipped} `).bg(results.skipped === 0 ? 'grey' : 'blue') : ''}`
-        );
+        Write.log(message);
         Write.hr();
       }
 

diff --git a/src/modules/helpers/it/core.ts b/src/modules/helpers/it/core.ts
@@ -3,6 +3,7 @@ import { each } from '../../../configs/each.js';
 import { indentation } from '../../../configs/indentation.js';
 import { format } from '../../../services/format.js';
 import { Write } from '../../../services/write.js';
+import { todo } from './todo.js';
 
 async function itCore(
   message: string,
@@ -89,4 +90,6 @@ async function itCore(
   }
 }
 
-export const it = Object.assign(itCore, {});
+export const it = Object.assign(itCore, {
+  todo,
+});
diff --git a/src/modules/helpers/it/todo.ts b/src/modules/helpers/it/todo.ts
@@ -0,0 +1,9 @@
+import { Write } from '../../../services/write.js';
+import { indentation } from '../../../configs/indentation.js';
+import { format } from '../../../services/format.js';
+
+export const todo = (message: string, _cb?: () => unknown) => {
+  Write.log(
+    `${indentation.hasDescribe ? '  ' : ''}${format(`● ${message}`).cyan().bold()}`
+  );
+};
diff --git a/src/modules/helpers/list-files.ts b/src/modules/helpers/list-files.ts
@@ -70,7 +70,7 @@ export const getAllFiles = async (
 
       if (
         fullPath.indexOf('node_modules') !== -1 ||
-        fullPath.indexOf('.git') === 0
+        fullPath.indexOf('.git/') !== -1
       ) {
         return;
       }

diff --git a/src/modules/helpers/skip.ts b/src/modules/helpers/skip.ts
@@ -2,16 +2,16 @@ import { exit, env } from 'node:process';
 import { Write } from '../../services/write.js';
 import { format } from '../../services/format.js';
 
-export const skip = (message?: string) => {
+export const skip = (message = 'Skipping') => {
   const isPoku = typeof env?.FILE === 'string' && env?.FILE.length > 0;
   const FILE = env.FILE;
 
   if (message) {
     Write.log(
       format(
         isPoku
-          ? `ℹ ${message} ${format('›').dim()} ${format(`${FILE}`).italic().gray().dim()}`
-          : `ℹ ${message}`
+          ? `◯ ${message} ${format('›').dim()} ${format(`${FILE}`).italic().gray().dim()}`
+          : `◯ ${message}`
       )
         .info()
         .bold()
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		import { skip } from '../../../src/modules/helpers/skip.js';

		skip('Some skip');
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		import { test } from '../../../src/modules/helpers/test.js';

		test.todo('Some todo');
-Original file line number
+Diff line change
@@ Expand Up / @@ -70,7 +70,7 @@ export const getAllFiles = async ( @@
           if (
             fullPath.indexOf('node_modules') !== -1 ||
-            fullPath.indexOf('.git') === 0
+            fullPath.indexOf('.git/') !== -1
           ) {
             return;
           }
@@ Expand Down @@