Installation

bashunit ships as a single-file executable. Pick the option that fits your project: install.sh (universal), npm (Node.js projects), Brew (macOS/Linux global), MacPorts, or bashdep.

Requirements

bashunit requires Bash 3.0 or newer. On Windows use WSL.

install.sh

There is a tool that will generate an executable with the whole library in a single file:

Linux/Mac

curl -s https://bashunit.com/install.sh | bash

Windows

# IMPORTANT: You need WSL (Windows Subsystem for Linux) to run bashunit
#
# Step 1: Install WSL if you haven't already
#   - Open PowerShell as Administrator
#   - Run: wsl --install
#   - Restart your computer
#
# Step 2: Open your WSL terminal and run:
curl -s https://bashunit.com/install.sh | bash

This will create a file inside a lib folder, such as lib/bashunit.

Automatic checksum verification

install.sh verifies the download against the release checksum asset by default and aborts on a mismatch, so a tampered or corrupted download never lands. Set BASHUNIT_VERIFY_CHECKSUM=false to opt out (e.g. for old releases published before checksum assets existed). The manual check below is only needed when you opt out.

Verify

# Verify the sha256sum for latest stable: 0.39.1
DIR="lib"; KNOWN_HASH="0cb0153ebcf7198371051332b8e8fce36c47b514eef9bb362148f404837c2e82"; FILE="$DIR/bashunit"; [ "$(shasum -a 256 "$FILE" | awk '{ print $1 }')" = "$KNOWN_HASH" ] && echo -e "✓ \033[1mbashunit\033[0m verified." || { echo -e "✗ \033[1mbashunit\033[0m corrupt"; rm "$FILE"; }

TIP

You can find the checksum for each version inside GitHub's releases. E.g.:

https://github.com/TypedDevs/bashunit/releases/download/0.39.1/checksum

Define custom tag and folder

The installation script can receive arguments (in any order):

Linux/Mac

curl -s https://bashunit.com/install.sh | bash -s [dir] [version]

Windows

# IMPORTANT: You need WSL (Windows Subsystem for Linux) to run bashunit
#
# Step 1: Install WSL if you haven't already
#   - Open PowerShell as Administrator
#   - Run: wsl --install
#   - Restart your computer
#
# Step 2: Open your WSL terminal and run:
curl -s https://bashunit.com/install.sh | bash -s [dir] [version]

• [dir]: the destiny directory to save the executable bashunit; lib by default
• [version]: the release to download, for instance 0.39.1; latest by default.

TIP

You can use beta as [version] to get the next non-stable preview release. We try to keep it stable, but there is no promise that we won't change functions or their signatures without prior notice.

TIP

Committing (or not) this file to your project it's up to you. In the end, it is a dev dependency.

npm

bashunit on npm is the recommended option for Node.js projects.

Per-project (recommended)

# Install as dev dependency
npm install --save-dev bashunit

# Run via npx (resolves node_modules/.bin/bashunit)
npx bashunit tests/

Global

# Install on PATH
npm install -g bashunit

# Run directly, no npx needed
bashunit tests/

One-shot

# No install, runs the latest release
npx bashunit@latest tests/

Per-project: package.json script

