vitest-bats 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 C. Spencer Beggs
+
+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,415 @@
+# vitest-bats
+
+A [Vitest](https://vitest.dev/) plugin for testing bash scripts with
+[BATS](https://github.com/bats-core/bats-core) and collecting
+[kcov](https://github.com/SimonKagstrom/kcov) coverage, merged into Vitest's
+standard v8 coverage report.
+
+## Features
+
+- **Single plugin setup** -- `BatsPlugin()` handles dependency detection,
+  reporter injection, environment configuration, and matcher registration
+- **Native `.sh` imports** -- `import script from "./hello.sh"` returns a
+  builder. Configure with `env()` / `flags()` / `mock()`, terminate with
+  `run(...args)` or `exec(shellExpr)`.
+- **23 `expect.extend` matchers** -- `toSucceed`, `toContainOutput`,
+  `toHaveJsonValue`, `toMatchSchema`, `toHaveInvoked`, and more.
+  Auto-registered via setup file -- no user setup required.
+- **Schema validation** -- `toMatchSchema` accepts any
+  [Standard Schema](https://github.com/standard-schema/standard-schema)
+  validator (Zod, Valibot, Arktype, Effect Schema). `toMatchJsonSchema`
+  validates raw JSON Schema via Ajv.
+- **Self-contained command mocking** -- `.mock("git", { "remote get-url *":
+  "echo https://example.com" })` embeds shim binaries that record calls and
+  emit pre-recorded responses. No `bats-mock` runtime dependency.
+- **Unified coverage** -- Shell script coverage from kcov is merged into the v8
+  Istanbul CoverageMap and reported alongside TypeScript coverage.
+
+## Installation
+
+```bash
+npm install --save-dev vitest-bats vitest
+```
+
+`vitest-bats` requires `vitest >= 4.1.0` and BATS `>= 1.5` (for the
+`run --separate-stderr` form used to capture stderr separately).
+
+### System Dependencies
+
+These must be installed on the host (or in your Docker container):
+
+| Dependency | Required | Install (macOS) | Install (Linux) |
+| --- | --- | --- | --- |
+| bats (>= 1.5) | Yes | `brew install bats-core` | `apt-get install bats` |
+| bats-support | Yes | `brew install bats-support` | `apt-get install bats-support` |
+| bats-assert | Yes | `brew install bats-assert` | `apt-get install bats-assert` |
+| bats-mock | Yes | `brew install bats-mock` | `apt-get install bats-file` |
+| jq | Yes | `brew install jq` | `apt-get install jq` |
+| kcov | Coverage only | `brew install kcov` | `apt-get install kcov` |
+
+`bats-assert` and `bats-mock` are still detected at startup for compatibility
+warnings; the runtime no longer loads them. Mocks are self-contained, and
+assertions happen in TypeScript via the matchers below.
+
+## Quick Start
+
+### 1. Configure Vitest
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from "vitest/config";
+import { BatsPlugin } from "vitest-bats";
+
+export default defineConfig({
+  plugins: [BatsPlugin()],
+  test: {
+    include: ["__test__/**/*.test.ts"],
+    coverage: {
+      provider: "v8",
+    },
+  },
+});
+```
+
+The plugin auto-injects `vitest-bats/setup` into `test.setupFiles`. Do not
+add it manually -- it registers all matchers and a `beforeEach` builder
+reset.
+
+### 2. Add the `.sh` module type
+
+In `tsconfig.json`, add `vitest-bats` to `types` so TypeScript understands
+`.sh` imports:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["vitest-bats"]
+  }
+}
+```
+
+### 3. Write Tests
+
+```typescript
+// __test__/hello.test.ts
+import { describe, expect, test } from "vitest";
+import hello from "../scripts/hello.sh";
+
+describe("hello.sh", () => {
+  test("outputs default greeting", () => {
+    const result = hello.run();
+    expect(result).toSucceed();
+    expect(result).toContainOutput("Hello World");
+  });
+
+  test("greets by name", () => {
+    const result = hello.run("--name", "Alice");
+    expect(result).toSucceed();
+    expect(result).toContainOutput("Hello Alice");
+  });
+
+  test("outputs JSON with --json flag", () => {
+    const result = hello.run("--json");
+    expect(result).toSucceed();
+    expect(result).toHaveJsonValue("greeting", "Hello World");
+  });
+
+  test("rejects unknown arguments", () => {
+    const result = hello.run("--invalid");
+    expect(result).toFail();
+    expect(result).toContainStderr("Unknown option");
+  });
+});
+```
+
+`run()` returns a `BatsResult` synchronously. `await` is harmless but
+unnecessary -- `BatsResult` is not thenable.
+
+### 4. Run Tests
+
+```bash
+vitest run
+vitest run --coverage  # With coverage (requires kcov on Linux)
+```
+
+## API Reference
+
+### `BatsPlugin(options?)`
+
+Vitest plugin. Add to the `plugins` array in `vitest.config.ts`.
+
+```typescript
+BatsPlugin({
+  coverage: "auto",       // "auto" | true | false (default: "auto")
+  deps: "error",          // "error" | "warn"      (default: "error")
+  logLevel: "errors-only", // "verbose" | "debug" | "errors-only"
+  links: "auto",           // "auto" | "default" | "hte"
+});
+```
+
+Coverage modes:
+
+| Value | Behavior |
+| --- | --- |
+| `"auto"` (default) | Shell coverage on when kcov is available and platform is not macOS |
+| `true` | Require kcov on a non-macOS platform; throw otherwise |
+| `false` | Always exclude shell scripts from coverage |
+
+`deps`:
+
+- `"error"` (default) -- throw on missing required dependencies
+- `"warn"` -- log warnings; pure-TS unit tests still run, integration
+  tests using `.sh` imports fail individually
+
+### Importing Scripts
+
+`.sh` imports return a `ScriptBuilder` instance:
+
+```typescript
+import script from "../scripts/hello.sh";
+// script: ScriptBuilder
+```
+
+The plugin's Vite transform (`resolveId` + `load`) intercepts the import and
+emits a virtual module that constructs a `ScriptBuilder` bound to the
+script's absolute path.
+
+### `ScriptBuilder`
+
+Configuration methods accumulate state and return `this` for chaining.
+Termination methods (`run` / `exec`) consume the state, execute the script,
+and return a `BatsResult`. Builder state is reset after every termination
+(via a `finally` block) and again before each test (via the auto-injected
+`beforeEach`).
+
+#### Configuration
+
+| Method | Purpose |
+| --- | --- |
+| `env(vars)` | Set environment variables for the next run. Multiple calls accumulate. |
+| `flags(value)` | Append a fixed flag string to the script invocation. Replaces prior `flags()`. |
+| `mock(cmd, responses?)` | Register a recorder shim for `cmd`. Patterns map to bash response expressions. |
+
+`mock()` patterns are converted to bash globs: literal segments are
+double-quoted while `* ? [ ]` stay active. Responses are evaluated by `eval`
+so they can include any bash expression.
+
+```typescript
+const result = script
+  .env({ NAME: "Alice" })
+  .flags("--upper")
+  .mock("git", { "remote get-url *": "echo https://example.com" })
+  .run();
+```
+
+If no pattern matches at runtime, the shim emits an error to stderr and
+exits 1. Mocks accumulate across `mock()` calls; passing an empty
+`responses` map records calls without producing output.
+
+#### Termination
+
+| Method | Generated invocation |
+| --- | --- |
+| `run(...args)` | `"$SCRIPT" arg0 arg1 ...` (kcov-wrapped when coverage is on) |
+| `exec(shellExpr)` | `bash -c '<expr>'` -- `$SCRIPT` is exported. Not kcov-wrapped. |
+
+`exec()` is the escape hatch for pipelines and shell expressions:
+
+```typescript
+const result = script.exec('"$SCRIPT" --name Pipeline | tr a-z A-Z');
+```
+
+### `BatsResult`
+
+Returned by `run()` / `exec()`. Plain class, not thenable.
+
+```typescript
+class BatsResult {
+  readonly status: number;
+  readonly output: string;
+  readonly stderr: string;
+  readonly lines: string[];          // output split on "\n"
+  readonly stderr_lines: string[];   // stderr split on "\n"
+  readonly calls: Record<string, MockCall[]>;
+  json<T = unknown>(): T;            // Lazy parse, cached
+}
+```
+
+`result.json<T>()` lazily parses `output` as JSON, caching the value on
+first call. Throws with a descriptive message if the output is not valid
+JSON.
+
+### Matchers
+
+23 matchers are registered automatically. All operate on a `BatsResult`.
+
+#### Status
+
+| Matcher | Asserts |
+| --- | --- |
+| `toSucceed()` | `status === 0` |
+| `toFail(code?)` | `status !== 0` (or `status === code` if given) |
+
+#### Output (stdout)
+
+| Matcher | Asserts |
+| --- | --- |
+| `toHaveOutput(text)` | `output === text` |
+| `toContainOutput(text)` | `output.includes(text)` |
+| `toMatchOutput(pattern)` | RegExp test against `output` |
+| `toHaveEmptyOutput()` | `output === ""` |
+
+#### Stderr
+
+| Matcher | Asserts |
+| --- | --- |
+| `toHaveStderr(text)` | `stderr === text` |
+| `toContainStderr(text)` | `stderr.includes(text)` |
+| `toMatchStderr(pattern)` | RegExp test against `stderr` |
+
+#### Lines
+
+| Matcher | Asserts |
+| --- | --- |
+| `toHaveLine(index, text)` | `lines[index] === text` |
+| `toHaveLineContaining(text, index?)` | Line at `index` contains `text`, or any line if index omitted |
+| `toHaveLineMatching(pattern, index?)` | Same shape, RegExp |
+| `toHaveLineCount(n)` | `lines.length === n` |
+
+#### JSON
+
+| Matcher | Asserts |
+| --- | --- |
+| `toOutputJson()` | `result.json()` doesn't throw |
+| `toEqualJson(expected)` | Parsed JSON deep-equals `expected` |
+| `toMatchJson(partial)` | `partial` is a deep subset of parsed JSON |
+| `toHaveJsonValue(path, expected)` | Path exists and deep-equals `expected` |
+| `toHaveJsonPath(path)` | Path exists |
+
+Path syntax: dots for keys, brackets for array indices
+(e.g., `"users[0].name"`).
+
+#### Schema
+
+| Matcher | Asserts |
+| --- | --- |
+| `toMatchSchema(schema)` | Standard Schema OR raw JSON Schema validates the parsed JSON |
+| `toMatchJsonSchema(schema)` | Raw JSON Schema validates the parsed JSON |
+
+`toMatchSchema` auto-detects Standard Schema (Zod, Valibot, Arktype, Effect
+Schema) by the `~standard` property and falls through to Ajv for plain
+objects. Compiled validators are cached.
+
+```typescript
+import { z } from "zod";
+
+const HookSchema = z.object({
+  decision: z.enum(["approve", "block"]),
+  reason: z.string(),
+});
+
+test("hook.sh emits a valid response", () => {
+  const result = hook.run();
+  expect(result).toSucceed();
+  expect(result).toMatchSchema(HookSchema);
+});
+```
+
+#### Invocation (mock calls)
+
+| Matcher | Asserts |
+| --- | --- |
+| `toHaveInvoked(cmd, opts?)` | `cmd` was invoked at least once; if `opts.args` given, at least one call matches |
+| `toHaveInvokedTimes(cmd, n)` | `result.calls[cmd].length === n` |
+| `toHaveInvokedExactly(cmd, calls)` | `result.calls[cmd]` deep-equals the given list (order-sensitive) |
+
+```typescript
+const result = widget
+  .mock("widget-cli", {
+    init: "echo initialized",
+    "build --target=*": "echo built",
+    "ship *": "echo shipped",
+  })
+  .run();
+
+expect(result).toHaveInvokedTimes("widget-cli", 3);
+expect(result).toHaveInvokedExactly("widget-cli", [
+  { args: ["init"] },
+  { args: ["build", "--target=foo"] },
+  { args: ["ship", "release with spaces"] },
+]);
+```
+
+Strict-count matchers can be flaky when kcov instrumentation invokes
+binaries you have mocked (e.g., `git rev-parse`). For reliable
+strict-count assertions, mock binaries kcov never touches.
+
+## Coverage
+
+### How It Works
+
+1. Vitest runs TypeScript test files.
+2. Each `script.run(...)` call generates a self-contained `.bats` file in a
+   per-pid temp dir and executes it via `bats --tap`.
+3. When coverage is enabled and kcov is available, the generated `.bats`
+   wraps `"$SCRIPT"` with kcov.
+4. `BatsCoverageReporter.onCoverage()` parses each script's
+   `cobertura.xml`, converts to Istanbul format, and merges into the v8
+   CoverageMap.
+5. Vitest reports unified coverage (TypeScript + shell scripts).
+
+### Platform Support
+
+| Platform | Tests | Coverage |
+| --- | --- | --- |
+| Linux | Full support | Full support |
+| macOS | Full support | Not supported (SIP blocks ptrace) |
+| Docker on macOS | Full support | Full support |
+
+When kcov is unavailable, the reporter still emits coverage entries for
+every `.sh` script registered during the Vite transform: synthetic at the
+configured threshold percentage when thresholds are set, otherwise
+zero-coverage from source-line analysis. Shell scripts therefore always
+appear in the coverage table, even on macOS.
+
+## Entry Points
+
+| Path | Purpose |
+| --- | --- |
+| `vitest-bats` | `BatsPlugin`, `BatsCoverageReporter`, `ScriptBuilder`, `BatsResult`, `batsMatchers`, types |
+| `vitest-bats/runtime` | `ScriptBuilder`, `BatsResult`, `resetAllBuilders`. Imported by virtual `.sh` modules. |
+| `vitest-bats/setup` | Auto-injected setup file. Registers matchers and the `beforeEach` reset hook. |
+
+The previous `vitest-bats/runner` entry has been removed -- execution now
+happens inline inside `ScriptBuilder.run/exec`.
+
+## Troubleshooting
+
+### Coverage Shows 0% on macOS
+
+Expected. kcov cannot instrument bash scripts on macOS due to SIP. Use the
+included Docker setup, the dev container, or run in CI on Linux.
+
+### "Missing required dependencies" Error
+
+`BatsPlugin` checks for system dependencies at startup. Install the missing
+tools listed in the error message, or pass `deps: "warn"` to allow pure-TS
+tests to run.
+
+### "BATS version 1.4 is too old"
+
+`run --separate-stderr` requires BATS 1.5+. Upgrade your BATS install.
+
+## Related
+
+- [Vitest](https://vitest.dev/) -- Test framework
+- [BATS](https://github.com/bats-core/bats-core) -- Bash Automated Testing
+  System
+- [kcov](https://github.com/SimonKagstrom/kcov) -- Code coverage for shell
+  scripts
+- [Standard Schema](https://github.com/standard-schema/standard-schema) --
+  Schema validator interoperability spec
+
+## License
+
+[MIT](LICENSE)

package/bats-executor.js

@@ -0,0 +1,103 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+
+//#region src/bats-executor.ts
+let cleanupRegistered = false;
+let batsFileDirCache = null;
+function getBatsFileDir() {
+	if (batsFileDirCache) return batsFileDirCache;
+	const dir = join(tmpdir(), `vitest-bats-${process.pid}`);
+	mkdirSync(dir, { recursive: true });
+	batsFileDirCache = dir;
+	if (!cleanupRegistered) {
+		cleanupRegistered = true;
+		process.on("exit", () => {
+			try {
+				if (batsFileDirCache) rmSync(batsFileDirCache, {
+					recursive: true,
+					force: true
+				});
+			} catch {}
+		});
+	}
+	return dir;
+}
+function decodeB64(b64) {
+	return Buffer.from(b64, "base64").toString("utf-8");
+}
+/**
+* Parses the base64-encoded result payload written by the generated BATS test file.
+* @internal
+*/
+function parseExecutionResult(recorderDir) {
+	const resultPath = join(recorderDir, "result.txt");
+	if (!existsSync(resultPath)) throw new Error(`vitest-bats: expected result file not found at ${resultPath}. BATS likely crashed before the test body completed.`);
+	const raw = readFileSync(resultPath, "utf-8");
+	let status = null;
+	let outputB64 = null;
+	let stderrB64 = null;
+	for (const line of raw.split("\n")) if (line.startsWith("status:")) {
+		const n = Number(line.slice(7));
+		if (!Number.isNaN(n)) status = n;
+	} else if (line.startsWith("output_b64:")) outputB64 = line.slice(11);
+	else if (line.startsWith("stderr_b64:")) stderrB64 = line.slice(11);
+	if (status === null) throw new Error(`vitest-bats: malformed result file at ${resultPath}: missing 'status:' line. Contents:\n${raw}`);
+	if (outputB64 === null || stderrB64 === null) throw new Error(`vitest-bats: malformed result file at ${resultPath}: missing output_b64 or stderr_b64. Contents:\n${raw}`);
+	const calls = {};
+	const callsPath = join(recorderDir, "calls.jsonl");
+	if (existsSync(callsPath)) {
+		const callsRaw = readFileSync(callsPath, "utf-8");
+		for (const [i, line] of callsRaw.split("\n").entries()) {
+			if (line.trim() === "") continue;
+			let parsed;
+			try {
+				parsed = JSON.parse(line);
+			} catch (err) {
+				const msg = err instanceof Error ? err.message : String(err);
+				throw new Error(`vitest-bats: failed to parse calls.jsonl line ${i + 1}: ${msg}\n  line: ${line}`);
+			}
+			if (!parsed || typeof parsed !== "object" || !("cmd" in parsed) || !("args" in parsed)) throw new Error(`vitest-bats: calls.jsonl line ${i + 1} missing cmd or args: ${line}`);
+			const { cmd, args } = parsed;
+			if (typeof cmd !== "string" || !Array.isArray(args)) throw new Error(`vitest-bats: calls.jsonl line ${i + 1} has wrong types: ${line}`);
+			const argsStr = args.map(String);
+			if (!calls[cmd]) calls[cmd] = [];
+			calls[cmd].push({ args: argsStr });
+		}
+	}
+	return {
+		status,
+		output: decodeB64(outputB64),
+		stderr: decodeB64(stderrB64),
+		calls
+	};
+}
+/**
+* Spawns `bats` against a generated `.bats` file and parses the recorded result.
+* @internal
+*/
+function executeBats(opts) {
+	mkdirSync(opts.recorderDir, { recursive: true });
+	const batsFileDir = getBatsFileDir();
+	const batsFile = resolve(batsFileDir, `${Date.now()}-${Math.random().toString(36).slice(2)}.bats`);
+	writeFileSync(batsFile, opts.batsContent, { mode: 493 });
+	const result = spawnSync(opts.batsPath, ["--tap", batsFile], {
+		encoding: "utf-8",
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		timeout: opts.timeoutMs ?? 6e4,
+		env: {
+			...process.env,
+			VBATS_RECORDER: opts.recorderDir
+		}
+	});
+	if (result.error) throw new Error(`vitest-bats: failed to spawn bats at ${opts.batsPath}: ${result.error.message}`);
+	return parseExecutionResult(opts.recorderDir);
+}
+
+//#endregion
+export { executeBats, parseExecutionResult };

package/bats-generator.js

@@ -0,0 +1,114 @@
+import { dirname } from "node:path";
+
+//#region src/bats-generator.ts
+function shellQuote(s) {
+	return `"${s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+}
+function singleQuoteForBash(s) {
+	return `'${s.replace(/'/g, `'"'"'`)}'`;
+}
+function patternToBashGlob(pattern) {
+	let result = "";
+	let inLiteral = false;
+	for (const ch of pattern) if (ch === "*" || ch === "?" || ch === "[" || ch === "]") {
+		if (inLiteral) {
+			result += "\"";
+			inLiteral = false;
+		}
+		result += ch;
+	} else {
+		if (!inLiteral) {
+			result += "\"";
+			inLiteral = true;
+		}
+		if (ch === "\\" || ch === "\"" || ch === "$" || ch === "`") result += `\\${ch}`;
+		else result += ch;
+	}
+	if (inLiteral) result += "\"";
+	return result;
+}
+function buildRecorderShim(stub, indent) {
+	const lines = [
+		`${indent}cat > "$VBATS_RECORDER/bin/${stub.cmd}" <<__VBATS_EOF__`,
+		`#!/usr/bin/env bash`,
+		`jq -nc --arg cmd "${stub.cmd}" --args '{cmd: \\$cmd, args: \\$ARGS.positional}' -- "\\$@" \\\\`,
+		`  >> "$VBATS_RECORDER/calls.jsonl"`
+	];
+	const entries = Object.entries(stub.responses);
+	if (entries.length === 0) lines.push(`exit 0`);
+	else {
+		const arms = entries.map(([pattern, response], i) => {
+			return [
+				`${i === 0 ? "if" : "elif"} [[ "\\$*" == ${patternToBashGlob(pattern)} ]]; then`,
+				`    eval ${singleQuoteForBash(response)}`,
+				`    exit \\$?`
+			];
+		});
+		for (const arm of arms) for (const line of arm) lines.push(line);
+		lines.push(`else`);
+		lines.push(`    echo "vitest-bats: no mock pattern matched for '${stub.cmd} \\$*'" >&2`);
+		lines.push(`    exit 1`);
+		lines.push(`fi`);
+	}
+	lines.push(`__VBATS_EOF__`);
+	lines.push(`${indent}chmod +x "$VBATS_RECORDER/bin/${stub.cmd}"`);
+	return lines;
+}
+function buildRunCommand(scriptPath, args, flags, mode, kcov) {
+	const wrapWithKcov = (target) => {
+		if (!kcov) return target;
+		const includePattern = dirname(scriptPath);
+		return [
+			shellQuote(kcov.kcovPath),
+			"--skip-solibs",
+			`--include-pattern=${singleQuoteForBash(includePattern)}`,
+			`--exclude-line="^#!/,^set -euo pipefail,^set -eo pipefail"`,
+			`"$KCOV_OUT"`,
+			target
+		].join(" ");
+	};
+	if (mode.kind === "shell") return `bash -c ${singleQuoteForBash(mode.expression)}`;
+	const quotedArgs = args.map(shellQuote).join(" ");
+	const flagsSuffix = flags ? ` ${flags}` : "";
+	return wrapWithKcov(`"$SCRIPT"${quotedArgs ? ` ${quotedArgs}` : ""}${flagsSuffix}`);
+}
+/**
+* Renders a `.bats` file body for a single `ScriptBuilder` invocation: setup (deps,
+* env, recorder, mock shims, kcov), the `run` command, and the base64 result capture.
+* @internal
+*/
+function generateBatsFile(input) {
+	const { scriptPath, args, env, flags, stubs, recorderDir, deps, mode, kcov } = input;
+	const lines = [];
+	lines.push(`#!${deps.batsPath}`);
+	lines.push("");
+	lines.push("setup() {");
+	lines.push(`    load '${deps.batsSupportPath}/load.bash'`);
+	lines.push(`    export SCRIPT=${singleQuoteForBash(scriptPath)}`);
+	lines.push(`    export VBATS_RECORDER=${singleQuoteForBash(recorderDir)}`);
+	lines.push("    mkdir -p \"$VBATS_RECORDER/bin\"");
+	if (kcov) {
+		lines.push(`    export KCOV_OUT=${singleQuoteForBash(kcov.outputDir)}`);
+		lines.push("    mkdir -p \"$KCOV_OUT\"");
+	}
+	for (const stub of stubs) for (const shimLine of buildRecorderShim(stub, "    ")) lines.push(shimLine);
+	if (stubs.length > 0) lines.push("    PATH=\"$VBATS_RECORDER/bin:$PATH\"");
+	lines.push("}");
+	lines.push("");
+	lines.push(`@test "_run_" {`);
+	const envEntries = Object.entries(env);
+	const envPrefix = envEntries.length > 0 ? `${envEntries.map(([k, v]) => `${k}=${shellQuote(v)}`).join(" ")} ` : "";
+	const target = buildRunCommand(scriptPath, args, flags, mode, kcov);
+	lines.push(`    ${envPrefix}run --separate-stderr ${target}`);
+	lines.push("    {");
+	lines.push("        echo \"status:$status\"");
+	lines.push("        echo \"output_b64:$(printf '%s' \"$output\" | base64 | tr -d '\\n')\"");
+	lines.push("        echo \"stderr_b64:$(printf '%s' \"$stderr\" | base64 | tr -d '\\n')\"");
+	lines.push("    } > \"$VBATS_RECORDER/result.txt\"");
+	lines.push("}");
+	lines.push("");
+	return lines.join("\n");
+}
+
+//#endregion
+export { generateBatsFile };