@rstackjs/test-utils 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Rspack Contrib
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @rstackjs/test-utils
+
+<p>
+  <a href="https://npmjs.com/package/@rstackjs/test-utils">
+   <img src="https://img.shields.io/npm/v/@rstackjs/test-utils?style=flat-square&colorA=564341&colorB=EDED91" alt="npm version" />
+  </a>
+  <img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="license" />
+  <a href="https://npmcharts.com/compare/@rstackjs/test-utils?minimal=true"><img src="https://img.shields.io/npm/dm/@rstackjs/test-utils.svg?style=flat-square&colorA=564341&colorB=EDED91" alt="downloads" /></a>
+</p>
+
+Shared testing utilities for the Rstack ecosystem.
+
+## Installation
+
+```bash
+# pnpm
+pnpm add @rstackjs/test-utils -D
+# yarn
+yarn add @rstackjs/test-utils -D
+# npm
+npm add @rstackjs/test-utils -D
+# bun
+bun add @rstackjs/test-utils -D
+```
+
+## Usage
+
+### findFile
+
+Finds the first matching path in a file-content map. String matchers use suffix matching, and content hashes are ignored by default.
+
+```ts
+import { findFile } from '@rstackjs/test-utils';
+
+const files = {
+  '/dist/index.abcdef12.js': 'console.log("hello")',
+  '/dist/styles.css': '.root {}',
+};
+
+const scriptPath = findFile(files, 'index.js');
+// /dist/index.abcdef12.js
+```
+
+The matcher can be a string, regular expression, or function. Set `ignoreHash` to `false` to match the original path.
+
+```ts
+findFile(files, /styles\.css$/);
+findFile(files, (file) => file.endsWith('.css'));
+findFile(files, 'index.abcdef12.js', { ignoreHash: false });
+```
+
+### getDistFiles
+
+Recursively reads UTF-8 files from a dist directory. Source map files are excluded by default.
+
+```ts
+import { getDistFiles } from '@rstackjs/test-utils';
+
+const files = await getDistFiles('./dist');
+const filesWithSourceMaps = await getDistFiles('./dist', true);
+```
+
+### getFileContent
+
+Returns the content of the first file matched by the same matcher and options supported by `findFile`.
+
+```ts
+import { getFileContent } from '@rstackjs/test-utils';
+
+const content = getFileContent(files, 'index.js');
+// console.log("hello")
+```
+
+### getRandomPort
+
+Returns an available TCP port that has not already been returned by the current process.
+
+```ts
+import { getRandomPort } from '@rstackjs/test-utils';
+
+const port = await getRandomPort();
+```
+
+You can optionally provide the starting port. If it is unavailable, the next available port is returned.
+
+```ts
+const port = await getRandomPort(30000);
+```
+
+### isPortAvailable
+
+Checks whether a TCP port is currently available to bind. The port is released before the promise resolves.
+
+```ts
+import { isPortAvailable } from '@rstackjs/test-utils';
+
+const available = await isPortAvailable(30000);
+```
+
+### proxyConsole
+
+Captures console output and removes ANSI control characters. By default, it captures `log`, `warn`, `info`, and `error`.
+
+```ts
+import { proxyConsole } from '@rstackjs/test-utils';
+
+const logHelper = proxyConsole({ types: ['warn', 'error'] });
+
+try {
+  console.warn('Something happened');
+  console.error('Something failed');
+
+  await logHelper.expectLog('Something happened');
+  logHelper.expectNoLog('Unexpected error');
+} finally {
+  logHelper.restore();
+}
+
+console.log(logHelper.logs);
+```
+
+### readDirContents
+
+Recursively reads UTF-8 files from a directory and returns a file-content map keyed by sorted absolute paths.
+
+```ts
+import { readDirContents } from '@rstackjs/test-utils';
+
+const files = await readDirContents('./dist');
+
+for (const [filePath, content] of Object.entries(files)) {
+  console.log(filePath, content);
+}
+```
+
+### toPosixPath
+
+Converts backslash path separators to POSIX forward slashes.
+
+```ts
+import { toPosixPath } from '@rstackjs/test-utils';
+
+const normalizedPath = toPosixPath('C:\\project\\src\\index.ts');
+// C:/project/src/index.ts
+```
+
+### waitFor
+
+Waits for a duration or polls a synchronous or asynchronous condition until it returns `true`.
+
+```ts
+import { waitFor } from '@rstackjs/test-utils';
+
+await waitFor(() => server.isReady(), {
+  interval: 50,
+  timeout: 5000,
+});
+```
+
+Condition polling uses a 100ms interval and a 5-second timeout by default.
+
+## License
+
+[MIT](./LICENSE).

