docs: improve config descriptions and intellisense (#561)

wellwelwel · Jul 20, 2024 · 8dae9f3 · 8dae9f3
1 parent 368f396
commit 8dae9f3
Show file tree

Hide file tree

Showing 6 changed files with 110 additions and 24 deletions.
diff --git a/fixtures/schemas/options.json b/fixtures/schemas/options.json
@@ -50,6 +50,48 @@
       "description": "Stops the tests at the first failure.\nhttps://poku.io/docs/documentation/poku/options/fail-fast",
       "default": false
     },
+    "envFile": {
+      "type": "string",
+      "description": "Reads an environment file and sets the environment variables.\nhttps://poku.io/docs/documentation/helpers/env",
+      "default": ".env"
+    },
+    "kill": {
+      "description": "Terminates the specified ports, port ranges and process IDs.\nhttp://localhost:3000/docs/documentation/helpers/processes/kill",
+      "type": "object",
+      "properties": {
+        "port": {
+          "description": "Terminates the specified ports before running the test suite.\nhttp://localhost:3000/docs/documentation/helpers/processes/kill#killport",
+          "type": "array",
+          "items": {
+            "type": "number"
+          }
+        },
+        "range": {
+          "description": "Terminates the specified port range before running the test suite.\nhttp://localhost:3000/docs/documentation/helpers/processes/kill#killrange",
+          "type": "array",
+          "items": {
+            "type": "array",
+            "items": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "number"
+              }
+            ]
+          }
+        },
+        "pid": {
+          "description": "Terminates the specified processes before running the test suite.\nhttp://localhost:3000/docs/documentation/helpers/processes/kill#killpid",
+          "type": "array",
+          "items": {
+            "type": "number"
+          }
+        }
+      },
+      "required": [],
+      "additionalProperties": false
+    },
     "platform": {
       "type": "string",
       "description": "Determines the platform for test execution.\nhttps://poku.io/docs/documentation/poku/options/platform",

diff --git a/src/@types/poku.ts b/src/@types/poku.ts
@@ -87,13 +87,29 @@ export type FinalResults = {
   started: Date;
 };
 
-export type ConfigFile = {
+type cliConfigs = {
+  /** By default, **Poku** searches for _`.test.`_ and `.spec.` files, but you can customize it. */
   include?: string | string[];
+  /** Reads an environment file and sets the environment variables. */
+  envFile?: string;
+  /** Terminates the specified ports, port ranges and process IDs. */
+  kill?: {
+    /** Terminates the specified ports before running the test suite. */
+    port?: [number];
+    /** Terminates the specified port range before running the test suite. */
+    range?: [number, number][];
+    /** Terminates the specified processes before running the test suite. */
+    pid?: [number];
+  };
+};
+
+export type ConfigJSONFile = {
   filter?: string;
   exclude?: string;
-} & Omit<Configs, 'beforeEach' | 'afterEach' | 'noExit' | 'filter' | 'exclude'>;
+} & Omit<
+  Configs,
+  'beforeEach' | 'afterEach' | 'noExit' | 'filter' | 'exclude'
+> &
+  cliConfigs;
 
-export type ConfigModuleFile = {
-  filter?: RegExp;
-  exclude?: RegExp;
-} & Omit<ConfigFile, 'filter' | 'exclude'>;
+export type ConfigFile = Omit<Configs, 'noExit'> & cliConfigs;
diff --git a/src/bin/index.ts b/src/bin/index.ts
@@ -72,13 +72,17 @@ import { getConfigs } from '../parsers/options.js';
 
   const tasks: Promise<unknown>[] = [];
 
-  if (killPort) {
-    const ports = killPort.split(',').map(Number);
+  if (killPort || defaultConfigs?.kill?.port) {
+    const ports =
+      killPort?.split(',').map(Number) || defaultConfigs?.kill?.port || [];
     tasks.push(kill.port(ports));
   }
 
-  if (killRange) {
-    const ranges = killRange.split(',');
+  if (killRange || defaultConfigs?.kill?.range) {
+    const ranges =
+      killRange?.split(',') ||
+      defaultConfigs?.kill?.range?.map((range) => `${range[0]}-${range[1]}`) ||
+      [];
 
     for (const range of ranges) {
       const ports = range.split('-').map(Number);
@@ -88,14 +92,15 @@ import { getConfigs } from '../parsers/options.js';
     }
   }
 
-  if (killPID) {
-    const PIDs = killPID.split(',').map(Number);
+  if (killPID || defaultConfigs?.kill?.pid) {
+    const PIDs =
+      killPID?.split(',').map(Number) || defaultConfigs?.kill?.pid || [];
 
     tasks.push(kill.pid(PIDs));
   }
 
-  if (hasEnvFile) {
-    const envFilePath = getArg('env-file');
+  if (hasEnvFile || defaultConfigs?.envFile) {
+    const envFilePath = getArg('env-file') ?? defaultConfigs?.envFile;
 
     tasks.push(envFile(envFilePath));
   }
@@ -121,6 +126,10 @@ import { getConfigs } from '../parsers/options.js';
       cjs: denoCJS,
     },
     noExit: watchMode,
+    beforeEach:
+      'beforeEach' in defaultConfigs ? defaultConfigs.beforeEach : undefined,
+    afterEach:
+      'afterEach' in defaultConfigs ? defaultConfigs.afterEach : undefined,
   };
 
   if (debug || defaultConfigs?.debug) {

diff --git a/src/modules/index.ts b/src/modules/index.ts
@@ -1,4 +1,4 @@
-import type { ConfigModuleFile } from '../@types/poku.js';
+import type { ConfigFile } from '../@types/poku.js';
 
 export { poku } from './essentials/poku.js';
 export { assert } from './essentials/assert.js';
@@ -22,10 +22,6 @@ export { exit } from './helpers/exit.js';
 export { log } from './helpers/log.js';
 export { listFiles } from './helpers/list-files.js';
 
-/** 🐷 Auxiliary function to define the `poku` configurations */
-export const defineConfig = (options: ConfigModuleFile): ConfigModuleFile =>
-  options;
-
 export type { Code } from '../@types/code.js';
 export type { Configs } from '../@types/poku.js';
 export type {
@@ -41,3 +37,6 @@ export type {
   WaitForPortOptions,
 } from '../@types/wait-for.js';
 export type { Configs as ListFilesConfigs } from '../@types/list-files.js';
+
+/** 🐷 Auxiliary function to define the `poku` configurations */
+export const defineConfig = (options: ConfigFile) => options;
diff --git a/src/parsers/options.ts b/src/parsers/options.ts
@@ -1,5 +1,5 @@
 /* c8 ignore next */ // Types
-import type { ConfigFile, ConfigModuleFile } from '../@types/poku.js';
+import type { ConfigFile, ConfigJSONFile } from '../@types/poku.js';
 import { cwd } from 'node:process';
 import { normalize, join } from 'node:path';
 import { readFile } from '../polyfills/fs.js';
@@ -10,7 +10,7 @@ const processCWD = cwd();
 /* c8 ignore next */ // ?
 export const getConfigs = async (
   customPath?: string
-): Promise<ConfigFile | ConfigModuleFile> => {
+): Promise<ConfigFile | ConfigJSONFile> => {
   const expectedFiles = customPath
     ? [customPath]
     : new Set([
@@ -26,11 +26,11 @@ export const getConfigs = async (
     try {
       if (filePath.endsWith('.js') || filePath.endsWith('.cjs')) {
         /* c8 ignore next */ // ?
-        return (await import(normalize(filePath))) as ConfigModuleFile;
+        return (await import(normalize(filePath))) as ConfigFile;
       }
 
       const configsFile = await readFile(filePath, 'utf-8');
-      return JSONC.parse<ConfigFile>(configsFile);
+      return JSONC.parse<ConfigJSONFile>(configsFile);
     } catch {}
   }
 

diff --git a/website/docs/documentation/poku/config-files.mdx b/website/docs/documentation/poku/config-files.mdx
@@ -22,10 +22,19 @@ module.exports = defineConfig({
   parallel: false,
   debug: false,
   filter: /\.(test.|.spec)\./,
-  exclude: /.bak$/,
+  exclude: [], // regex
   failFast: false,
   concurrency: 0, // No limit
   quiet: false,
+  envFile: '.env',
+  kill: {
+    port: [3000],
+    range: [
+      [3000, 3003],
+      [4000, 4002],
+    ],
+    pid: [612],
+  },
   platform: 'node', // "node", "bun" and "deno"
   deno: {
     allow: ['run', 'env', 'read', 'hrtime', 'net'],
@@ -34,6 +43,8 @@ module.exports = defineConfig({
     // "cjs": true // all extensions
     // "cjs": false // no polyfill
   },
+  beforeEach: () => true, // Before each test file
+  afterEach: () => true, // After each test file
 });
 ```
 
@@ -52,6 +63,15 @@ Create a `poku.json` (or `poku.jsonc`) in your project's root directory, for exa
   "failFast": false,
   "concurrency": 0, // No limit
   "quiet": false,
+  "envFile": ".env",
+  "kill": {
+    "port": [3000],
+    "range": [
+      [3000, 3003],
+      [4000, 4002],
+    ],
+    "pid": [612],
+  },
   "platform": "node", // "node", "bun" and "deno"
   "deno": {
     "allow": ["run", "env", "read", "hrtime", "net"],