### Start Bashunit Interactive Learning Tutorial

Source: https://github.com/typeddevs/bashunit/blob/main/docs/command-line.md

Use the 'learn' command to launch an interactive tutorial with 10 progressive lessons designed for new users to get started with bashunit.

```bash
bashunit learn
```

--------------------------------

### Install and Run BashUnit in One Step via Action

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Execute BashUnit tests directly within the GitHub Action setup using the `args` input. This combines installation and execution into a single action step.

```yaml
# .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: '{{ pkg.version }}'
          args: tests/ --strict
```

--------------------------------

### Preview Documentation Locally

Source: https://github.com/typeddevs/bashunit/blob/main/docs/project-overview.md

Locally preview documentation changes by navigating to the docs directory, installing dependencies, and starting the development server.

```bash
cd docs
npm ci
npm run dev
```

--------------------------------

### Bashunit Configuration File Example

Source: https://github.com/typeddevs/bashunit/blob/main/docs/configuration.md

Configure bashunit behavior by setting key-value pairs in a .bashunitrc file. Blank lines and comments starting with '#' are ignored.

```bash
# .bashunitrc
BASHUNIT_SHOW_HEADER=false
BASHUNIT_PARALLEL_RUN=true
BASHUNIT_PROFILE=true
```

--------------------------------

### Run Bashunit Example Tests

Source: https://github.com/typeddevs/bashunit/blob/main/example/README.md

Execute this command from the project root to run the tests included in the example directory.

```bash
./bashunit example
```

--------------------------------

### Output for data provider example

Source: https://github.com/typeddevs/bashunit/blob/main/docs/blog/2024-09-01-release-0-15.md

Example output demonstrating successful test runs with data providers supplying multiple arguments.

```bash
Running example_test.sh
✓ Passed: Directory exists (outro /usr)
✓ Passed: Directory exists (outro /etc)
✓ Passed: Directory exists (outro /var)
```

--------------------------------

### Install Bashunit with curl

Source: https://github.com/typeddevs/bashunit/blob/main/docs/quickstart.md

Installs bashunit by downloading and executing an install script. This method generates a single-file executable in the lib/bashunit directory.

```bash
# Generates lib/bashunit (single-file executable)
curl -s https://bashunit.com/install.sh | bash
```

--------------------------------

### Install BashUnit via install.sh Script

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Install BashUnit by downloading and executing the `install.sh` script directly. This method places the binary in the `./lib/bashunit` path.

```yaml
# .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
```

--------------------------------

### Install Bashunit with GitHub Action

Source: https://github.com/typeddevs/bashunit/blob/main/docs/blog/2026-06-07-release-0-38.md

Use this composite action in your CI workflows to install bashunit. It can be pinned by commit SHA for reproducible builds and allows specifying the installation directory and version.

```yaml
- uses: TypedDevs/bashunit@<commit-sha>
  with:
    version: '0.38.0'      # optional, defaults to the version pinned at the ref
    directory: 'lib'       # where to install
    add-to-path: 'true'    # expose `bashunit` on PATH
    verify-checksum: 'true'
- run: bashunit tests/
```

--------------------------------

### Install Bashunit on Windows with WSL

Source: https://github.com/typeddevs/bashunit/blob/main/docs/quickstart.md

Installs bashunit on Windows using the Windows Subsystem for Linux (WSL). Ensure WSL is installed first, then run the install script within the WSL terminal.

```bash
# 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
```

--------------------------------

### Write a Bashunit Test

Source: https://github.com/typeddevs/bashunit/blob/main/README.md

Example of a simple bashunit test file demonstrating the assert_same assertion.

```bash
#!/usr/bin/env bash

function test_bashunit_is_working() {
  assert_same "bashunit is working" "bashunit is working"
}
```

--------------------------------

### Install Bashunit Per-Project with npm

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Install Bashunit as a development dependency for your project. This is the recommended approach for Node.js projects. Use 'npx' to run the installed binary.

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

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

--------------------------------

### Display Bashunit Help Message

Source: https://github.com/typeddevs/bashunit/blob/main/docs/command-line.md

This command displays the main help message, listing all available commands and global options. It also guides on how to get command-specific help.

```bash
bashunit --help
```

--------------------------------

### Install BashUnit with Custom Directory and Version (Linux/Mac)

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Customize the installation by specifying a destination directory and a specific version of BashUnit to download on Linux or macOS.

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

