Configuration

Environment configuration to control bashunit behavior.

It serves to configure the behavior of bashunit in your project. You need to create a .env file in the root directory, but you can give it another name if you pass it as an argument to the command with --env option.

Default path

BASHUNIT_DEFAULT_PATH=directory|file

Specifies the directory or file containing the tests to be run. empty by default.

If a directory is specified, it will execute tests within files ending in bench.sh. When running benchmarks (--bench), the same path is used to search for files ending in bench.sh.

If you use wildcards, bashunit will run any tests it finds.

Example

bash

# all tests inside the tests directory
BASHUNIT_DEFAULT_PATH=tests

# concrete test by full path
BASHUNIT_DEFAULT_PATH=tests/example_test.sh

# all test matching given wildcard
BASHUNIT_DEFAULT_PATH=tests/**/*_test.sh

Output

BASHUNIT_SIMPLE_OUTPUT=true|false

Enables simplified output to the console. false by default.

Verbose is the default output, but it can be overridden by the environment configuration.

Similar as using -s|--simple | -vvv|--detailed option on the command line.

Simple output.env

bash

....

bash

BASHUNIT_SIMPLE_OUTPUT=true

Verbose output.env

Running tests/functional/logic_test.sh
✓ Passed: Other way of using the exit code
✓ Passed: Should validate a non ok exit code
✓ Passed: Should validate an ok exit code
✓ Passed: Text should be equal

bash

BASHUNIT_SIMPLE_OUTPUT=false

Parallel

BASHUNIT_PARALLEL_RUN=true|false

Runs the tests in child processes with randomized execution, which may improve overall testing speed, especially for larger test suites.

WARNING

Parallel execution is supported only on macOS and Ubuntu. On other systems bashunit forces sequential execution to avoid inconsistent results.

Similar as using -p|--parallel option on the command line.

Stop on failure

BASHUNIT_STOP_ON_FAILURE=true|false

Force to stop the runner right after encountering one failing test. false by default.

Similar as using -S|--stop-on-failure option on the command line.

Assertion behavior

By default, when an assertion fails within a test, subsequent assertions in the same test are skipped. Use -R, --run-all or set BASHUNIT_STOP_ON_ASSERTION_FAILURE=false to run all assertions even when one fails.

The --stop-on-failure flag is separate – it stops the entire test runner after a failing test, while assertion-level stopping happens within each test.

Stop on assertion failure

BASHUNIT_STOP_ON_ASSERTION_FAILURE=true|false

Controls whether to stop at the first failed assertion within a test. true by default.

When enabled (default), subsequent assertions in the same test are skipped after a failure. When disabled, all assertions in the test run, showing all failures at once.

Similar as using -R|--run-all option on the command line.

Run all assertionsStop on first failure (default)

bash

BASHUNIT_STOP_ON_ASSERTION_FAILURE=false

bash

BASHUNIT_STOP_ON_ASSERTION_FAILURE=true

Show header

BASHUNIT_SHOW_HEADER=true|false
BASHUNIT_HEADER_ASCII_ART=true|false

Specify if you want to show the bashunit header. true by default.

Additionally, you can use the env-var BASHUNIT_HEADER_ASCII_ART to display bashunit in ASCII. false by default.

Without header.env

✓ Passed: foo bar

bash

BASHUNIT_SHOW_HEADER=false

Plain header.env

bashunit - 0.30.0 // [!code hl]

✓ Passed: foo bar

bash

BASHUNIT_SHOW_HEADER=true

ASCII header.env