Only relevant for the per-project install (global and one-shot don't touch package.json). Define a script so contributors and CI share one command:

{
  "scripts": {
    "test": "bashunit tests/"
  },
  "devDependencies": {
    "bashunit": "^0.39.1"
  }
}

Then run:

npm test
# or any custom script name
npm run <script-name>

Windows (native) not supported

The npm package declares "os": ["darwin", "linux"], so npm install bashunit on native Windows (PowerShell / cmd) fails with EBADPLATFORM:

npm error code EBADPLATFORM
npm error notsup Unsupported platform for bashunit@x.y.z: wanted {"os":"darwin,linux"} (current: {"os":"win32"})

Fix: install WSL and run npm install --save-dev bashunit inside the WSL shell. Alternatively use the install.sh route from WSL.

WARNING

The npm package only ships the prebuilt single-file binary (no src/ tree). You cannot source internals from node_modules/bashunit/ - use the bashunit command. To vendor or extend the framework, use install.sh or clone the repository.

Brew

You can install bashunit globally on macOS or Linux using brew.

brew install bashunit

MacPorts

On macOS, you can also install bashunit via MacPorts:

sudo port install bashunit

bashdep

You can manage your dependencies using bashdep, a simple dependency manager for bash.

Linux/Mac - install-dependencies.sh

# Ensure bashdep is installed
[ ! -f lib/bashdep ] && {
  mkdir -p lib
  curl -sLo lib/bashdep \
    https://github.com/Chemaclass/bashdep/releases/download/0.1/bashdep
  chmod +x lib/bashdep
}

# Add latest bashunit release to your dependencies
DEPENDENCIES=(
  "https://github.com/TypedDevs/bashunit/releases/download/0.39.1/bashunit"
)

# Load, configure and run bashdep
source lib/bashdep
bashdep::setup dir="lib" silent=false
bashdep::install "${DEPENDENCIES[@]}"

Windows - install-dependencies.sh

# IMPORTANT: You need WSL (Windows Subsystem for Linux) to run bashunit
#
# Step 1: Install WSL if you haven't already
#   - Open PowerShell as Administrator
#   - Run: wsl --install
#   - Restart your computer
#
# Step 2: Open your WSL terminal and run:

# Ensure bashdep is installed
[ ! -f lib/bashdep ] && {
  mkdir -p lib
  curl -sLo lib/bashdep \
    https://github.com/Chemaclass/bashdep/releases/download/0.1/bashdep
  chmod +x lib/bashdep
}

# Add latest bashunit release to your dependencies
DEPENDENCIES=(
  "https://github.com/TypedDevs/bashunit/releases/download/0.39.1/bashunit"
)

# Load, configure and run bashdep
source lib/bashdep
bashdep::setup dir="lib" silent=false
bashdep::install "${DEPENDENCIES[@]}"

Output

Downloading 'bashunit' to 'lib'...
> bashunit installed successfully in 'lib'

GitHub Actions

The official TypedDevs/bashunit action installs the binary in one step. Pin it to the floating major tag @v0 to track the latest release within a major, or to a commit SHA for an immutable, supply-chain-safe install (keeps static analyzers such as zizmor happy):

via action

# .github/workflows/bashunit-tests.yml
name: Tests
on: [pull_request, push]
jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      # @v0 tracks the latest release within the v0 major.
      # For an immutable pin use a commit SHA: TypedDevs/bashunit@<sha> # 0.39.1
      - uses: TypedDevs/bashunit@v0
        with:
          version: '0.39.1' # or "latest" (default)
          directory: lib               # optional, "lib" by default
          add-to-path: 'true'          # optional, "true" by default
          verify-checksum: 'true'      # optional, "true" by default
      # add-to-path puts the binary on $PATH, so just call "bashunit":
      - run: bashunit tests

install + run

# .github/workflows/bashunit-tests.yml
name: Tests
on: [pull_request, push]
jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      # Install and run the suite in a single step via the `args` input.
      - uses: TypedDevs/bashunit@v0
        with:
          version: '0.39.1'
          args: tests/ --strict

via install.sh

# .github/workflows/bashunit-tests.yml
name: Tests
on: [pull_request, push]
jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - run: curl -s https://bashunit.com/install.sh | bash
      - run: ./lib/bashunit tests

via npm

# .github/workflows/bashunit-tests.yml
name: Tests
on: [pull_request, push]
jobs:
  tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with: { node-version: 22 }
      - run: npm ci
      - run: npx bashunit tests/

Inputs: version (default latest), directory (default lib), add-to-path (default true), verify-checksum (default true), args (default empty — when set, runs bashunit <args> after installing). Outputs: path (binary path relative to the workspace), version (installed version).

verify-checksum validates the downloaded binary against the release checksum asset (sha256) and fails the install on any mismatch. Set it to false only when pinning a release published before checksum assets existed.

Keep the SHA pin fresh automatically

A commit-SHA pin is the most secure, but bumping it by hand is tedious. Let a bot do it and keep the # 0.39.1 comment as the human-readable tracker.

Renovate - renovate.json

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],
  "packageRules": [
    {
      "matchManagers": ["github-actions"],
      "matchPackageNames": ["TypedDevs/bashunit"],
      "pinDigests": true
    }
  ]
}

Dependabot - .github/dependabot.yml

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly

Renovate updates the pinned SHA and refreshes the trailing # tag comment in the same PR. Dependabot bumps github-actions pins on the schedule you set.

TIP

See bashunit's own pipeline for a real example: https://github.com/TypedDevs/bashunit/blob/main/.github/workflows/tests.yml

Related

• Quickstart - write and run your first test
• Command line - CLI flags and options
• Configuration - env vars and config files
• Project overview - repo layout and contributor workflow