--------------------------------

### Setup and Teardown with set_up/tear_down

Source: https://github.com/typeddevs/bashunit/blob/main/docs/common-patterns.md

Use `set_up` to prepare the test environment before each test and `tear_down` to clean up afterward. Ensure necessary scripts are sourced within `set_up`.

```bash
#!/usr/bin/env bash

function set_up() {
  # Runs before each test
  export TEST_DB="/tmp/test_db_$$"
  mkdir -p "$TEST_DB"
  source "src/database.sh"
}

function tear_down() {
  # Runs after each test
  rm -rf "$TEST_DB"
}

function test_create_table() {
  create_table "users"
  assert_file_exists "$TEST_DB/users.txt"
}

function test_insert_record() {
  create_table "users"
  insert_record "users" "john@example.com"

  assert_file_contains "john@example.com" "$TEST_DB/users.txt"
}
```

--------------------------------

### Install Bashunit

Source: https://github.com/typeddevs/bashunit/blob/main/README.md

Installs the latest version of bashunit into your project using curl.

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

--------------------------------

### One-time Setup/Teardown with set_up_before_script/tear_down_after_script

Source: https://github.com/typeddevs/bashunit/blob/main/docs/common-patterns.md

Employ `set_up_before_script` for expensive, one-time setup operations before any tests in the file run, and `tear_down_after_script` for cleanup after all tests. Remember to manage background processes and their PIDs.

```bash
#!/usr/bin/env bash

function set_up_before_script() {
  # Runs once before all tests in this file
  export TEST_SERVER_PID
  ./scripts/start_test_server.sh &
  TEST_SERVER_PID=$!
  sleep 2  # Wait for server to start
}

function tear_down_after_script() {
  # Runs once after all tests in this file
  kill "$TEST_SERVER_PID" 2>/dev/null || true
}

function test_server_responds_to_ping() {
  assert_successful_code "curl -s http://localhost:8080/ping"
}

function test_server_returns_json() {
  local response
  response=$(curl -s http://localhost:8080/api/data)

  assert_contains '"status":"ok"' "$response"
}
```

--------------------------------

### Install BashUnit with Custom Directory and Version (Windows/WSL)

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Customize the installation by specifying a destination directory and a specific version of BashUnit to download within your WSL environment on Windows.

```bash
# 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]
```

--------------------------------

### Install Bashunit Dependencies on Windows using bashdep (WSL)

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Provides instructions for installing bashunit dependencies on Windows using bashdep within a WSL environment. It includes steps to install WSL and then proceeds with dependency management similar to Linux/Mac.

```bash
# 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/{{ pkg.version }}/bashunit"
)

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

--------------------------------

### Test Individual Bash Functions

Source: https://github.com/typeddevs/bashunit/blob/main/docs/common-patterns.md

Source your script and test each function individually. Ensure setup logic is in a `set_up` function.

```bash
#!/usr/bin/env bash

function add() {
  echo $(($1 + $2))
}

function multiply() {
  echo $(($1 * $2))
}
```

```bash
#!/usr/bin/env bash

function set_up() {
  source "src/calculator.sh"
}

function test_add_two_positive_numbers() {
  assert_same "5" "$(add 2 3)"
}

function test_add_negative_numbers() {
  assert_same "-5" "$(add -2 -3)"
}

function test_multiply() {
  assert_same "6" "$(multiply 2 3)"
}
```

--------------------------------

### Isolate Code Under Test (Good Practice)

Source: https://github.com/typeddevs/bashunit/blob/main/docs/benchmarks.md

Minimize setup code within the benchmark function itself. Initialize necessary data or state in a separate setup function to ensure only the target code is measured.

```bash
function set_up() {
  TEST_DATA=$(generate_large_dataset)
}

# @revs=100 @its=5
function bench_process_data() {
  process "$TEST_DATA"
}
```

--------------------------------

### Test Directory Structure Example

Source: https://github.com/typeddevs/bashunit/blob/main/docs/common-patterns.md

Organize your tests into logical groups such as unit, integration, and functional tests. Helper scripts can be placed in a dedicated directory.

```bash
tests/
├── unit/
│   ├── parser_test.sh
│   ├── validator_test.sh
│   └── formatter_test.sh
├── integration/
│   ├── api_test.sh
│   └── database_test.sh
├── functional/
│   ├── user_workflow_test.sh
│   └── admin_workflow_test.sh
└── helpers/
    └── test_helpers.sh
