Merge branch 'main' into add-assert-subcommand

Author: Chemaclass

CHANGELOG.md

@@ -3,6 +3,9 @@
 ## Unreleased
 
 ### Added
+- Add bootstrap argument passing support via `--env "file.sh arg1 arg2"` or `BASHUNIT_BOOTSTRAP_ARGS` (fixes #546)
+- Add `--preserve-env` flag to skip `.env` loading and use shell environment only (fixes #546)
+- Add `-l, --login` flag to run tests in login shell context (fixes #546)
 - Add `--strict` flag to enable strict shell mode (`set -euo pipefail`) for tests (fixes #540)
 - Add `BASHUNIT_STRICT_MODE` configuration option (default: `false`)
 - Add `-R, --run-all` flag to run all assertions even when one fails (fixes #536)
@@ -281,7 +284,7 @@
 - Enable display execution time on macOS with `SHOW_EXECUTION_TIME`
 - Support for displaying the clock without `perl` (for non-macOS)
 - Enable strict mode
-- Add `-l|--log-junit <log.xml>` option
+- Add `--log-junit <log.xml>` option
 - Add `-r|--report-html <report.html>` option
 - Add `--debug` option
 - Add `dump` and `dd` functions for local debugging

bashunit

@@ -38,6 +38,18 @@ export BASHUNIT_ROOT_DIR
 declare -r BASHUNIT_WORKING_DIR="$PWD"
 export BASHUNIT_WORKING_DIR
 
+# Early scan for flags that must be set before loading env.sh
+for arg in "$@"; do
+  case "$arg" in
+    --preserve-env)
+      export BASHUNIT_PRESERVE_ENV=true
+      ;;
+    -l|--login)
+      export BASHUNIT_LOGIN_SHELL=true
+      ;;
+  esac
+done
+
 source "$BASHUNIT_ROOT_DIR/src/dev/debug.sh"
 source "$BASHUNIT_ROOT_DIR/src/check_os.sh"
 source "$BASHUNIT_ROOT_DIR/src/str.sh"

docs/command-line.md

@@ -46,9 +46,9 @@ bashunit test tests/ --parallel --simple
 | Option | Description |
 |--------|-------------|
 | `-a, --assert <fn> <args>` | Run a standalone assert function |
-| `-e, --env, --boot <file>` | Load custom env/bootstrap file |
+| `-e, --env, --boot <file>` | Load custom env/bootstrap file (supports args) |
 | `-f, --filter <name>` | Only run tests matching name |
-| `-l, --log-junit <file>` | Write JUnit XML report |
+| `--log-junit <file>` | Write JUnit XML report |
 | `-p, --parallel` | Run tests in parallel (default) |
 | `--no-parallel` | Run tests sequentially |
 | `-r, --report-html <file>` | Write HTML report |
@@ -62,6 +62,8 @@ bashunit test tests/ --parallel --simple
 | `--debug [file]` | Enable shell debug mode |
 | `--no-output` | Suppress all output |
 | `--strict` | Enable strict shell mode |
+| `--preserve-env` | Skip `.env` loading, use shell environment only |
+| `-l, --login` | Run tests in login shell context |
 
 ### Standalone Assert
 
@@ -92,6 +94,42 @@ bashunit test tests/ --filter "user_login"
 ```
 :::
 
+### Environment / Bootstrap
+
+> `bashunit test -e|--env|--boot <file>`
+> `bashunit test --env "file arg1 arg2"`
+
+Load a custom environment or bootstrap file before running tests.
+
+::: code-group
+```bash [Basic usage]
+bashunit test --env tests/bootstrap.sh tests/
+```
+```bash [With arguments]
+# Pass arguments to the bootstrap file
+bashunit test --env "tests/bootstrap.sh staging verbose" tests/
+```
+:::
+
+Arguments are available as positional parameters (`$1`, `$2`, etc.) in your bootstrap script:
+
+```bash
+#!/usr/bin/env bash
+# tests/bootstrap.sh
+ENVIRONMENT="${1:-production}"
+VERBOSE="${2:-false}"
+
+export API_URL="https://${ENVIRONMENT}.api.example.com"
+```
+
+You can also set arguments via environment variable:
+
+```bash
+BASHUNIT_BOOTSTRAP_ARGS="staging verbose" bashunit test tests/
+```
+
+See [Configuration: Bootstrap](/configuration#bootstrap) for more details.
+
 ### Inline Filter Syntax
 
 You can also specify a filter directly in the file path using `::` or `:line` syntax:
@@ -197,6 +235,47 @@ bashunit test tests/ --strict
 ```
 :::
 
+### Preserve Environment
+
+> `bashunit test --preserve-env`
+
+Skip loading the `.env` file and use the current shell environment only.
+
+By default, bashunit loads variables from `.env` which can override environment
+variables set in your shell. Use `--preserve-env` when you want to:
+- Run in CI/CD where environment is pre-configured
+- Override `.env` values with shell environment variables
+- Avoid `.env` interfering with your current settings
+
+::: code-group
+```bash [Example]
+BASHUNIT_SIMPLE_OUTPUT=true ./bashunit test tests/ --preserve-env
+```
+:::
+
+### Login Shell
+
+> `bashunit test -l|--login`
+
+Run tests in a login shell context by sourcing profile files.
+
+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, such as:
+- PATH modifications
+- Shell functions defined in `.bash_profile`
+- Environment variables set during login
+
+::: code-group
+```bash [Example]
+bashunit test tests/ --login
+```
+:::
+
 ## bench
 
 > `bashunit bench [path] [options]`
@@ -220,11 +299,13 @@ bashunit bench --filter "parse"
 
 | Option | Description |
 |--------|-------------|
-| `-e, --env, --boot <file>` | Load custom env/bootstrap file |
+| `-e, --env, --boot <file>` | Load custom env/bootstrap file (supports args) |
 | `-f, --filter <name>` | Only run benchmarks matching name |
 | `-s, --simple` | Simple output |
 | `--detailed` | Detailed output (default) |
 | `-vvv, --verbose` | Show execution details |
+| `--preserve-env` | Skip `.env` loading, use shell environment only |
+| `-l, --login` | Run in login shell context |
 
 ## doc
 

docs/common-patterns.md

@@ -660,6 +660,52 @@ export DB_NAME=test_db
 ```
 :::
 
+### Bootstrap Files with Arguments
+
+Pass configuration to your bootstrap file for different test scenarios:
+
+::: code-group
+```bash [tests/bootstrap.sh]
+#!/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 [Run with arguments]
+# Pass arguments inline with --env
+./bashunit --env "tests/bootstrap.sh staging true" tests/
+
+# Or via environment variable
+BASHUNIT_BOOTSTRAP_ARGS="staging true" ./bashunit tests/
+```
+:::
+
+::: tip
+Use bootstrap arguments to avoid duplicating bootstrap files for different
+environments. A single bootstrap file can configure staging, CI, or local
+development based on the arguments passed.
+:::
+
 ## Testing Private Functions
 
 When you need to test functions that aren't exported:

docs/configuration.md

@@ -237,6 +237,33 @@ 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.
+
+::: code-group
+```bash [.env]
+BASHUNIT_BOOTSTRAP="tests/bootstrap.sh"
+BASHUNIT_BOOTSTRAP_ARGS="staging verbose"
+```
+```bash [bootstrap.sh]
+#!/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](/command-line#environment) option:
+
+```bash
+bashunit --env "tests/bootstrap.sh staging verbose" tests/
+```
+
 ## Dev log
 
 > `BASHUNIT_DEV_LOG=file`
@@ -310,6 +337,46 @@ BASHUNIT_STRICT_MODE=true
 ```
 :::
 
+## Preserve environment
+
+> `BASHUNIT_PRESERVE_ENV=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.
+
+Similar as using `--preserve-env` option on the [command line](/command-line#preserve-environment).
+
+::: code-group
+```bash [Example]
+BASHUNIT_PRESERVE_ENV=true ./bashunit tests/
+```
+:::
+
+## Login shell
+
+> `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](/command-line#login-shell).
+
+::: code-group
+```bash [Example]
+BASHUNIT_LOGIN_SHELL=true
+```
+:::
+
 <script setup>
 import pkg from '../package.json'
 </script>

src/console_header.sh

@@ -103,9 +103,9 @@ Arguments:
 
 Options:
   -a, --assert <fn> <args>    Run a standalone assert function (deprecated: use 'bashunit assert')
-  -e, --env, --boot <file>    Load a custom env/bootstrap file
+  -e, --env, --boot <file>    Load a custom env/bootstrap file  (supports args)
   -f, --filter <name>         Only run tests matching the name
-  -l, --log-junit <file>      Write JUnit XML report
+  --log-junit <file>          Write JUnit XML report
   -p, --parallel              Run tests in parallel (default)
   --no-parallel               Run tests sequentially
   -r, --report-html <file>    Write HTML report
@@ -117,6 +117,8 @@ Options:
   --debug [file]              Enable shell debug mode
   --no-output                 Suppress all output
   --strict                    Enable strict shell mode (set -euo pipefail)
+  --preserve-env              Skip .env loading, use shell environment only
+  -l, --login                 Run tests in login shell context
   -h, --help                  Show this help message
 
 Examples:
@@ -137,11 +139,13 @@ Arguments:
   path                        File or directory containing benchmarks
 
 Options:
-  -e, --env, --boot <file>    Load a custom env/bootstrap file
+  -e, --env, --boot <file>    Load a custom env/bootstrap file (supports args)
   -f, --filter <name>         Only run benchmarks matching the name
   -s, --simple                Simple output
   --detailed                  Detailed output (default)
   -vvv, --verbose             Show execution details
+  --preserve-env              Skip .env loading, use shell environment only
+  -l, --login                 Run in login shell context
   -h, --help                  Show this help message
 
 Examples: