From b1ea52dcce900e5376f3a76712ac4a27ef51d9de Mon Sep 17 00:00:00 2001 From: wellwelwel <46850407+wellwelwel@users.noreply.github.com> Date: Sat, 20 Jul 2024 05:44:45 -0300 Subject: [PATCH] docs: improve config descriptions and intellisense --- fixtures/schemas/options.json | 42 +++++++++++++++++++ src/@types/poku.ts | 28 ++++++++++--- src/bin/index.ts | 25 +++++++---- src/modules/index.ts | 9 ++-- src/parsers/options.ts | 8 ++-- .../docs/documentation/poku/config-files.mdx | 22 +++++++++- 6 files changed, 110 insertions(+), 24 deletions(-) diff --git a/fixtures/schemas/options.json b/fixtures/schemas/options.json index 0fde7ab0..c4a345d4 100644 --- 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 index cbbb7208..0ebc4129 100644 --- 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; +} & Omit< + Configs, + 'beforeEach' | 'afterEach' | 'noExit' | 'filter' | 'exclude' +> & + cliConfigs; -export type ConfigModuleFile = { - filter?: RegExp; - exclude?: RegExp; -} & Omit; +export type ConfigFile = Omit & cliConfigs; diff --git a/src/bin/index.ts b/src/bin/index.ts index 67a7b0bf..9fe8f431 100644 --- a/src/bin/index.ts +++ b/src/bin/index.ts @@ -72,13 +72,17 @@ import { getConfigs } from '../parsers/options.js'; const tasks: Promise[] = []; - 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 index 24fc8233..22822146 100755 --- 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 index 3284dc59..1bbc2945 100644 --- 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 => { +): Promise => { 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(configsFile); + return JSONC.parse(configsFile); } catch {} } diff --git a/website/docs/documentation/poku/config-files.mdx b/website/docs/documentation/poku/config-files.mdx index 6cc7b1bc..91c94e8b 100644 --- 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"],