```

--------------------------------

### Source File Example: math.sh

Source: https://github.com/typeddevs/bashunit/blob/main/docs/coverage.md

A sample bash script used to demonstrate LCOV coverage calculation, highlighting executable and non-executable lines.

```bash
#!/usr/bin/env bash           # Line 1 - not executable (comment/shebang)
function add() {              # Line 2 - not executable (function declaration)
  echo $(($1 + $2))           # Line 3 - executable
}                             # Line 4 - not executable (closing brace)
function multiply() {         # Line 5 - not executable (function declaration)
  echo $(($1 * $2))           # Line 6 - executable
}                             # Line 7 - not executable (closing brace)
```

--------------------------------

### Bashdep Installation Output

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

This is the expected output message after successfully installing bashunit using bashdep.

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

--------------------------------

### Set Up Before All Tests

Source: https://github.com/typeddevs/bashunit/blob/main/docs/test-files.md

The `set_up_before_script` function is called once before all test functions in a file. It's useful for global setup like loading shared resources. Failures halt the script immediately.

```bash
function set_up_before_script() {
  open_database_connection
}
```

--------------------------------

### Chaining Multiple Assertions Example

Source: https://github.com/typeddevs/bashunit/blob/main/docs/standalone.md

An example demonstrating how to chain multiple assertions like exit code, content presence, and line count on a script's output. This is equivalent to running individual assertions sequentially.

```bash
./bashunit assert "./my_script.sh" \
  exit_code "0" \
  contains "success" \
  not_contains "error" \
  line_count "5"
