vitest-bats weekly downloads statistics

vitest-bats

A Vitest plugin for testing bash scripts with BATS and collecting 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 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

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

The plugin auto-injects vitest-bats/setup into test.setupFiles. Do not add it manually -- it registers all matchers and a beforeEach builder reset.

1. Add the .sh module type

In tsconfig.json, add vitest-bats to types so TypeScript understands .sh imports:

1. Write Tests

run() returns a BatsResult synchronously. await is harmless but unnecessary -- BatsResult is not thenable.

1. Run Tests

API Reference

BatsPlugin(options?)

Vitest plugin. Add to the plugins array in vitest.config.ts.

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:

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.

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 '' -- $SCRIPT is exported. Not kcov-wrapped. |

exec() is the escape hatch for pipelines and shell expressions:

BatsResult

Returned by run() / exec(). Plain class, not thenable.

result.json() 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 |…