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()