@optique/testing 1.3.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025–2026 Hong Minhee
+
+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,42 @@
+@optique/testing
+================
+
+Testing support for [Optique] command-line interfaces.
+
+An Optique application can be exercised at four distinct execution boundaries,
+and this package gives each one its own entry point, so the scope of a test is
+visible from its import:
+
+ -  *@optique/testing/parser*: a parser on its own, without help rendering,
+    process integration, or command dispatch.
+ -  *@optique/testing/run*: what `run()` and `runAsync()` write through their
+    injected output callbacks, plus intentional exits.
+ -  *@optique/testing/discover*: a `runProgram()` invocation, including command
+    discovery and handler dispatch.
+ -  *@optique/testing/cli*: a real CLI entry point in a child process.
+
+The package root holds only the contracts that mean the same thing at more than
+one boundary.  It depends on no test framework and no assertion library.
+
+[Optique]: https://optique.dev/
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@optique/testing
+npm add @optique/testing
+pnpm add @optique/testing
+yarn add @optique/testing
+bun add @optique/testing
+~~~~
+
+
+Documentation
+-------------
+
+For full documentation, visit the [testing guide], which explains what each
+layer does and does not execute, and how to choose between them.
+
+[testing guide]: https://optique.dev/concepts/testing

package/dist/cli.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/discover.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/discover.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/index.d.cts

@@ -0,0 +1,46 @@
+//#region src/index.d.ts
+/**
+ * Testing support for Optique command-line interfaces.
+ *
+ * An Optique application can be exercised at four distinct execution
+ * boundaries, and this package gives each one its own entry point:
+ *
+ * - `@optique/testing/parser` runs a parser against an argument list without
+ *   help rendering, process integration, or command dispatch.
+ * - `@optique/testing/run` captures what `run()` and `runAsync()` write
+ *   through their injected output callbacks, along with intentional exits.
+ * - `@optique/testing/discover` captures a `runProgram()` invocation,
+ *   including command discovery and handler dispatch.
+ * - `@optique/testing/cli` invokes a real CLI entry point in a child process.
+ *
+ * This module holds only the contracts that mean the same thing at more than
+ * one of those boundaries.  Results that differ by layer—parsed values,
+ * intentional exits, terminating signals—belong to the subpath that produces
+ * them.
+ *
+ * @module
+ * @since 1.3.0
+ */
+/**
+ * Text captured from a program's standard output and standard error streams.
+ *
+ * The two streams are kept apart and their text is preserved exactly, so a
+ * test can assert on trailing newlines and on which stream a message reached.
+ * Each layer documents how it fills these fields: the in-process layers
+ * accumulate the text their injected writers receive, while the subprocess
+ * layer decodes whatever the child actually wrote.
+ *
+ * @since 1.3.0
+ */
+interface CapturedOutput {
+  /**
+   * The text written to standard output.  Empty when nothing was written.
+   */
+  readonly stdout: string;
+  /**
+   * The text written to standard error.  Empty when nothing was written.
+   */
+  readonly stderr: string;
+}
+//#endregion
+export { CapturedOutput };

package/dist/index.d.ts

@@ -0,0 +1,46 @@
+//#region src/index.d.ts
+/**
+ * Testing support for Optique command-line interfaces.
+ *
+ * An Optique application can be exercised at four distinct execution
+ * boundaries, and this package gives each one its own entry point:
+ *
+ * - `@optique/testing/parser` runs a parser against an argument list without
+ *   help rendering, process integration, or command dispatch.
+ * - `@optique/testing/run` captures what `run()` and `runAsync()` write
+ *   through their injected output callbacks, along with intentional exits.
+ * - `@optique/testing/discover` captures a `runProgram()` invocation,
+ *   including command discovery and handler dispatch.
+ * - `@optique/testing/cli` invokes a real CLI entry point in a child process.
+ *
+ * This module holds only the contracts that mean the same thing at more than
+ * one of those boundaries.  Results that differ by layer—parsed values,
+ * intentional exits, terminating signals—belong to the subpath that produces
+ * them.
+ *
+ * @module
+ * @since 1.3.0
+ */
+/**
+ * Text captured from a program's standard output and standard error streams.
+ *
+ * The two streams are kept apart and their text is preserved exactly, so a
+ * test can assert on trailing newlines and on which stream a message reached.
+ * Each layer documents how it fills these fields: the in-process layers
+ * accumulate the text their injected writers receive, while the subprocess
+ * layer decodes whatever the child actually wrote.
+ *
+ * @since 1.3.0
+ */
+interface CapturedOutput {
+  /**
+   * The text written to standard output.  Empty when nothing was written.
+   */
+  readonly stdout: string;
+  /**
+   * The text written to standard error.  Empty when nothing was written.
+   */
+  readonly stderr: string;
+}
+//#endregion
+export { CapturedOutput };

package/dist/parser.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/parser.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/run.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/run.d.ts

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -0,0 +1,101 @@
+{
+  "name": "@optique/testing",
+  "version": "1.3.0-dev.0",
+  "description": "Testing support for Optique command-line interfaces",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "testing",
+    "subprocess"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/testing/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./cli": {
+      "types": {
+        "import": "./dist/cli.d.ts",
+        "require": "./dist/cli.d.cts"
+      },
+      "import": "./dist/cli.js",
+      "require": "./dist/cli.cjs"
+    },
+    "./discover": {
+      "types": {
+        "import": "./dist/discover.d.ts",
+        "require": "./dist/discover.d.cts"
+      },
+      "import": "./dist/discover.js",
+      "require": "./dist/discover.cjs"
+    },
+    "./parser": {
+      "types": {
+        "import": "./dist/parser.d.ts",
+        "require": "./dist/parser.d.cts"
+      },
+      "import": "./dist/parser.js",
+      "require": "./dist/parser.cjs"
+    },
+    "./run": {
+      "types": {
+        "import": "./dist/run.d.ts",
+        "require": "./dist/run.d.cts"
+      },
+      "import": "./dist/run.js",
+      "require": "./dist/run.cjs"
+    }
+  },
+  "sideEffects": false,
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "node --test",
+    "test:bun": "bun test",
+    "test:deno": "deno test --allow-read",
+    "test-all": "tsdown && node --test && bun test && deno test --allow-read"
+  }
+}