package/dist/findFile.d.ts

@@ -0,0 +1,12 @@
+export type FileMatcher = string | RegExp | ((file: string) => boolean);
+export type FindFileOptions = {
+    /**
+     * Whether to ignore a content hash in the filename.
+     * @default true
+     */
+    ignoreHash?: boolean;
+};
+/**
+ * Find the first file path that matches the provided matcher.
+ */
+export declare const findFile: (files: Record<string, string>, matcher: FileMatcher, options?: FindFileOptions) => string;

package/dist/getDistFiles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Recursively read UTF-8 files from a dist directory.
+ *
+ * Source map files are excluded by default.
+ */
+export declare const getDistFiles: (distPath: string, sourceMaps?: boolean) => Promise<Record<string, string>>;

package/dist/getFileContent.d.ts

@@ -0,0 +1,5 @@
+import { type FileMatcher, type FindFileOptions } from './findFile.js';
+/**
+ * Return the content of the first file that matches the provided matcher.
+ */
+export declare const getFileContent: (files: Record<string, string>, matcher: FileMatcher, options?: FindFileOptions) => string;

package/dist/getRandomPort.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Check whether a TCP port is available to bind.
+ *
+ * The port is released before the returned promise resolves.
+ */
+export declare const isPortAvailable: (port: number) => Promise<boolean>;
+/**
+ * Return an available TCP port that has not been returned by this process.
+ *
+ * The default starting port is randomly selected between 15000 and 45000.
+ */
+export declare const getRandomPort: (startPort?: number) => Promise<number>;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { type FileMatcher, findFile, type FindFileOptions, } from './findFile.js';
+export { getDistFiles } from './getDistFiles.js';
+export { getFileContent } from './getFileContent.js';
+export { getRandomPort, isPortAvailable } from './getRandomPort.js';
+export { type ConsoleType, createLogHelper, type ExtendedLogHelper, type LogHelper, proxyConsole, type ProxyConsoleOptions, } from './proxyConsole.js';
+export { readDirContents } from './readDirContents.js';
+export { toPosixPath } from './toPosixPath.js';
+export { waitFor, type WaitForCondition, type WaitForOptions, } from './waitFor.js';

package/dist/index.js