```

```bash
OUTPUT=$(./bashunit assert exit_code "0" "./my_script.sh")
./bashunit assert contains "success" "$OUTPUT"
./bashunit assert not_contains "error" "$OUTPUT"
./bashunit assert line_count "5" "$OUTPUT"
```

--------------------------------

### LCOV File Structure Example

Source: https://github.com/typeddevs/bashunit/blob/main/docs/coverage.md

A basic example of the LCOV file format, showing the standard fields for source file and line data.

```lcov
TN:
SF:/path/to/source/file.sh
DA:2,5
DA:3,0
LF:2
LH:1
end_of_record
```

--------------------------------

### Install Bashunit with Homebrew

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Installs bashunit globally on macOS or Linux using the Homebrew package manager.

```bash
brew install bashunit
```

--------------------------------

### Verify Installer Checksum with Bash

Source: https://github.com/typeddevs/bashunit/blob/main/docs/blog/2026-06-07-release-0-38.md

Enable checksum verification for the bashunit installer script by setting the BASHUNIT_VERIFY_CHECKSUM environment variable to true before executing the install script. This ensures the integrity of the downloaded binary.

```bash
BASHUNIT_VERIFY_CHECKSUM=true bash <(curl -s https://bashunit.com/install.sh)
```

--------------------------------

### Install BashUnit via GitHub Action

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Use the official TypedDevs/bashunit action to install the binary. Pin to `@v0` for the latest minor release or a commit SHA for immutability. Configure optional inputs like `version`, `directory`, `add-to-path`, and `verify-checksum`.

```yaml
# .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> # {{ pkg.version }}
      - uses: TypedDevs/bashunit@v0
        with:
          version: '{{ pkg.version }}' # 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
```

--------------------------------

### Code Coverage Output Example

Source: https://github.com/typeddevs/bashunit/blob/main/docs/coverage.md

This output shows the test results and a detailed code coverage report, including lines hit and percentage for each file.

```bash
bashunit - 0.37.0 | Tests: 5
.....

Tests:      5 passed, 5 total
Assertions: 12 passed, 12 total

All tests passed
Time taken: 1 s

Coverage Report
ᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥᎥI'm a large language model, trained by Google. I am a conversational AI that can generate human-like text in response to a wide range of prompts and questions. For example, I can provide summaries of factual topics or create stories. 
```

--------------------------------

### Install Bashunit Globally with npm

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Install Bashunit globally on your system's PATH. This allows you to run the 'bashunit' command directly without needing 'npx'.

```bash
# Install on PATH
npm install -g bashunit

# Run directly, no npx needed
bashunit tests/
```

--------------------------------

### Install BashUnit via npm

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Install BashUnit using npm after setting up Node.js. This approach integrates BashUnit into your Node.js project's development workflow.

```yaml
# .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/
```

--------------------------------

### Verify BashUnit Installation

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

After installation, verify the integrity of the downloaded bashunit executable using its SHA256 checksum. This ensures the file is not corrupted or tampered with.

```bash-vue
# Verify the sha256sum for latest stable: {{ pkg.version }}
DIR="lib"; KNOWN_HASH="{{pkg.checksum}}"; 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"; }
```

--------------------------------

### One-Shot Bashunit Installation with npm

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Run the latest release of Bashunit without installing it. This is useful for quick tests or when you don't want to add it to your project's dependencies.

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

--------------------------------

### Console Coverage Report Example

Source: https://github.com/typeddevs/bashunit/blob/main/docs/coverage.md

Displays file-wise coverage with color coding indicating performance against thresholds. Useful for a quick overview of test coverage.

```bash
Coverage Report
---------------
src/math.sh                       10/ 12 lines ( 83%)  # Green (>= 80%)
src/parser.sh                      7/ 10 lines ( 70%)  # Yellow (50-79%)
src/legacy.sh                      2/ 15 lines ( 13%)  # Red (< 50%)
---------------
Total: 19/37 (51%)
```

--------------------------------

### Monitor Lifecycle Hook Performance

Source: https://github.com/typeddevs/bashunit/blob/main/docs/blog/2025-12-19-release-0-31.md

Observe the execution time of setup and teardown scripts. This output is suppressed in failures-only and parallel modes.

```text
● set_up_before_script                                               2.30s
✓ Passed: My test                                                      45ms
● tear_down_after_script                                              0.5s
```

--------------------------------

### Bashunit Snapshot Testing Example

Source: https://github.com/typeddevs/bashunit/blob/main/docs/snapshots.md

Demonstrates the usage of `assert_match_snapshot` for both successful snapshot creation and failure detection. Requires two test runs: the first creates snapshots, and the second asserts against them.

```bash
function test_success() {
  assert_match_snapshot "$(ls)"
}

function test_failure() {
  assert_match_snapshot "$(date)"
}
```

```text
Running snapshot_test.sh
✎ Snapshot: Success
✎ Snapshot: Failure

Tests:		2 snapshot, 2 total
Assertions:	2 snapshot, 2 total
Some snapshots created
```

```text
Running snapshot_test.sh
✓ Passed: Success
✗ Failed: Failure
    Expected to match the snapshot
    Mon Jul 27 [-13:37:46-]{+13:37:49+} UTC 1987

Tests:		1 passed, 1 failed, 2 total
Assertions:	1 passed, 1 failed, 2 total
Some tests failed
```

--------------------------------

### Install Bashunit via npm

Source: https://github.com/typeddevs/bashunit/blob/main/docs/blog/2026-05-07-release-0-36.md

Install bashunit globally or as a project dev dependency using npm. This allows for version pinning and management within your project.

```bash
npm install -g bashunit
```

```bash
npm install --save-dev bashunit
```

--------------------------------

### Example Test Function Names

Source: https://github.com/typeddevs/bashunit/blob/main/docs/test-files.md

These are examples of valid test function names that bashunit will discover and execute. Function names must be prefixed with 'test' and are case-insensitive.

```bash
function test_should_validate_an_ok_exit_code() { ... }
```

```bash
function testRenderAllTestsPassedWhenNotFailedTests { ... }
```

```bash
test_getFunctionsToRun_with_filter_should_return_matching_functions() { ... }
```

--------------------------------

### Bash: Assert Files Equal

Source: https://github.com/typeddevs/bashunit/blob/main/docs/assertions.md

Use `assert_files_equals` to verify that two files have identical content. The example demonstrates both a successful comparison and a failure case.

```bash
function test_success() {
  local expected="/tmp/file1.txt"
  local actual="/tmp/file2.txt"

  echo "file content" > "$expected"
  echo "file content" > "$actual"

  assert_files_equals "$expected" "$actual"
}

function test_failure() {
  local expected="/tmp/file1.txt"
  local actual="/tmp/file2.txt"

  echo "file content" > "$expected"
  echo "different content" > "$actual"

  assert_files_equals "$expected" "$actual"
}
```

--------------------------------

### Create Test Helper Functions

Source: https://github.com/typeddevs/bashunit/blob/main/docs/common-patterns.md

Define reusable functions for common test setup and teardown tasks, such as creating and cleaning up temporary databases or user data.

```bash
#!/usr/bin/env bash

# Create a temporary test database
function create_test_db() {
  local db_path="/tmp/test_db_$$_$RANDOM"
  mkdir -p "$db_path"
  echo "$db_path"
}

# Clean up test database
function cleanup_test_db() {
  local db_path=$1
  rm -rf "$db_path"
}

# Create a test user
function create_test_user() {
  local name=$1
  local email=$2
  echo "$name,$email,active" >> "$TEST_DB/users.csv"
}
```

```bash
#!/usr/bin/env bash

function set_up() {
  source "tests/helpers/test_helpers.sh"
  source "src/user.sh"
  export TEST_DB
  TEST_DB=$(create_test_db)
}

function tear_down() {
  cleanup_test_db "$TEST_DB"
}

function test_create_user() {
  create_test_user "John Doe" "john@example.com"

  assert_file_contains "John Doe" "$TEST_DB/users.csv"
}
```

--------------------------------

### Assertion Success and Failure Examples

Source: https://github.com/typeddevs/bashunit/blob/main/docs/standalone.md

Demonstrates a successful assertion which results in no output and an exit code of 0, and a failing assertion which provides detailed error output.

```bash
./bashunit assert equals "hello" "hello"
# Exit code: 0
```

```bash
./bashunit assert equals "hello" "world"
```

```bash
✗ Failed: assert equals
    Expected 'hello'
    but got  'world'
```

--------------------------------

### npm error on Windows

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

The npm package for Bashunit is not supported on native Windows due to platform restrictions. Install WSL to resolve this issue.

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

--------------------------------

### Run Bashunit from GitHub Action with Arguments

Source: https://github.com/typeddevs/bashunit/blob/main/docs/blog/2026-06-09-release-0-39.md

Use the 'args' input in the TypedDevs/bashunit GitHub Action to install and run your test suite in a single step. Specify test paths and parallel execution flags.

```yaml
- uses: TypedDevs/bashunit@v0
  with:
    args: 'tests/ --parallel'
```

--------------------------------

### LCOV Example Breakdown for math.sh

Source: https://github.com/typeddevs/bashunit/blob/main/docs/coverage.md

Illustrates the LCOV output for a specific bash script, detailing line hit counts and overall coverage calculation.

```lcov
TN:
SF:/path/to/src/math.sh
DA:3,2
DA:6,0
LF:2
LH:1
end_of_record
```

--------------------------------

### Isolate Code Under Test (Avoid)

Source: https://github.com/typeddevs/bashunit/blob/main/docs/benchmarks.md

Avoid including setup code, such as data generation, directly within the benchmark function as it will be included in the measured execution time.

```bash
# @revs=100 @its=5
function bench_process_data() {
  local data=$(generate_large_dataset)  # Measured!
  process "$data"
}
```

--------------------------------

### Configure npm script for Bashunit

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Define a 'test' script in your package.json to easily run Bashunit. This ensures consistency for contributors and CI environments. Requires a per-project installation.

```json
{
  "scripts": {
    "test": "bashunit tests/"
  },
  "devDependencies": {
    "bashunit": "^{{ pkg.version }}"
  }
}
```

--------------------------------

### GitHub Actions Workflow Integration

Source: https://github.com/typeddevs/bashunit/blob/main/docs/configuration.md

Example of a GitHub Actions workflow step that runs BashUnit, logs GHA commands to a file, and streams the file to stdout on failure for inline annotations.

```yaml
- run: ./bashunit --log-gha gha.log tests/ || (cat gha.log && exit 1)
```

--------------------------------

### Set Up Before Each Test

Source: https://github.com/typeddevs/bashunit/blob/main/docs/test-files.md

Use the `set_up` function to prepare the environment or set initial variables before each test function is executed. This is useful for creating temporary files or directories.

```bash
function set_up() {
  touch temp_file.txt
}
```

--------------------------------

### Interactive Tutorial

Source: https://github.com/typeddevs/bashunit/blob/main/README.md

Launches an interactive tutorial for learning bashunit.

```bash
./lib/bashunit learn
```

--------------------------------

### Bashunit Test Execution Output

Source: https://github.com/typeddevs/bashunit/blob/main/docs/quickstart.md

Example output from running bashunit tests. It shows the version, number of tests, individual test results with execution time, and a summary of passed/total tests and assertions.

```text
bashunit - {{ pkg.version }} | Tests: 1
Running tests/example_test.sh
✓ Passed: Bashunit is working                                         16 ms

Tests:      1 passed, 1 total
Assertions: 1 passed, 1 total

All tests passed
Time taken: 90 ms
```

--------------------------------

### Initialize Bashunit Test Directory

Source: https://github.com/typeddevs/bashunit/blob/main/docs/command-line.md

Use the 'init' command to set up a new test directory. By default, it creates a 'tests/' directory with sample files. You can specify a custom directory name.

```bash
# Create tests/ directory (default)
bashunit init

# Create custom directory
bashunit init spec
```

--------------------------------

### Install Bashunit with MacPorts

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Installs bashunit on macOS using the MacPorts package manager.

```bash
sudo port install bashunit
```

--------------------------------

### Create a Benchmark File

Source: https://github.com/typeddevs/bashunit/blob/main/docs/benchmarks.md

Create a benchmark file with functions prefixed with 'bench'. The file can then be run using the 'bench' command.

```bash
#!/usr/bin/env bash

# @revs=100 @its=5
function bench_my_function() {
  my_function_under_test
}
```

```bash
./bashunit bench tests/benchmark/
```

--------------------------------

### Run Benchmarks with Simple Output

Source: https://github.com/typeddevs/bashunit/blob/main/docs/benchmarks.md

Use the '--simple' flag with the 'bench' command for a concise output, showing progress dots and a summary table.

```bash
./bashunit bench --simple
```

--------------------------------

### Assert String Not Starts With

Source: https://github.com/typeddevs/bashunit/blob/main/docs/assertions.md

Reports an error if the haystack string does not start with the needle string. Use this to ensure a string does not have a specific prefix.

```bash
function test_success() {
  assert_string_not_starts_with "bar" "foobar"
}

function test_failure() {
  assert_string_not_starts_with "foo" "foobar"
}
```

--------------------------------

### Run All Benchmarks

Source: https://github.com/typeddevs/bashunit/blob/main/docs/benchmarks.md

Execute all benchmark files found in the default path or specified directories using the 'bench' command.

```bash
./bashunit bench tests/benchmark/
```

--------------------------------

### Run Benchmarks with Detailed Output

Source: https://github.com/typeddevs/bashunit/blob/main/docs/benchmarks.md

Execute benchmarks without the '--simple' flag to see detailed timing for each iteration as it runs, followed by a summary.

```bash
./bashunit bench
```

--------------------------------

### BashUnit CLI Quick Reference

Source: https://github.com/typeddevs/bashunit/blob/main/docs/command-line.md

Provides a quick overview of available bashunit subcommands and their basic usage.

```bash
bashunit test [path] [options]    # Run tests (default)
bashunit bench [path] [options]   # Run benchmarks
bashunit watch [path] [options]   # Watch files, re-run tests on change
bashunit assert <fn> <args>       # Run standalone assertion
bashunit doc [filter]             # Show assertion documentation
bashunit init [dir]               # Initialize test directory
bashunit learn                    # Interactive tutorial
bashunit upgrade                  # Upgrade to latest version
bashunit --help                   # Show help
bashunit --version                # Show version
```

--------------------------------

### Test Directory Structure Creation

Source: https://github.com/typeddevs/bashunit/blob/main/docs/common-patterns.md

Verifies the creation of a project directory structure, including subdirectories like src, tests, and docs. Asserts the existence of each expected directory.

```bash
#!/usr/bin/env bash

function set_up() {
  export TEST_DIR="/tmp/bashunit_test_$$"
  source "src/file_manager.sh"
}

function tear_down() {
  rm -rf "$TEST_DIR"
}

function test_create_directory_structure() {
  create_project_structure "$TEST_DIR"

  assert_directory_exists "$TEST_DIR"
  assert_directory_exists "$TEST_DIR/src"
  assert_directory_exists "$TEST_DIR/tests"
  assert_directory_exists "$TEST_DIR/docs"
}
```

--------------------------------

### Initialize Bashunit Test Suite

Source: https://github.com/typeddevs/bashunit/blob/main/docs/quickstart.md

Initializes a new bashunit test suite in the specified directory. This command creates a directory and populates it with a sample test file and bootstrap file.

```bash
./lib/bashunit init tests
```

--------------------------------

### Install Bashunit Dependencies on Linux/Mac using bashdep

Source: https://github.com/typeddevs/bashunit/blob/main/docs/installation.md

Ensures bashdep is installed and then adds the latest bashunit release to your project's dependencies using bashdep. This script is intended for Linux and macOS environments.

```bash
# 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/{{ pkg.version }}/bashunit"
)

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