__               _                   _    // [!code hl]
| |__   __ _ ___| |__  __ __ ____ (_) |_  // [!code hl]
| '_ \ / _' / __| '_ \| | | | '_ \| | __| // [!code hl]
| |_) | (_| \__ \ | | | |_| | | | | | |_  // [!code hl]
|_.__/ \__,_|___/_| |_|\___/|_| |_|_|\__| // [!code hl]
0.30.0 // [!code hl]

✓ Passed: foo bar

bash

BASHUNIT_SHOW_HEADER=true
BASHUNIT_HEADER_ASCII_ART=true

Show execution time

BASHUNIT_SHOW_EXECUTION_TIME=true|false

Specify if you want to display the execution time after running bashunit. true by default.

The time format adapts based on duration:

Under 1 second: displayed in milliseconds (e.g., 14 ms)
1-59 seconds: displayed in seconds (e.g., 5 s)
60+ seconds: displayed in minutes and seconds (e.g., 2m 1s)

With execution time.env

✓ Passed: foo bar

Tests:      1 passed, 1 total
Assertions: 3 passed, 3 total
All tests passed
Time taken: 14 ms  // [!code hl]

bash

BASHUNIT_SHOW_EXECUTION_TIME=true

Without execution time.env

✓ Passed: foo bar

Tests:      1 passed, 1 total
Assertions: 3 passed, 3 total
All tests passed

bash

BASHUNIT_SHOW_EXECUTION_TIME=false

Log JUnit

BASHUNIT_LOG_JUNIT=file

Create a report XML file that follows the JUnit XML format and contains information about the test results of your bashunit tests.

Example

bash

BASHUNIT_LOG_JUNIT=log-junit.xml

Report HTML

BASHUNIT_REPORT_HTML=file

Create a report HTML file that contains information about the test results of your bashunit tests.

Example

bash

BASHUNIT_REPORT_HTML=report.html

Bootstrap

BASHUNIT_BOOTSTRAP=file

Specifies an additional file to be loaded for all tests cases. Useful to set up global variables or functions accessible in all your tests.

Using functions in tests

If you need shell functions available in your tests, define them in a bootstrap file and use export -f function_name to make them available in test subshells. This is the recommended pattern for sharing functions across tests.

Similarly, you can use load an additional file via the command line.

Example

bash

# a simple .env file
BASHUNIT_BOOTSTRAP=".env.tests"

# or a complete script file
BASHUNIT_BOOTSTRAP="tests/globals.sh"

# Default value
BASHUNIT_BOOTSTRAP="tests/bootstrap.sh"

Bootstrap arguments

BASHUNIT_BOOTSTRAP_ARGS=arguments

Pass arguments to the bootstrap file. Arguments are space-separated and available as positional parameters ($1, $2, etc.) in your bootstrap script.

.envbootstrap.sh

bash

BASHUNIT_BOOTSTRAP="tests/bootstrap.sh"
BASHUNIT_BOOTSTRAP_ARGS="staging verbose"

bash

#!/usr/bin/env bash
ENVIRONMENT="${1:-production}"
VERBOSE="${2:-false}"

export API_URL="https://${ENVIRONMENT}.api.example.com"

You can also pass arguments inline via the --env option:

bash

bashunit --env "tests/bootstrap.sh staging verbose" tests/

Dev log

BASHUNIT_DEV_LOG=file

See: Globals > log

SetupUsageOutput: out.log

bash

BASHUNIT_DEV_LOG="dev.log"

bash

log "I am tracing something..."
log "error" "an" "error" "message"
log "warning" "different log level messages!"

bash

2024-10-03 21:27:23 [INFO]: I am tracing something... #tests/sample.sh:11
2024-10-03 21:27:23 [ERROR]: an error message #tests/sample.sh:27
2024-10-03 21:27:24 [WARNING]: different log level messages! #tests/sample.sh:21

When enabled, the selected log file path is printed in the header so you can quickly tail -f it while the tests run.

All internal messages emitted by bashunit are prefixed with [INTERNAL]. You can toggle internal messages with BASHUNIT_INTERNAL_LOG=true|false.

Verbose

BASHUNIT_VERBOSE=bool

Display internal details for each test.

Similarly, you can use the command line option for this: command line.

Example

bash

BASHUNIT_VERBOSE=true

No output

BASHUNIT_NO_OUTPUT=true|false

Suppress all console output. Defaults to false.

Similar as using --no-output option on the command line.

Example

bash

BASHUNIT_NO_OUTPUT=true

Failures only

BASHUNIT_FAILURES_ONLY=true|false

Only show failures, suppressing passed, skipped, and incomplete tests. false by default.

When enabled, progress output is suppressed and only failing tests are displayed. The final summary still shows all counts (passed/failed/skipped/incomplete).

Similar as using --failures-only option on the command line.

Example

bash

BASHUNIT_FAILURES_ONLY=true

Color output

NO_COLOR=1

Disables ANSI color codes in output. Follows the no-color.org standard.

When set to any value, bashunit will output plain text without color formatting.

Similar as using --no-color option on the command line.

Example

bash

NO_COLOR=1

Strict mode

BASHUNIT_STRICT_MODE=true|false

Enable strict shell mode (set -euo pipefail) for test execution. false by default.

By default, tests run in permissive mode to maximize compatibility with different coding styles. Enable strict mode to catch potential issues like uninitialized variables and unchecked command failures.

Similar as using --strict option on the command line.

Example

bash

BASHUNIT_STRICT_MODE=true

Skip env file

BASHUNIT_SKIP_ENV_FILE=true|false

Skip loading the .env file and use the current shell environment only. false by default.

By default, bashunit loads variables from .env which can override environment variables set in your shell. Enable this option when running in CI/CD pipelines or when you want shell environment variables to take precedence.

Important

Only environment variables are inherited from the parent shell. Shell functions and aliases are NOT available in tests due to bashunit's subshell architecture. Use a bootstrap file to define functions needed by your tests.

Similar as using --skip-env-file option on the command line.

Example

bash

BASHUNIT_SKIP_ENV_FILE=true ./bashunit tests/

BASHUNIT_LOGIN_SHELL=true|false

Run tests in a login shell context by sourcing profile files. false by default.

When enabled, bashunit sources the following files (if they exist) before each test:

/etc/profile
~/.bash_profile
~/.bash_login
~/.profile

Use this when your tests depend on environment setup from login shell profiles.

Similar as using -l|--login option on the command line.

Example

bash

BASHUNIT_LOGIN_SHELL=true

Configuration ​

Default path ​

Output ​

Parallel ​

Stop on failure ​

Stop on assertion failure ​

Show header ​

Show execution time ​

Log JUnit ​

Report HTML ​

Bootstrap ​

Bootstrap arguments ​

Dev log ​

Verbose ​

No output ​

Failures only ​

Color output ​

Strict mode ​

Skip env file ​

Login shell ​

Configuration

Default path

Output

Parallel

Stop on failure

Stop on assertion failure

Show header

Show execution time

Log JUnit

Report HTML

Bootstrap

Bootstrap arguments

Dev log

Verbose

No output

Failures only

Color output

Strict mode

Skip env file

Login shell