@@ -0,0 +1,194 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join, resolve as external_node_path_resolve } from "node:path";
+import node_net from "node:net";
+import { stripVTControlCharacters, styleText } from "node:util";
+const HASH_PATTERN = /\.[0-9a-z]{8,}(?=\.)/gi;
+const toMatcher = (matcher)=>{
+    if ('function' == typeof matcher) return matcher;
+    if ('string' == typeof matcher) return (file)=>file.endsWith(matcher);
+    const regexp = new RegExp(matcher.source, matcher.flags);
+    return (file)=>{
+        regexp.lastIndex = 0;
+        return regexp.test(file);
+    };
+};
+const findFile = (files, matcher, options = {})=>{
+    const { ignoreHash = true } = options;
+    const matcherFn = toMatcher(matcher);
+    for (const file of Object.keys(files)){
+        const comparableFile = ignoreHash ? file.replace(HASH_PATTERN, '') : file;
+        if (matcherFn(comparableFile)) return file;
+    }
+    throw new Error(`Unable to find file matching "${matcher.toString()}"`);
+};
+const collectFilePaths = async (directoryPath)=>{
+    const entries = await readdir(directoryPath, {
+        withFileTypes: true
+    });
+    const filePaths = await Promise.all(entries.map((entry)=>{
+        const filePath = join(directoryPath, entry.name);
+        if (entry.isDirectory()) return collectFilePaths(filePath);
+        return entry.isFile() ? [
+            filePath
+        ] : [];
+    }));
+    return filePaths.flat();
+};
+const readDirContents = async (directoryPath)=>{
+    const filePaths = await collectFilePaths(external_node_path_resolve(directoryPath));
+    filePaths.sort();
+    const entries = await Promise.all(filePaths.map(async (filePath)=>[
+            filePath,
+            await readFile(filePath, 'utf-8')
+        ]));
+    return Object.fromEntries(entries);
+};
+const getDistFiles = async (distPath, sourceMaps = false)=>{
+    const files = await readDirContents(distPath);
+    if (sourceMaps) return files;
+    return Object.fromEntries(Object.entries(files).filter(([filePath])=>!filePath.endsWith('.map')));
+};
+const getFileContent = (files, matcher, options)=>files[findFile(files, matcher, options)];
+const usedPorts = new Set();
+const isPortAvailable = (port)=>{
+    try {
+        const server = node_net.createServer().listen(port);
+        return new Promise((resolve)=>{
+            server.on('listening', ()=>{
+                server.close(()=>{
+                    resolve(true);
+                });
+            });
+            server.on('error', ()=>{
+                resolve(false);
+            });
+        });
+    } catch  {
+        return Promise.resolve(false);
+    }
+};
+const getRandomPort = async (startPort = Math.ceil(30000 * Math.random()) + 15000)=>{
+    let port = startPort;
+    while(port <= 65535){
+        if (!usedPorts.has(port) && await isPortAvailable(port)) {
+            usedPorts.add(port);
+            return port;
+        }
+        port++;
+    }
+    throw new Error('No available ports found in the valid range.');
+};
+const toPosixPath = (filePath)=>filePath.replaceAll('\\', '/');
+const matchPattern = (log, pattern, options = {})=>{
+    const logToCheck = options.posix ? toPosixPath(log) : log;
+    if ('string' == typeof pattern) return options.strict ? logToCheck.split('\n').some((line)=>line.trim() === pattern.trim()) : logToCheck.includes(pattern);
+    if (pattern instanceof RegExp) return pattern.test(logToCheck);
+    return pattern(logToCheck);
+};
+const createLogHelper = ()=>{
+    const logs = [];
+    const originalLogs = [];
+    const logPatterns = new Set();
+    const clearLogs = ()=>{
+        logs.splice(0);
+    };
+    const addLog = (input)=>{
+        const log = stripVTControlCharacters(input);
+        logs.push(log);
+        originalLogs.push(input);
+        for (const { pattern, resolve, options } of logPatterns)if (matchPattern(log, pattern, options)) resolve(true);
+    };
+    const expectLog = async (pattern, options = {})=>{
+        if (logs.some((log)=>matchPattern(log, pattern, options))) return true;
+        return new Promise((resolve, reject)=>{
+            const timeoutId = setTimeout(()=>{
+                const title = styleText([
+                    'bold',
+                    'red'
+                ], 'Timeout: Expected log not found within 5 seconds.');
+                const expected = styleText('yellow', pattern.toString());
+                reject(new Error(`${title}\nExpect: ${expected}\nGet:\n${originalLogs.join('\n')}`));
+            }, 5000);
+            const patternEntry = {
+                pattern,
+                options,
+                resolve: (value)=>{
+                    clearTimeout(timeoutId);
+                    logPatterns.delete(patternEntry);
+                    resolve(value);
+                }
+            };
+            logPatterns.add(patternEntry);
+        });
+    };
+    const expectNoLog = (pattern, options = {})=>{
+        const result = logs.some((log)=>matchPattern(log, pattern, options));
+        if (result) {
+            const title = styleText([
+                'bold',
+                'red'
+            ], 'Unexpected log found.');
+            const unexpected = styleText('yellow', pattern.toString());
+            throw new Error(`${title}\nUnexpected: ${unexpected}\nGet:\n${originalLogs.join('\n')}`);
+        }
+    };
+    return {
+        logs,
+        originalLogs,
+        addLog,
+        clearLogs,
+        expectLog,
+        expectNoLog
+    };
+};
+const proxyConsole = ({ types = [
+    'log',
+    'warn',
+    'info',
+    'error'
+] } = {})=>{
+    const restores = [];
+    const logHelper = createLogHelper();
+    for (const type of Array.isArray(types) ? types : [
+        types
+    ]){
+        const method = console[type];
+        restores.push(()=>{
+            console[type] = method;
+        });
+        console[type] = (...args)=>{
+            const logMessage = args.map((arg)=>{
+                if ('string' == typeof arg) return arg;
+                return 'object' == typeof arg ? JSON.stringify(arg) : String(arg);
+            }).join(' ');
+            logHelper.addLog(logMessage);
+        };
+    }
+    const restore = ()=>{
+        for (const restoreMethod of restores)restoreMethod();
+    };
+    const printCapturedLogs = ()=>{
+        restore();
+        console.log(logHelper.originalLogs.join('\n'));
+    };
+    return {
+        restore,
+        printCapturedLogs,
+        ...logHelper
+    };
+};
+const delay = (milliseconds)=>new Promise((resolve)=>{
+        setTimeout(resolve, milliseconds);
+    });
+async function waitFor(millisecondsOrCondition, options = {}) {
+    if ('number' == typeof millisecondsOrCondition) return delay(millisecondsOrCondition);
+    const { interval = 100, timeout = 5000 } = options;
+    const startTime = Date.now();
+    while(true){
+        if (await millisecondsOrCondition()) return;
+        const elapsedTime = Date.now() - startTime;
+        if (elapsedTime >= timeout) throw new Error(`Timed out after ${timeout}ms while waiting for condition.`);
+        await delay(Math.min(interval, timeout - elapsedTime));
+    }
+}
+export { createLogHelper, findFile, getDistFiles, getFileContent, getRandomPort, isPortAvailable, proxyConsole, readDirContents, toPosixPath, waitFor };

