@crustjs/testing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chenxin Yan
+
+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,15 @@
+# @crustjs/testing
+
+Typed terminal testing helpers for Crust CLI applications.
+
+Use core `app.run(path, input)` for quiet captured output and typed completed/finished/failed outcomes. `captureExecute(app, argv)` tests terminal parsing, error presentation, and exit codes. `runInteractive(app, path, input)` from `@crustjs/testing/interactive` drives fake-terminal prompts (requires `@crustjs/prompts`) and propagates failed outcomes through `done` and `waitFor`.
+
+## Install
+
+```sh
+bun add -d @crustjs/testing
+```
+
+## Documentation
+
+Full docs: [crustjs.com/docs/modules/testing](https://crustjs.com/docs/modules/testing)

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { InvocationIO } from "@crustjs/core";
+//#region src/index.d.ts
+/** Structural io shape accepted by {@link captureExecute}. */
+export type CaptureIO = Partial<InvocationIO>;
+/** Minimal structural surface of `execute()` invoked by {@link captureExecute}. */
+export interface ExecutableApp {
+  execute(options?: {
+    argv?: string[];
+    io?: CaptureIO;
+  }): Promise<number>;
+}
+export interface CapturedExecute {
+  readonly stdout: string;
+  readonly stderr: string;
+  /** The exit code `execute()` established (`0`, `1`, or `130` for cancellation). */
+  readonly exitCode: number;
+}
+/**
+ * Drive the terminal `execute()` path in-process: exit-code protocol,
+ * Extension `onError` rendering, and cancellation (130) are all observable
+ * without spawning a subprocess.
+ */
+export declare function captureExecute(app: ExecutableApp, argv: readonly string[]): Promise<CapturedExecute>;
+//#endregion

package/dist/index.js

@@ -0,0 +1,37 @@
+//#region src/index.ts
+let activeExecuteCaptures = 0;
+let exitCodeBeforeExecuteCaptures;
+/**
+* Drive the terminal `execute()` path in-process: exit-code protocol,
+* Extension `onError` rendering, and cancellation (130) are all observable
+* without spawning a subprocess.
+*/
+async function captureExecute(app, argv) {
+	const stdoutLines = [];
+	const stderrLines = [];
+	if (activeExecuteCaptures === 0) exitCodeBeforeExecuteCaptures = process.exitCode;
+	activeExecuteCaptures++;
+	try {
+		const exitCode = await app.execute({
+			argv: [...argv],
+			io: {
+				stdout: (text) => {
+					stdoutLines.push(text);
+				},
+				stderr: (text) => {
+					stderrLines.push(text);
+				}
+			}
+		});
+		return {
+			stdout: stdoutLines.join("\n"),
+			stderr: stderrLines.join("\n"),
+			exitCode
+		};
+	} finally {
+		activeExecuteCaptures--;
+		if (activeExecuteCaptures === 0) process.exitCode = exitCodeBeforeExecuteCaptures ?? 0;
+	}
+}
+//#endregion
+export { captureExecute };

package/dist/interactive.d.ts

@@ -0,0 +1,13 @@
+import { Key } from "@crustjs/prompts/testing";
+import { AnyCrust, CommandPath, CommandShapeAt, RunInputArguments } from "@crustjs/core";
+//#region src/interactive.d.ts
+export interface InteractiveRun {
+  waitFor(pattern: RegExp, timeoutMs?: number): Promise<void>;
+  type(text: string): void;
+  keys(...namedKeys: Key[]): void;
+  screen(): string;
+  readonly done: Promise<void>;
+}
+/** Run an application with fake terminal streams for its prompts and stderr output. */
+export declare function runInteractive<App extends AnyCrust, const Path extends CommandPath<App["_types"]["tree"]>>(app: App, path: Path, ...args: RunInputArguments<CommandShapeAt<App["_types"]["shape"], Path>>): InteractiveRun;
+//#endregion

package/dist/interactive.js

@@ -0,0 +1,49 @@
+import { setTimeout } from "node:timers/promises";
+import { withTerminalIO } from "@crustjs/prompts";
+import { createPromptIO } from "@crustjs/prompts/testing";
+//#region src/interactive.ts
+/** Run an application with fake terminal streams for its prompts and stderr output. */
+function runInteractive(app, path, ...args) {
+	const harness = createPromptIO();
+	const output = harness.io.output;
+	const [input] = args;
+	const done = withTerminalIO(harness.io, () => app.run(path, input, {
+		stdout: () => {},
+		stderr: (text) => {
+			output.write(`${text}\n`);
+		}
+	}).then((outcome) => {
+		if (outcome.status === "failed") throw outcome.error;
+	}));
+	let settled = false;
+	let failed = false;
+	let failure;
+	done.then(() => {
+		settled = true;
+	}, (cause) => {
+		settled = true;
+		failed = true;
+		failure = cause;
+	});
+	return {
+		waitFor: async (pattern, timeoutMs = 5e3) => {
+			const matcher = new RegExp(pattern.source, pattern.flags.replace(/[gy]/g, ""));
+			const deadline = Date.now() + timeoutMs;
+			while (!matcher.test(harness.screen())) {
+				if (settled) {
+					if (matcher.test(harness.screen())) return;
+					if (failed) throw failure;
+					throw new Error(`waitFor(${matcher}) never matched; the application already completed. Screen:\n${harness.screen()}`);
+				}
+				if (Date.now() > deadline) throw new Error(`waitFor(${matcher}) timed out after ${timeoutMs}ms. Screen:\n${harness.screen()}`);
+				await setTimeout(1);
+			}
+		},
+		type: (text) => harness.type(text),
+		keys: (...namedKeys) => harness.keys(...namedKeys),
+		screen: () => harness.screen(),
+		done
+	};
+}
+//#endregion
+export { runInteractive };

package/package.json

@@ -0,0 +1,74 @@
+{
+	"name": "@crustjs/testing",
+	"version": "0.1.0",
+	"description": "Testing helpers for Crust CLI applications",
+	"type": "module",
+	"sideEffects": false,
+	"license": "MIT",
+	"author": "chenxin-yan",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/chenxin-yan/crust.git",
+		"directory": "packages/testing"
+	},
+	"homepage": "https://crustjs.com",
+	"bugs": {
+		"url": "https://github.com/chenxin-yan/crust/issues"
+	},
+	"keywords": [
+		"cli",
+		"testing",
+		"crust",
+		"bun",
+		"typescript"
+	],
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./interactive": {
+			"types": "./dist/interactive.d.ts",
+			"import": "./dist/interactive.js"
+		}
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsdown",
+		"dev": "tsdown --watch",
+		"check:types": "tsc --noEmit",
+		"test": "bun test",
+		"prepack": "cp ../../LICENSE LICENSE",
+		"postpack": "rm -f LICENSE"
+	},
+	"devDependencies": {
+		"@crustjs/config": "0.0.0",
+		"@crustjs/core": "0.2.0",
+		"@crustjs/progress": "0.1.0",
+		"@crustjs/prompts": "0.2.0",
+		"tsdown": "^0.23.0"
+	},
+	"peerDependencies": {
+		"@crustjs/core": "^0.2.0",
+		"@crustjs/prompts": "0.x",
+		"typescript": "^7.0.0"
+	},
+	"peerDependenciesMeta": {
+		"@crustjs/prompts": {
+			"optional": true
+		},
+		"typescript": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"bun": ">=1.3.14",
+		"node": ">=22",
+		"deno": ">=2.8"
+	}
+}