--------------------------------

### Choose Output Style

Source: https://github.com/typeddevs/bashunit/blob/main/docs/command-line.md

Select between simple output (dots) using the --simple flag or detailed output using the --detailed flag. Simple output provides a concise overview, while detailed output lists each passed or failed test.

```bash
bashunit test tests/ --simple
```

```text
........
```

```bash
bashunit test tests/ --detailed
```

```text
Running tests/unit/example_test.sh
✓ Passed: Should validate input
✓ Passed: Should handle errors
```

--------------------------------

### Environment variables for configuration

Source: https://github.com/typeddevs/bashunit/blob/main/docs/blog/2024-09-01-release-0-15.md

All configuration keys in .env files are now prefixed with BASHUNIT_.

```bash
BASHUNIT_DEFAULT_PATH=
BASHUNIT_SHOW_HEADER=
BASHUNIT_HEADER_ASCII_ART=
BASHUNIT_SIMPLE_OUTPUT=
BASHUNIT_STOP_ON_FAILURE=
BASHUNIT_SHOW_EXECUTION_TIME=
BASHUNIT_LOG_JUNIT=
BASHUNIT_REPORT_HTML=
```

--------------------------------

### Assert String Starts With

Source: https://github.com/typeddevs/bashunit/blob/main/docs/assertions.md