package/dist/proxyConsole.d.ts

@@ -0,0 +1,35 @@
+export type ConsoleType = 'error' | 'group' | 'info' | 'log' | 'table' | 'warn';
+type LogPattern = string | RegExp | ((log: string) => boolean);
+type MatchPatternOptions = {
+    /**
+     * Whether to use exact line matching instead of substring matching.
+     * @default false
+     */
+    strict?: boolean;
+    /**
+     * Whether to convert file paths to POSIX format before matching.
+     * @default false
+     */
+    posix?: boolean;
+};
+export declare const createLogHelper: () => {
+    logs: string[];
+    originalLogs: string[];
+    addLog: (input: string) => void;
+    clearLogs: () => void;
+    expectLog: (pattern: LogPattern, options?: MatchPatternOptions) => Promise<boolean>;
+    expectNoLog: (pattern: LogPattern, options?: MatchPatternOptions) => void;
+};
+export type LogHelper = ReturnType<typeof createLogHelper>;
+export type ProxyConsoleOptions = {
+    types?: ConsoleType | ConsoleType[];
+};
+export type ExtendedLogHelper = LogHelper & {
+    /** Restore the original console methods. */
+    restore: () => void;
+    /** Restore the original console methods and print the captured logs. */
+    printCapturedLogs: () => void;
+};
+/** Proxy the console methods to capture logs. */
+export declare const proxyConsole: ({ types, }?: ProxyConsoleOptions) => ExtendedLogHelper;
+export {};

package/dist/readDirContents.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Recursively read UTF-8 files from a directory.
+ *
+ * The returned record uses sorted absolute file paths as keys.
+ */
+export declare const readDirContents: (directoryPath: string) => Promise<Record<string, string>>;

package/dist/toPosixPath.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Convert backslash path separators to POSIX forward slashes.
+ */
+export declare const toPosixPath: (filePath: string) => string;

package/dist/waitFor.d.ts

@@ -0,0 +1,15 @@
+export type WaitForCondition = () => boolean | Promise<boolean>;
+export type WaitForOptions = {
+    /**
+     * Delay between condition checks in milliseconds.
+     * @default 100
+     */
+    interval?: number;
+    /**
+     * Maximum time to wait for the condition in milliseconds.
+     * @default 5000
+     */
+    timeout?: number;
+};
+export declare function waitFor(milliseconds: number): Promise<void>;
+export declare function waitFor(condition: WaitForCondition, options?: WaitForOptions): Promise<void>;

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@rstackjs/test-utils",
+  "version": "0.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rstackjs/test-utils"
+  },
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.13.2",
+    "prettier": "^3.9.4",
+    "rstack": "0.0.2",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "rs lib",
+    "dev": "rs lib -w",
+    "lint": "rs lint && prettier -c .",
+    "lint:write": "rs lint --fix && prettier -w .",
+    "test": "rs test",
+    "bump": "pnpx bumpp"
+  }
+}