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

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

// 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:

{
  "compilerOptions": {
    "types": ["vitest-bats"]
  }
}

3. Write Tests

// __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

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.

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:

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…