Use `assert_string_starts_with` to verify if a string begins with a specified prefix. The inverse is `assert_string_not_starts_with`.

```bash
function test_success() {
  assert_string_starts_with "foo" "foobar"
}

function test_failure() {
  assert_string_starts_with "baz" "foobar"
}
```

--------------------------------

### Load Custom Environment or Bootstrap File

Source: https://github.com/typeddevs/bashunit/blob/main/docs/command-line.md

Use the --env or --boot flag followed by a file path to load a custom environment or bootstrap script before running tests. Arguments can be passed to the script directly or via the BASHUNIT_BOOTSTRAP_ARGS environment variable.

```bash
bashunit test --env tests/bootstrap.sh tests/
```

```bash
# Pass arguments to the bootstrap file
bashunit test --env "tests/bootstrap.sh staging verbose" tests/
```

```bash
BASHUNIT_BOOTSTRAP_ARGS="staging verbose" bashunit test tests/
```

--------------------------------

### Display Bashunit Version

Source: https://github.com/typeddevs/bashunit/blob/main/docs/command-line.md

Use this command to check the currently installed version of bashunit. The output format includes the package version.

```bash
bashunit --version
```

--------------------------------

### Example tear_down_after_script function

Source: https://github.com/typeddevs/bashunit/blob/main/docs/test-files.md

This function is called once after all tests in a file have completed. It is used for cleanup operations like closing database connections.

```bash
function tear_down_after_script() {
  close_database_connection
}
```

--------------------------------

### Bootstrap Test Environment

Source: https://github.com/typeddevs/bashunit/blob/main/docs/common-patterns.md

Use a bootstrap file to set up common test environment variables and load necessary utility scripts before running tests.

```bash
#!/usr/bin/env bash

# Set test environment variables
export TEST_MODE=true
export LOG_LEVEL=debug
export CONFIG_PATH=/tmp/test_config

# Load common test utilities
source "tests/helpers/test_helpers.sh"

# Setup test database connection
export DB_HOST=localhost
export DB_PORT=5432
export DB_NAME=test_db
```

```bash
# Run tests with bootstrap file
./bashunit --env tests/bootstrap.sh tests/
```

--------------------------------

### Mocking a function with a body

Source: https://github.com/typeddevs/bashunit/blob/main/docs/test-doubles.md

Override a function with a custom body. This example shows how to mock the `ps` command to return a specific string.

```bash
function test_example() {
  bashunit::mock ps echo hello world

  assert_same "hello world" "$(ps)"
}
```

--------------------------------

### BashUnit assert_empty Example

Source: https://github.com/typeddevs/bashunit/blob/main/docs/assertions.md

Use `assert_empty` to confirm that a given string is empty. The inverse assertion, `assert_not_empty`, can be used to ensure a string contains content.

```bash
function test_success() {
  assert_empty ""
}

function test_failure() {
  assert_empty "foo"
}
```

--------------------------------

### Display Command-Specific Help

Source: https://github.com/typeddevs/bashunit/blob/main/docs/command-line.md

Each bashunit subcommand supports a --help flag to display detailed usage information and options specific to that command.

```bash
bashunit test --help
```

```bash
bashunit bench --help
```

```bash
bashunit watch --help
```

```bash
bashunit doc --help
```

--------------------------------

### Bootstrap Test Environment with Arguments

Source: https://github.com/typeddevs/bashunit/blob/main/docs/common-patterns.md

Pass arguments to your bootstrap file to configure different test environments dynamically, avoiding the need for multiple bootstrap files.

```bash
#!/usr/bin/env bash

# Receive arguments passed to bootstrap
ENVIRONMENT="${1:-production}"
VERBOSE="${2:-false}"

# Configure based on environment
case "$ENVIRONMENT" in
  staging)
    export API_URL="https://staging.api.example.com"
    export DB_NAME="test_staging_db"
    ;;
  ci)
    export API_URL="https://ci.api.example.com"
    export DB_NAME="test_ci_db"
    ;;
  *)
    export API_URL="https://api.example.com"
    export DB_NAME="test_db"
    ;;
esac

[[ "$VERBOSE" == "true" ]] && export LOG_LEVEL=debug
```

```bash
# Pass arguments inline with --env
./bashunit --env "tests/bootstrap.sh staging true" tests/

# Or via environment variable
BASHUNIT_BOOTSTRAP_ARGS="staging true" ./bashunit tests/
```

--------------------------------

### Run Tests with Options

Source: https://github.com/typeddevs/bashunit/blob/main/docs/command-line.md

Executes tests using parallel execution and a simple output format.

```bash
# Run with options
bashunit test tests/ --parallel --simple
```

--------------------------------

### Project Configuration with .bashunitrc

Source: https://github.com/typeddevs/bashunit/blob/main/docs/blog/2026-06-03-release-0-37.md

Define default bashunit settings for your project by creating a `.bashunitrc` file at the project root. These settings are used when not overridden by environment variables or command-line flags.

```bash
# .bashunitrc
BASHUNIT_PARALLEL_RUN=true
BASHUNIT_SHOW_OUTPUT=true
BASHUNIT_PROFILE_COUNT=15
```

--------------------------------

### Assert Directory Not Empty

Source: https://github.com/typeddevs/bashunit/blob/main/docs/assertions.md

Use assert_is_directory_not_empty to confirm that a directory contains files or subdirectories. This assertion is useful for checking if setup operations have populated a directory.

```bash
function test_success() {
  local directory="/etc"

  assert_is_directory_not_empty "$directory"
}
```

```bash
function test_failure() {
  local directory="/home/user/empty_directory"
  mkdir "$directory"

  assert_is_directory_not_empty "$directory"
}
```

--------------------------------

### Assert Date Within Range

Source: https://github.com/typeddevs/bashunit/blob/main/docs/assertions.md

Use assert_date_within_range to verify if the actual date falls inclusively between a start and end date. Inputs are converted to epoch seconds.

```bash
function test_success() {
  assert_date_within_range "1600000000" "1800000000" "1700000000"
}

function test_failure() {
  assert_date_within_range "1600000000" "1800000000" "1900000000"
}
```

--------------------------------

### Enable Basic Code Coverage

Source: https://github.com/typeddevs/bashunit/blob/main/docs/coverage.md

Run your tests with the `--coverage` flag to enable code coverage tracking.

```bash
bashunit tests/ --coverage
```

--------------------------------

### Tear Down After Each Test

Source: https://github.com/typeddevs/bashunit/blob/main/docs/test-files.md

Use the `tear_down` function to clean up resources allocated or changes made during the `set_up` or test function. This ensures each test starts with a clean state.

```bash
function tear_down() {
  rm temp_file.txt
}
```

--------------------------------

### Assert False with Various Inputs

Source: https://github.com/typeddevs/bashunit/blob/main/docs/assertions.md

Demonstrates using assert_false with boolean values, commands that return 1 (false), and functions. Use this to verify conditions that should evaluate to false.

```bash
function test_success() {
  assert_false false
  assert_false 1
  assert_false "eval return 1"
  assert_false mock_false
}

function test_failure() {
  assert_false true
  assert_false 0
  assert_false "eval return 0"
  assert_false mock_true
}
```

```bash
function mock_true() {
  return 0
}
function mock_false() {
  return 1
}
```