From 87dbdc7f96aed159b2f33379fb96c36dc67ae462 Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Sun, 11 Oct 2026 21:51:06 +0200 Subject: [PATCH 1/2] docs: add missing release blog posts --- CHANGELOG.md | 4 ++ docs/blog/2026-07-24-release-0-43.md | 40 ++++++++++++++++++++ docs/blog/2026-07-29-release-0-44.md | 52 ++++++++++++++++++++++++++ docs/blog/2026-08-09-release-0-45.md | 50 +++++++++++++++++++++++++ docs/blog/2026-08-11-release-0-46.md | 50 +++++++++++++++++++++++++ docs/blog/2026-08-13-release-0-47.md | 48 ++++++++++++++++++++++++ docs/blog/2026-08-14-release-0-48.md | 38 +++++++++++++++++++ docs/blog/2026-08-16-release-0-49.md | 47 +++++++++++++++++++++++ docs/blog/2026-08-18-release-0-50.md | 50 +++++++++++++++++++++++++ docs/blog/2026-08-22-release-0-50-1.md | 36 ++++++++++++++++++ docs/blog/2026-09-18-release-0-51.md | 40 ++++++++++++++++++++ docs/blog/2026-10-11-release-0-52.md | 36 ++++++++++++++++++ 12 files changed, 491 insertions(+) create mode 100644 docs/blog/2026-07-24-release-0-43.md create mode 100644 docs/blog/2026-07-29-release-0-44.md create mode 100644 docs/blog/2026-08-09-release-0-45.md create mode 100644 docs/blog/2026-08-11-release-0-46.md create mode 100644 docs/blog/2026-08-13-release-0-47.md create mode 100644 docs/blog/2026-08-14-release-0-48.md create mode 100644 docs/blog/2026-08-16-release-0-49.md create mode 100644 docs/blog/2026-08-18-release-0-50.md create mode 100644 docs/blog/2026-08-22-release-0-50-1.md create mode 100644 docs/blog/2026-09-18-release-0-51.md create mode 100644 docs/blog/2026-10-11-release-0-52.md diff --git a/CHANGELOG.md b/CHANGELOG.md index a6e8ee203..0c55cd318 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## Unreleased +### Added + +- Blog posts for releases 0.43.0 through 0.52.0, including the 0.50.1 cleanup patch + ## [0.52.0](https://github.com/TypedDevs/bashunit/compare/0.51.0...0.52.0) - 2026-10-11 ### Changed diff --git a/docs/blog/2026-07-24-release-0-43.md b/docs/blog/2026-07-24-release-0-43.md new file mode 100644 index 000000000..1cd0b05e1 --- /dev/null +++ b/docs/blog/2026-07-24-release-0-43.md @@ -0,0 +1,40 @@ +--- +date: '2026-07-24' +title: 'Release 0.43.0' +description: 'Loop branch coverage and fewer subprocesses in assertions and parallel tests.' +coverAlt: 'Loop branch coverage and process reductions in string assertions and parallel workers' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.43.0 adds branch coverage for loops and reduces the number of processes started by assertions and parallel workers. Existing assertions keep their behavior, so the process changes do not require rewriting tests. + +## Find loops your tests never enter + +Branch coverage now includes `while`, `until`, `for`, and `select`. Each loop body is represented as a single branch, covered when the loop runs at least once. A test that only exercises an empty input can therefore leave the loop body uncovered even when the surrounding function runs successfully ([#855](https://github.com/TypedDevs/bashunit/issues/855)). + +```bash +bashunit tests/ --coverage --coverage-paths src/ +``` + +For a function that processes a list, include both an empty-list case and a case with at least one item. The first checks what happens when the loop is skipped; the second reaches its body. The coverage report now makes the missing body case visible. It records whether the loop was entered, rather than reporting a separate branch for each iteration. + +## Fewer processes for the same assertions + +String assertions such as `assert_contains`, `assert_matches`, and the prefix and suffix checks no longer start a subshell to join their arguments. Array, date, duration, JSON, file, and folder assertions also resolve their failure labels without a command substitution. The labels and comparison behavior stay the same ([#844](https://github.com/TypedDevs/bashunit/issues/844)). + +Parallel workers now name result files using an ordinal assigned by the suite, replacing a temporary-file creation and rename for every test. Data-provider tests also avoid the argument-sanitizing pipeline previously used for those names. Result aggregation is unchanged ([#851](https://github.com/TypedDevs/bashunit/issues/851)). + +```bash +bashunit --parallel tests/ +``` + +These changes reduce repeated process work as the number of assertions and tests grows, without introducing new options or changing how you invoke the suite. + +--- + +See the full changelog for [0.43.0](https://github.com/TypedDevs/bashunit/releases/tag/0.43.0) on GitHub. diff --git a/docs/blog/2026-07-29-release-0-44.md b/docs/blog/2026-07-29-release-0-44.md new file mode 100644 index 000000000..c8d620e98 --- /dev/null +++ b/docs/blog/2026-07-29-release-0-44.md @@ -0,0 +1,52 @@ +--- +date: '2026-07-29' +title: 'Release 0.44.0' +description: 'Custom assertion helpers, snapshot controls, clearer spy checks, and stricter configuration validation.' +coverAlt: 'Custom assertions, snapshot review controls, spy diagnostics and configuration validation' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.44.0 gives custom assertions their own testing and documentation workflow. It also adds explicit snapshot controls and catches configuration mistakes that could previously produce misleading results. + +## Build and test custom assertions + +`bashunit::assert_that` runs a command and records the assertion verdict in one call. `bashunit::assert_once` lets a composed assertion count and report once under its own label, rather than once for every inner check. Existing assertion totals stay unchanged unless you opt in ([#915](https://github.com/TypedDevs/bashunit/issues/915), [#917](https://github.com/TypedDevs/bashunit/issues/917)). + +The new `assert_assertion_passes`, `assert_assertion_fails`, and `assert_assertion_fails_with` helpers test what a custom assertion reports. They isolate its counters and output, so a deliberate failure does not fail the surrounding test ([#916](https://github.com/TypedDevs/bashunit/issues/916)). + +```bash +function test_positive_assertion() { + assert_assertion_passes assert_positive_number 3 + assert_assertion_fails_with "positive number" assert_positive_number 0 +} +``` + +Here, `assert_positive_number` is your project's assertion. Load its bootstrap file to list its documentation alongside the built-in reference, or select only custom assertions with `--custom` ([#918](https://github.com/TypedDevs/bashunit/issues/918)). + +```bash +bashunit doc --custom --boot tests/bootstrap.sh +``` + +## Review snapshots deliberately + +Use `--snapshot-update` to re-record existing snapshots after an intentional change, optionally narrowing the run with `--filter`. Snapshots containing placeholders are left alone. In CI, `--no-snapshot-create` makes a missing snapshot fail instead of silently creating the first reference. `--snapshot-report-unused` lists leftovers from renamed or deleted tests without deleting anything, and requires a full run ([#900](https://github.com/TypedDevs/bashunit/issues/900), [#901](https://github.com/TypedDevs/bashunit/issues/901), [#902](https://github.com/TypedDevs/bashunit/issues/902)). + +```bash +bashunit tests/ --no-snapshot-create +bashunit tests/ --snapshot-report-unused +``` + +## Catch mistakes before trusting a pass + +Spy assertions now reject an unregistered command instead of treating it as a spy with zero calls. Per-argument comparisons distinguish one argument containing a space from two separate arguments, and failed call checks show the recorded calls. + +Invalid options, numeric settings, and missing bootstrap or environment files now produce errors. Coverage also gains an `xtrace` engine on Bash 4.1 and later; automatic selection retains the trap engine on older shells. The supported Bash floor remains 3.0. + +--- + +See the full changelog for [0.44.0](https://github.com/TypedDevs/bashunit/releases/tag/0.44.0) on GitHub. diff --git a/docs/blog/2026-08-09-release-0-45.md b/docs/blog/2026-08-09-release-0-45.md new file mode 100644 index 000000000..f378200e5 --- /dev/null +++ b/docs/blog/2026-08-09-release-0-45.md @@ -0,0 +1,50 @@ +--- +date: '2026-08-09' +title: 'Release 0.45.0' +description: 'Symlink assertions, command arguments in boolean checks, named snapshots, and correctness fixes.' +coverAlt: 'Symlink checks, command assertions, named snapshots and corrected test results' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.45.0 adds ways to check symbolic links, invoke commands through boolean assertions, and keep multiple snapshots in one test. It also fixes cases where malformed inputs or missing commands could produce misleading results. + +## Check the link itself + +Most filesystem assertions follow a symbolic link to its target. The new `assert_is_symlink`, `assert_is_not_symlink`, and `assert_symlink_to` inspect the link itself, making them useful for scripts that maintain a current-release link ([#981](https://github.com/TypedDevs/bashunit/issues/981)). + +```bash +function test_current_release_link() { + assert_is_symlink "./current" + assert_symlink_to "./releases/42" "./current" +} +``` + +## Pass arguments directly to boolean assertions + +`assert_true` and `assert_false` now accept a command followed by its arguments. A single argument retains its previous meaning ([#994](https://github.com/TypedDevs/bashunit/issues/994)). + +```bash +function test_release_directory() { + assert_true test -d "./releases/42" + assert_false test -d "./releases/missing" +} +``` + +Both assertions now fail when the command is unknown or not executable. A missing command is no longer accepted by `assert_false` as evidence that the intended condition was false; the failure message explains that the command could not run ([#982](https://github.com/TypedDevs/bashunit/issues/982)). + +## Keep snapshots distinct and results reliable + +Named snapshots let a test record more than one expected value. On a mismatch, bashunit shows the resolved snapshot path and the `--snapshot-update` hint. Absolute test paths now resolve snapshots correctly, and the fallback for snapshot placeholders checks the whole value when Perl is unavailable ([#986](https://github.com/TypedDevs/bashunit/issues/986), [#1002](https://github.com/TypedDevs/bashunit/issues/1002)). + +Input checks are stricter too: core comparison assertions reject missing arguments, date assertions reject unparseable values, and `assert_json_equals` rejects invalid JSON. Parallel runs retain results from same-named test files in different directories. + +Several existing checks avoid repeated processes, including literal snapshots, spy counters, case-insensitive containment, and common numeric-tolerance comparisons. The standalone build also omits source comments while preserving heredoc content and source markers. These changes keep the test-facing behavior intact while reducing work around it. + +--- + +See the full changelog for [0.45.0](https://github.com/TypedDevs/bashunit/releases/tag/0.45.0) on GitHub. diff --git a/docs/blog/2026-08-11-release-0-46.md b/docs/blog/2026-08-11-release-0-46.md new file mode 100644 index 000000000..2a70964c8 --- /dev/null +++ b/docs/blog/2026-08-11-release-0-46.md @@ -0,0 +1,50 @@ +--- +date: '2026-08-11' +title: 'Release 0.46.0' +description: 'Test selection, repeat runs and flaky outcomes, richer CI reports, and diff coverage.' +coverAlt: 'Changed-test selection, flaky-test detection, CI reports and coverage of changed lines' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.46.0 makes it easier to choose a run, investigate intermittent failures, and publish results in CI. It also fixes reports that could contain zero tests after a parallel run. + +## Inspect and select a run + +`--changed` selects test files Git reports as touched since a reference, including staged, unstaged, and untracked changes. It selects changed test files, rather than finding every test affected by a source-code change. Use `--list` to inspect the selected tests without executing them ([#1010](https://github.com/TypedDevs/bashunit/issues/1010), [#1007](https://github.com/TypedDevs/bashunit/issues/1007)). + +```bash +bashunit tests/ --changed origin/main --list +bashunit tests/ --list --list-format json +``` + +Tag expressions support AND and NOT, while repeated `--tag` options keep their OR behavior. `--exclude-filter` excludes matching test names and takes precedence over inclusion. `--order-by defects` brings the previous run's failures to the front while still running the entire selected suite. + +## Look for intermittent failures + +`--repeat` runs every selected test several times, reports an aggregate result, and identifies the failed iteration. Retry-assisted passes are now counted as flaky, with the first failure included in reports. They remain inside the pass total unless you request `--fail-on-flaky` ([#1013](https://github.com/TypedDevs/bashunit/issues/1013), [#1012](https://github.com/TypedDevs/bashunit/issues/1012)). + +```bash +bashunit tests/ --repeat 20 --filter flaky_candidate +bashunit tests/ --retry 2 --fail-on-flaky +``` + +## Bring useful reports into CI + +JSON, TAP, HTML, and JUnit file reports now collect results correctly under `--parallel`. JUnit groups tests by file, includes captured output, and carries informative failure messages. Markdown summaries can populate the GitHub Actions step summary, and automatic Actions annotations point to the failing file and line ([#1004](https://github.com/TypedDevs/bashunit/issues/1004), [#1016](https://github.com/TypedDevs/bashunit/issues/1016)). + +Coverage gains Cobertura XML and `--coverage-diff`, which limits the coverage view and minimum-percentage check to changed lines: + +```bash +bashunit tests/ --coverage --coverage-diff origin/main --coverage-min 90 +``` + +Coverage processing also avoids a process per classified source line. New numeric-range and command-availability assertions round out the release, alongside clearer handling of malformed numeric values and custom-assertion failures. + +--- + +See the full changelog for [0.46.0](https://github.com/TypedDevs/bashunit/releases/tag/0.46.0) on GitHub. diff --git a/docs/blog/2026-08-13-release-0-47.md b/docs/blog/2026-08-13-release-0-47.md new file mode 100644 index 000000000..cceae45e5 --- /dev/null +++ b/docs/blog/2026-08-13-release-0-47.md @@ -0,0 +1,48 @@ +--- +date: '2026-08-13' +title: 'Release 0.47.0' +description: 'Reports on stdout, test annotations, named suites, sandboxed commands, and corrected coverage totals.' +coverAlt: 'Structured stdout reports, suite settings, sandbox checks and more complete coverage' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.47.0 adds structured reports on stdout, reusable suite settings, and controls for individual tests. Coverage now includes tracked files that no test executed, which changes how you should interpret an upgrade's percentages. + +## Send reports straight to another command + +`--output json` and `--output junit` emit a report on stdout without requiring an intermediate report file. File reporters remain available alongside them ([#1018](https://github.com/TypedDevs/bashunit/issues/1018)). + +```bash +bashunit tests/ --output json | jq '.summary' +bashunit tests/ --output junit > report.xml +``` + +Named `[suite:]` sections in `.bashunitrc` store paths and options. Use `--suite ` to select one or repeat the option to combine suites, and `--list-suites` to see available names ([#1021](https://github.com/TypedDevs/bashunit/issues/1021)). + +```bash +bashunit --list-suites +bashunit --suite unit +``` + +## Make test requirements explicit + +Per-test `# @timeout`, `# @retry`, and `# @skip` annotations override run-wide settings. Malformed values stop the run instead of quietly falling back. The new conditional skip helpers both mark the test skipped and end it, replacing a separate `return` ([#1020](https://github.com/TypedDevs/bashunit/issues/1020), [#1019](https://github.com/TypedDevs/bashunit/issues/1019)). + +`--sandbox` fails a test that invokes an external command it did not mock; `--sandbox-allow` extends the baseline allowlist. For retry-loop tests, `bashunit::mock_sequence` returns successive answers and repeats the final answer when the sequence is exhausted ([#1022](https://github.com/TypedDevs/bashunit/issues/1022), [#1023](https://github.com/TypedDevs/bashunit/issues/1023)). + +## Read the corrected coverage denominator + +Previously, coverage considered only files a test executed. Now every file under `--coverage-paths` participates, with untouched files reported at zero coverage. Percentages may drop because the measurement includes more of the code. Diff coverage also includes changed files that no test ran, preventing a new untested file from escaping the minimum-percentage check ([#1053](https://github.com/TypedDevs/bashunit/issues/1053), [#1054](https://github.com/TypedDevs/bashunit/issues/1054)). + +Corrections to case-arm and function-span parsing also change reported coverage details. Report generation performs its classification and output work in one awk invocation per run rather than repeating shell loops and processes per file. + +Benchmark runs gain JSON and JUnit artifacts and median-based baseline comparisons. `--snapshot-prune` removes unused snapshots only after a full run without failures, printing each deleted path; partial runs cannot prune ([#1029](https://github.com/TypedDevs/bashunit/issues/1029), [#1030](https://github.com/TypedDevs/bashunit/issues/1030)). + +--- + +See the full changelog for [0.47.0](https://github.com/TypedDevs/bashunit/releases/tag/0.47.0) on GitHub. diff --git a/docs/blog/2026-08-14-release-0-48.md b/docs/blog/2026-08-14-release-0-48.md new file mode 100644 index 000000000..1727ca87e --- /dev/null +++ b/docs/blog/2026-08-14-release-0-48.md @@ -0,0 +1,38 @@ +--- +date: '2026-08-14' +title: 'Release 0.48.0' +description: 'Faster coverage reports, clearer errors and fixes that keep parallel runs and machine-readable output trustworthy.' +coverAlt: 'Release 0.48.0 highlights' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.48.0 improves coverage speed and the errors that explain why a run did not execute as expected. It also fixes cases where parallel execution could report success while silently missing tests. + +## Faster coverage and HTML reports + +Coverage processing avoids repeated work when reading hits and classifying source lines. In the repository's recorded measurements, a coverage run fell from 16.2 seconds to 2.9 seconds, while generating an HTML report for 128 files fell from 58.7 seconds to 3.1 seconds ([#1092](https://github.com/TypedDevs/bashunit/issues/1092), [#1117](https://github.com/TypedDevs/bashunit/issues/1117)). Those are measurements of those workloads, rather than a promised speedup for every project. + +The HTML test report now includes a Failures section with the test name, source location and message. Its summary includes risky and flaky outcomes, and test titles are escaped before they enter the markup ([#1251](https://github.com/TypedDevs/bashunit/issues/1251), [#1252](https://github.com/TypedDevs/bashunit/issues/1252), [#1249](https://github.com/TypedDevs/bashunit/issues/1249)). Coverage reports also handle filenames containing `|`, `<` or `&`. + +On Bash 3.x, `--verbose` explains that coverage cannot count lines executed inside subshells. Hits inside command substitutions are preserved on supported newer shells, so their work no longer disappears from the result ([#1112](https://github.com/TypedDevs/bashunit/issues/1112), [#1101](https://github.com/TypedDevs/bashunit/issues/1101)). + +## Missing tests become visible failures + +Duplicate test functions are detected in parallel runs again. An undefined data provider, or one that returns no rows, now produces an error naming the provider instead of making the test vanish behind “No tests found” ([#1147](https://github.com/TypedDevs/bashunit/issues/1147), [#1145](https://github.com/TypedDevs/bashunit/issues/1145)). + +Bootstrap failures exit non-zero wherever a bootstrap is loaded. A report destination that is a directory fails with a clear message, and a benchmark path with no benchmarks also exits non-zero. These failures can now reach CI instead of looking like a passing run. + +## Output that other tools can read + +JUnit output is valid XML, and stopping a parallel run after a failure no longer inserts console text into a machine-readable stream. TAP escapes `#` in test names so a name containing `# SKIP` is not mistaken for a directive ([#1239](https://github.com/TypedDevs/bashunit/issues/1239), [#1243](https://github.com/TypedDevs/bashunit/issues/1243), [#1119](https://github.com/TypedDevs/bashunit/issues/1119)). + +For test authors, `assert_exec` can check an expected non-zero exit under `--strict`, literal backslashes survive comparison normalization, and a provider argument ending in a backslash reaches the test intact. The reference docs now explain lowercase `test_` names, positional installer arguments and how to give each provider row its own named snapshot. + +--- + +See the full changelog for [0.48.0](https://github.com/TypedDevs/bashunit/releases/tag/0.48.0) on GitHub. diff --git a/docs/blog/2026-08-16-release-0-49.md b/docs/blog/2026-08-16-release-0-49.md new file mode 100644 index 000000000..5aaa0367d --- /dev/null +++ b/docs/blog/2026-08-16-release-0-49.md @@ -0,0 +1,47 @@ +--- +date: '2026-08-16' +title: 'Release 0.49.0' +description: 'Choose how empty selections behave, inspect available tags and keep large suites from losing tests or slowing down during cleanup.' +coverAlt: 'Release 0.49.0 highlights' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.49.0 distinguishes an intentionally empty test selection from an invalid path. It also adds tag discovery and fixes resource handling that could stop large suites from executing all their tests. + +## Allow an empty selection deliberately + +By default, selecting no tests remains a failure. `--pass-with-no-tests` makes that case exit successfully while still printing “No tests found”. This is useful for an empty CI shard or a changed-files run with no matching tests ([#1263](https://github.com/TypedDevs/bashunit/issues/1263)). + +```bash +bashunit --changed origin/main --pass-with-no-tests tests/ +``` + +A nonexistent path is still an error. An explicitly empty directory also no longer falls back to `BASHUNIT_DEFAULT_PATH`, so the runner cannot pass a different suite from the one you requested. + +## Find the tags you can select + +`--list-tags` prints the selected files' tags in sorted order, without duplicates, and runs no tests: + +```bash +bashunit --list-tags tests/ +bashunit --tag slow tests/ +``` + +If a tag matches nothing, the runner now lists the tags it saw, or explains that no test carries one. That makes a spelling error easier to distinguish from an empty selection ([#1265](https://github.com/TypedDevs/bashunit/issues/1265)). + +## Keep large suites complete + +Sequential runs no longer leak a file descriptor per test file. The old leak could exhaust the limit, stop executing assertions and still exit successfully. A regression fixture with 120 files and a 120-descriptor limit previously ran only two assertions instead of 120 ([#1271](https://github.com/TypedDevs/bashunit/issues/1271)). + +Per-test cleanup also stops scanning the entire shared temporary directory. The recorded 100-test fixture fell from 978 ms to 542 ms with 5,000 leftovers present. Use `bashunit::temp_file` and `bashunit::temp_dir` for automatic cleanup; files written there by hand are no longer removed for you ([#1269](https://github.com/TypedDevs/bashunit/issues/1269)). + +Snapshot reporting and pruning now find snapshots left by deleted or renamed test files. They still leave snapshots belonging to existing files outside the current run alone. Review the listed paths before pruning: this release widens the set of orphaned snapshots it can remove ([#1194](https://github.com/TypedDevs/bashunit/issues/1194)). + +--- + +See the full changelog for [0.49.0](https://github.com/TypedDevs/bashunit/releases/tag/0.49.0) on GitHub. diff --git a/docs/blog/2026-08-18-release-0-50.md b/docs/blog/2026-08-18-release-0-50.md new file mode 100644 index 000000000..4d81bf030 --- /dev/null +++ b/docs/blog/2026-08-18-release-0-50.md @@ -0,0 +1,50 @@ +--- +date: '2026-08-18' +title: 'Release 0.50.0' +description: 'Safer handling of test filenames, clean report streams, simpler seed replay and faster startup and parallel reporting.' +coverAlt: 'Release 0.50.0 highlights' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.50.0 fixes a security problem in test-file handling and several cases where report consumers saw different results from the console. It also makes random-order replay simpler and removes the interactive tutorial. + +## Test filenames are no longer evaluated as shell code + +The per-test exit trap used to embed the test-file path in a string that Bash evaluated again when the trap ran. A filename containing a command substitution could therefore execute that command. This matters when CI checks out a branch whose filenames another contributor controls ([#1315](https://github.com/TypedDevs/bashunit/issues/1315)). + +The trap now treats the path as data. Such filenames no longer cause their tests to skip assertions and appear as risky results. Update projects that run tests over files from untrusted branches. + +## Replay a shuffle with just its seed + +`--seed` now implies random order. Copying the seed from a failing run is enough to replay the shuffle, unless you explicitly select another order ([#1287](https://github.com/TypedDevs/bashunit/issues/1287)). + +```bash +bashunit --seed 12345 tests/ +``` + +Snapshot updates also have a shorter spelling, `-u`: + +```bash +bashunit -u --filter test_render_status tests/ +``` + +## Reports agree with the run + +JSON and JUnit output no longer receive stray console text from empty parallel selections, script teardown, duplicate-function errors or worker stderr. Parallel reports count a file-level hook failure once, matching the console summary ([#1295](https://github.com/TypedDevs/bashunit/issues/1295), [#1297](https://github.com/TypedDevs/bashunit/issues/1297), [#1299](https://github.com/TypedDevs/bashunit/issues/1299), [#1301](https://github.com/TypedDevs/bashunit/issues/1301)). + +JUnit and Cobertura escape special characters in paths. Streaming TAP escapes `#` in descriptions, GitHub Actions annotations encode their property values, and a code fence in a failure message cannot truncate the Markdown summary. Benchmark files that fail to load or set up now make `bashunit bench` exit non-zero. + +The recorded parallel reporting workload runs about 1.9 times faster and uses about 1.8 times less CPU after removing repeated base64 processes. Startup also saves about 9 ms in the recorded measurement by loading the colour palette without a subprocess for each colour ([#1289](https://github.com/TypedDevs/bashunit/issues/1289), [#1285](https://github.com/TypedDevs/bashunit/issues/1285)). + +## Tutorial removal + +`bashunit learn` has been removed. Calling it explains the removal and points to [the documentation](/installation). Use the guides for learning and examples; the runner no longer ships the interactive tutorial subsystem. + +--- + +See the full changelog for [0.50.0](https://github.com/TypedDevs/bashunit/releases/tag/0.50.0) on GitHub. diff --git a/docs/blog/2026-08-22-release-0-50-1.md b/docs/blog/2026-08-22-release-0-50-1.md new file mode 100644 index 000000000..a0aa6dfd9 --- /dev/null +++ b/docs/blog/2026-08-22-release-0-50-1.md @@ -0,0 +1,36 @@ +--- +date: '2026-08-22' +title: 'Release 0.50.1' +description: 'Lifecycle cleanup runs after setup failures, timeouts and cancellation, and parallel annotation errors correctly fail the suite.' +coverAlt: 'Release 0.50.1 highlights' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.50.1 focuses on cleanup. Hooks now release resources across setup failures, early stops, invalid annotations and interrupted runs, with the same ownership boundaries in sequential and parallel execution. + +## File resources stay alive until their tests finish + +Under `--parallel`, `tear_down_after_script` now runs after its own file's tests instead of alongside them. A resource created by `set_up_before_script` therefore remains available while those tests read it ([#1320](https://github.com/TypedDevs/bashunit/issues/1320)). + +The same teardown runs when setup fails, when `--stop-on-failure` halts a sequential run, or when invalid `@timeout` or `@retry` metadata aborts a file. Benchmark files also run their teardown before aborting on a malformed annotation ([#1318](https://github.com/TypedDevs/bashunit/issues/1318), [#1321](https://github.com/TypedDevs/bashunit/issues/1321), [#1322](https://github.com/TypedDevs/bashunit/issues/1322), [#1329](https://github.com/TypedDevs/bashunit/issues/1329)). + +## Cleanup after interruption + +Ctrl-C reaches the interrupted run's script teardown. In parallel mode, it also reaches the teardown of a test in flight, through the worker that owns those hooks. A second Ctrl-C ends a sequential run even if cleanup does not return ([#1323](https://github.com/TypedDevs/bashunit/issues/1323), [#1331](https://github.com/TypedDevs/bashunit/issues/1331)). + +A test killed by `--test-timeout` receives a chance to run `tear_down`. That cleanup is bounded by the watchdog's grace period before it sends SIGKILL, so a hanging hook cannot extend the run indefinitely ([#1324](https://github.com/TypedDevs/bashunit/issues/1324)). + +Temporary files created at the top level with `bashunit::temp_file` are also swept when their test file fails to load. + +## Parallel errors reach CI + +Malformed timeout or retry annotations in a parallel worker now fail the overall run, even when another file passes. Previously the worker printed the error but the parent could still exit zero ([#1335](https://github.com/TypedDevs/bashunit/issues/1335)). This patch makes cleanup and the final verdict reflect what happened inside each file. + +--- + +See the full changelog for [0.50.1](https://github.com/TypedDevs/bashunit/releases/tag/0.50.1) on GitHub. diff --git a/docs/blog/2026-09-18-release-0-51.md b/docs/blog/2026-09-18-release-0-51.md new file mode 100644 index 000000000..f5feab0f7 --- /dev/null +++ b/docs/blog/2026-09-18-release-0-51.md @@ -0,0 +1,40 @@ +--- +date: '2026-09-18' +title: 'Release 0.51.0' +description: 'Less overhead for hooks and test discovery, more accurate multiline coverage and fixes for timeout cleanup and test-name filtering.' +coverAlt: 'Release 0.51.0 highlights' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.51.0 reduces the work surrounding each test while keeping Bash 3.0 as the compatibility floor. It also corrects coverage for multiline statements and several cases involving similar test names or cleanup after timeouts. + +## Faster hooks and counting + +Tests that define `set_up` or `tear_down` no longer create and remove extra output files for every hook. In a recorded macOS arm64, Bash 3.2 measurement, a test with hooks fell from 14.1 ms to 5.4 ms, about 2.6 times faster ([#1345](https://github.com/TypedDevs/bashunit/issues/1345)). + +Source locations are resolved when needed instead of through a subshell for every sequential test. In another measurement on the same platform, a 500-test file fell from 2.75 seconds to 2.40 seconds ([#1346](https://github.com/TypedDevs/bashunit/issues/1346)). + +The header count reuses information from the function scan for files it can count safely. Files with providers, heredocs, multiline strings or dynamic definitions retain the fallback that loads them. Across the repository's 241-file measurement, counting fell from 1.72 seconds to 1.51 seconds ([#1347](https://github.com/TypedDevs/bashunit/issues/1347)). + +Parallel runs on shells without `EPOCHREALTIME` also avoid probing the clock once per test. The 500-test regression fixture now executes Perl twice instead of 502 times. + +## More accurate coverage + +Coverage counts each line of multiline arrays, quoted strings, heredocs and continued statements. Previously an array spread across several lines could look partially uncovered, and on Bash 3.x could look entirely uncovered. Hits on a parent statement no longer mark commands inside substitutions as covered ([#1338](https://github.com/TypedDevs/bashunit/issues/1338)). + +## Test selection and cleanup fixes + +`test_a` and `test_ab` are no longer mistaken for duplicate definitions. An `--exclude-filter` value containing a comma stays one test name; repeat the option to exclude several names. The environment setting `BASHUNIT_EXCLUDE_FILTER` keeps its comma-separated behavior. + +Timed-out tests get a bounded opportunity to finish `tear_down`, with the watchdog waiting for the test body to exit rather than assuming a fixed short delay will always suffice. Parallel runs also stop replaying Bash's process-group warning as if it came from a test file ([#1344](https://github.com/TypedDevs/bashunit/issues/1344)). + +Internally, helpers can select an optimized implementation for a newer Bash once at load time while retaining the Bash 3.0 fallback. This does not raise the minimum supported version. + +--- + +See the full changelog for [0.51.0](https://github.com/TypedDevs/bashunit/releases/tag/0.51.0) on GitHub. diff --git a/docs/blog/2026-10-11-release-0-52.md b/docs/blog/2026-10-11-release-0-52.md new file mode 100644 index 000000000..de753b62c --- /dev/null +++ b/docs/blog/2026-10-11-release-0-52.md @@ -0,0 +1,36 @@ +--- +date: '2026-10-11' +title: 'Release 0.52.0' +description: 'Fewer processes in providers and reports, reliable parallel row results and cleanup, and shared contributor instructions for Claude Code and Codex.' +coverAlt: 'Release 0.52.0 highlights' + +aside: false +--- + +# {{ $frontmatter.title }} + + + +Release 0.52.0 reduces process overhead in data providers and report collection, then tightens the result and cleanup boundaries around parallel tests. Existing quoting, report values and argument behavior are preserved. + +## Less work between the tests + +Parallel reports collect worker results without starting a base64 process for every row. Data providers likewise pass arguments without a base64 process for each argument, preserving quoted and empty values and keeping the parser isolated ([#1371](https://github.com/TypedDevs/bashunit/issues/1371), [#1370](https://github.com/TypedDevs/bashunit/issues/1370)). + +JSON reports avoid a separate process for each ordinary filename, test name or empty message while retaining their escaping rules. Sequential multi-file runs also reuse provider and annotation metadata for unchanged test files up to 512 bytes; the cache is checked against the file's current contents before reuse ([#1369](https://github.com/TypedDevs/bashunit/issues/1369), [#1372](https://github.com/TypedDevs/bashunit/issues/1372)). + +## Every provider row keeps its own result + +Concurrent provider rows have separate owners for temporary files, including rows with identical arguments. Rows that run synchronously within a parallel run also retain separate results, so a later passing row cannot hide an earlier failure ([#1379](https://github.com/TypedDevs/bashunit/issues/1379), [#1377](https://github.com/TypedDevs/bashunit/issues/1377)). + +A late timeout signal no longer interrupts `tear_down`. The watchdog still bounds cleanup that hangs. Piped parallel output can also finish without waiting for an inactive spinner's sleep process ([#1376](https://github.com/TypedDevs/bashunit/issues/1376), [#1368](https://github.com/TypedDevs/bashunit/issues/1368)). + +## Shared contributor setup + +Repository contributor instructions now come from shared agnostic-ai specs, generated for Claude Code and Codex. The project pins the tool as an npm development dependency and routes task context and model tiers through those sources. Contributors edit `.agnostic-ai/` and regenerate the target files ([#1387](https://github.com/TypedDevs/bashunit/pull/1387)). + +Release automation also updates and commits both npm lockfiles' project versions and restores them during rollback. CI compatibility checks scan shell source files without treating generated instructions as executable code, and Linux installer acceptance jobs include their required build optimizer. + +--- + +See the full changelog for [0.52.0](https://github.com/TypedDevs/bashunit/releases/tag/0.52.0) on GitHub. From b9050bf311c6f471cf0aee2562f424e3b94cd183 Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Sun, 11 Oct 2026 21:59:45 +0200 Subject: [PATCH 2/2] docs: simplify release post wording --- docs/blog/2026-07-24-release-0-43.md | 18 +++++++++--------- docs/blog/2026-07-29-release-0-44.md | 22 +++++++++++----------- docs/blog/2026-08-09-release-0-45.md | 20 ++++++++++---------- docs/blog/2026-08-11-release-0-46.md | 22 +++++++++++----------- docs/blog/2026-08-13-release-0-47.md | 24 ++++++++++++------------ docs/blog/2026-08-14-release-0-48.md | 20 ++++++++++---------- docs/blog/2026-08-16-release-0-49.md | 20 ++++++++++---------- docs/blog/2026-08-18-release-0-50.md | 24 ++++++++++++------------ docs/blog/2026-08-22-release-0-50-1.md | 20 ++++++++++---------- docs/blog/2026-09-18-release-0-51.md | 24 ++++++++++++------------ docs/blog/2026-10-11-release-0-52.md | 20 ++++++++++---------- 11 files changed, 117 insertions(+), 117 deletions(-) diff --git a/docs/blog/2026-07-24-release-0-43.md b/docs/blog/2026-07-24-release-0-43.md index 1cd0b05e1..0de2b541d 100644 --- a/docs/blog/2026-07-24-release-0-43.md +++ b/docs/blog/2026-07-24-release-0-43.md @@ -1,8 +1,8 @@ --- date: '2026-07-24' title: 'Release 0.43.0' -description: 'Loop branch coverage and fewer subprocesses in assertions and parallel tests.' -coverAlt: 'Loop branch coverage and process reductions in string assertions and parallel workers' +description: 'See which loops your tests reach, with fewer extra processes during checks and parallel tests.' +coverAlt: 'Reports of loops reached by tests and fewer extra processes during checks' aside: false --- @@ -11,29 +11,29 @@ aside: false -Release 0.43.0 adds branch coverage for loops and reduces the number of processes started by assertions and parallel workers. Existing assertions keep their behavior, so the process changes do not require rewriting tests. +Release 0.43.0 reports whether your tests enter loops. It also reduces the extra processes started by checks, called assertions, and by tests running at the same time. Existing checks keep their behavior, so you do not need to rewrite tests. ## Find loops your tests never enter -Branch coverage now includes `while`, `until`, `for`, and `select`. Each loop body is represented as a single branch, covered when the loop runs at least once. A test that only exercises an empty input can therefore leave the loop body uncovered even when the surrounding function runs successfully ([#855](https://github.com/TypedDevs/bashunit/issues/855)). +The report now includes `while`, `until`, `for`, and `select` loops. Each loop body counts as one possible path through the code, called a branch. That path is marked reached when the loop runs at least once. A test with only empty input can leave the loop body untested even when the surrounding function runs successfully ([#855](https://github.com/TypedDevs/bashunit/issues/855)). ```bash bashunit tests/ --coverage --coverage-paths src/ ``` -For a function that processes a list, include both an empty-list case and a case with at least one item. The first checks what happens when the loop is skipped; the second reaches its body. The coverage report now makes the missing body case visible. It records whether the loop was entered, rather than reporting a separate branch for each iteration. +For a function that processes a list, include both an empty-list case and a case with at least one item. The first checks what happens when the loop is skipped; the second reaches its body. The report now makes that missing test case visible. It records whether the loop was entered, rather than treating each pass through the loop as a separate path. -## Fewer processes for the same assertions +## Fewer processes for the same checks -String assertions such as `assert_contains`, `assert_matches`, and the prefix and suffix checks no longer start a subshell to join their arguments. Array, date, duration, JSON, file, and folder assertions also resolve their failure labels without a command substitution. The labels and comparison behavior stay the same ([#844](https://github.com/TypedDevs/bashunit/issues/844)). +Text checks such as `assert_contains`, `assert_matches`, and checks of the start and end of a value no longer start an extra shell process to join their arguments. Checks of arrays, dates, durations, JSON, files, and folders also find their failure labels without starting a shell process to capture a value. The labels and comparisons stay the same ([#844](https://github.com/TypedDevs/bashunit/issues/844)). -Parallel workers now name result files using an ordinal assigned by the suite, replacing a temporary-file creation and rename for every test. Data-provider tests also avoid the argument-sanitizing pipeline previously used for those names. Result aggregation is unchanged ([#851](https://github.com/TypedDevs/bashunit/issues/851)). +Tests running at the same time now name result files using a sequence number assigned by the test run. This replaces creating and renaming a temporary file for every test. Tests supplied with different sets of input values also avoid the chain of commands previously used to make those inputs safe for filenames. Results are still collected in the same way ([#851](https://github.com/TypedDevs/bashunit/issues/851)). ```bash bashunit --parallel tests/ ``` -These changes reduce repeated process work as the number of assertions and tests grows, without introducing new options or changing how you invoke the suite. +These changes reduce repeated work as the number of checks and tests grows. They add no new options and do not change how you run the tests. --- diff --git a/docs/blog/2026-07-29-release-0-44.md b/docs/blog/2026-07-29-release-0-44.md index c8d620e98..af7897171 100644 --- a/docs/blog/2026-07-29-release-0-44.md +++ b/docs/blog/2026-07-29-release-0-44.md @@ -1,8 +1,8 @@ --- date: '2026-07-29' title: 'Release 0.44.0' -description: 'Custom assertion helpers, snapshot controls, clearer spy checks, and stricter configuration validation.' -coverAlt: 'Custom assertions, snapshot review controls, spy diagnostics and configuration validation' +description: 'Test your own checks, manage saved expected output, and catch command-tracking and setup mistakes.' +coverAlt: 'Testing custom checks, reviewing saved expected output and catching setup mistakes' aside: false --- @@ -11,13 +11,13 @@ aside: false -Release 0.44.0 gives custom assertions their own testing and documentation workflow. It also adds explicit snapshot controls and catches configuration mistakes that could previously produce misleading results. +Release 0.44.0 helps you test and document your own checks, called custom assertions. It also gives you more control over saved expected output and catches setup mistakes that could previously produce misleading results. -## Build and test custom assertions +## Build and test your own checks -`bashunit::assert_that` runs a command and records the assertion verdict in one call. `bashunit::assert_once` lets a composed assertion count and report once under its own label, rather than once for every inner check. Existing assertion totals stay unchanged unless you opt in ([#915](https://github.com/TypedDevs/bashunit/issues/915), [#917](https://github.com/TypedDevs/bashunit/issues/917)). +`bashunit::assert_that` runs a command and records whether the check passed in one call. `bashunit::assert_once` lets a check made of several smaller checks count and report once under its own label. Existing totals stay unchanged unless you choose to use it ([#915](https://github.com/TypedDevs/bashunit/issues/915), [#917](https://github.com/TypedDevs/bashunit/issues/917)). -The new `assert_assertion_passes`, `assert_assertion_fails`, and `assert_assertion_fails_with` helpers test what a custom assertion reports. They isolate its counters and output, so a deliberate failure does not fail the surrounding test ([#916](https://github.com/TypedDevs/bashunit/issues/916)). +The new `assert_assertion_passes`, `assert_assertion_fails`, and `assert_assertion_fails_with` helpers test what your check reports. They keep its counts and output separate, so an expected failure does not fail the surrounding test ([#916](https://github.com/TypedDevs/bashunit/issues/916)). ```bash function test_positive_assertion() { @@ -26,15 +26,15 @@ function test_positive_assertion() { } ``` -Here, `assert_positive_number` is your project's assertion. Load its bootstrap file to list its documentation alongside the built-in reference, or select only custom assertions with `--custom` ([#918](https://github.com/TypedDevs/bashunit/issues/918)). +Here, `assert_positive_number` is your project's check. Load the setup file that defines it to list its documentation alongside the built-in reference. Use `--custom` to list only your project's checks ([#918](https://github.com/TypedDevs/bashunit/issues/918)). ```bash bashunit doc --custom --boot tests/bootstrap.sh ``` -## Review snapshots deliberately +## Review saved expected output -Use `--snapshot-update` to re-record existing snapshots after an intentional change, optionally narrowing the run with `--filter`. Snapshots containing placeholders are left alone. In CI, `--no-snapshot-create` makes a missing snapshot fail instead of silently creating the first reference. `--snapshot-report-unused` lists leftovers from renamed or deleted tests without deleting anything, and requires a full run ([#900](https://github.com/TypedDevs/bashunit/issues/900), [#901](https://github.com/TypedDevs/bashunit/issues/901), [#902](https://github.com/TypedDevs/bashunit/issues/902)). +A snapshot is saved expected output that later runs compare against. Use `--snapshot-update` to replace existing snapshots after an intentional change, optionally narrowing the run with `--filter`. Snapshots containing markers for text you chose to ignore are left alone. In automated checks, `--no-snapshot-create` makes a missing snapshot fail instead of silently saving the first reference. `--snapshot-report-unused` lists leftovers from renamed or deleted tests without deleting anything. It requires a full run ([#900](https://github.com/TypedDevs/bashunit/issues/900), [#901](https://github.com/TypedDevs/bashunit/issues/901), [#902](https://github.com/TypedDevs/bashunit/issues/902)). ```bash bashunit tests/ --no-snapshot-create @@ -43,9 +43,9 @@ bashunit tests/ --snapshot-report-unused ## Catch mistakes before trusting a pass -Spy assertions now reject an unregistered command instead of treating it as a spy with zero calls. Per-argument comparisons distinguish one argument containing a space from two separate arguments, and failed call checks show the recorded calls. +A spy tracks calls to a command. Checks of those calls now reject a command that was never registered for tracking, instead of reporting zero calls. Comparing arguments one at a time distinguishes one argument containing a space from two separate arguments. Failed checks show the recorded calls. -Invalid options, numeric settings, and missing bootstrap or environment files now produce errors. Coverage also gains an `xtrace` engine on Bash 4.1 and later; automatic selection retains the trap engine on older shells. The supported Bash floor remains 3.0. +Invalid options, numeric settings, and missing setup or environment files now produce errors. Coverage, which reports how much code the tests reach, also gains an `xtrace` method of recording execution on Bash 4.1 and later. Automatic selection keeps the existing `trap` method on older shells. Bash 3.0 remains the minimum supported version. --- diff --git a/docs/blog/2026-08-09-release-0-45.md b/docs/blog/2026-08-09-release-0-45.md index f378200e5..26746ebb7 100644 --- a/docs/blog/2026-08-09-release-0-45.md +++ b/docs/blog/2026-08-09-release-0-45.md @@ -1,8 +1,8 @@ --- date: '2026-08-09' title: 'Release 0.45.0' -description: 'Symlink assertions, command arguments in boolean checks, named snapshots, and correctness fixes.' -coverAlt: 'Symlink checks, command assertions, named snapshots and corrected test results' +description: 'Check symbolic links and commands, save multiple expected outputs, and avoid misleading test results.' +coverAlt: 'Symbolic-link and command checks, saved expected outputs and corrected results' aside: false --- @@ -11,11 +11,11 @@ aside: false -Release 0.45.0 adds ways to check symbolic links, invoke commands through boolean assertions, and keep multiple snapshots in one test. It also fixes cases where malformed inputs or missing commands could produce misleading results. +Release 0.45.0 adds ways to check symbolic links, pass arguments to command checks, and save multiple expected outputs in one test. It also fixes cases where invalid inputs or missing commands could produce misleading results. ## Check the link itself -Most filesystem assertions follow a symbolic link to its target. The new `assert_is_symlink`, `assert_is_not_symlink`, and `assert_symlink_to` inspect the link itself, making them useful for scripts that maintain a current-release link ([#981](https://github.com/TypedDevs/bashunit/issues/981)). +A symbolic link is a path that points to another file or directory. Most file checks follow the link and check its target. The new `assert_is_symlink`, `assert_is_not_symlink`, and `assert_symlink_to` check the link itself. They are useful for scripts that keep a link pointing to the current release ([#981](https://github.com/TypedDevs/bashunit/issues/981)). ```bash function test_current_release_link() { @@ -24,7 +24,7 @@ function test_current_release_link() { } ``` -## Pass arguments directly to boolean assertions +## Pass arguments directly to command checks `assert_true` and `assert_false` now accept a command followed by its arguments. A single argument retains its previous meaning ([#994](https://github.com/TypedDevs/bashunit/issues/994)). @@ -35,15 +35,15 @@ function test_release_directory() { } ``` -Both assertions now fail when the command is unknown or not executable. A missing command is no longer accepted by `assert_false` as evidence that the intended condition was false; the failure message explains that the command could not run ([#982](https://github.com/TypedDevs/bashunit/issues/982)). +Both checks now fail when the command is unknown or cannot be executed. A missing command is no longer accepted by `assert_false` as evidence that the intended condition was false; the failure message explains that the command could not run ([#982](https://github.com/TypedDevs/bashunit/issues/982)). -## Keep snapshots distinct and results reliable +## Keep expected outputs separate and results reliable -Named snapshots let a test record more than one expected value. On a mismatch, bashunit shows the resolved snapshot path and the `--snapshot-update` hint. Absolute test paths now resolve snapshots correctly, and the fallback for snapshot placeholders checks the whole value when Perl is unavailable ([#986](https://github.com/TypedDevs/bashunit/issues/986), [#1002](https://github.com/TypedDevs/bashunit/issues/1002)). +Snapshots save expected output for comparison on later runs. Giving each snapshot a name lets a test save more than one expected value. When values differ, bashunit shows the snapshot file path and the `--snapshot-update` hint. Test paths starting from the filesystem root now find snapshots correctly. When Perl is unavailable, the alternative comparison checks the whole value, including any markers for text you chose to ignore ([#986](https://github.com/TypedDevs/bashunit/issues/986), [#1002](https://github.com/TypedDevs/bashunit/issues/1002)). -Input checks are stricter too: core comparison assertions reject missing arguments, date assertions reject unparseable values, and `assert_json_equals` rejects invalid JSON. Parallel runs retain results from same-named test files in different directories. +Input checks are stricter too. Core comparison checks reject missing arguments, date checks reject values they cannot read as dates, and `assert_json_equals` rejects invalid JSON. Runs with tests executing at the same time retain results from same-named test files in different directories. -Several existing checks avoid repeated processes, including literal snapshots, spy counters, case-insensitive containment, and common numeric-tolerance comparisons. The standalone build also omits source comments while preserving heredoc content and source markers. These changes keep the test-facing behavior intact while reducing work around it. +Several existing checks start fewer extra processes. These include snapshots without ignored-text markers, counters that track command calls, text searches that ignore letter case, and common comparisons that allow a small numeric difference. The single-file executable also omits source comments while keeping text blocks inside shell commands and markers identifying source files. These changes reduce extra work while preserving how the checks behave. --- diff --git a/docs/blog/2026-08-11-release-0-46.md b/docs/blog/2026-08-11-release-0-46.md index 2a70964c8..dd5571f67 100644 --- a/docs/blog/2026-08-11-release-0-46.md +++ b/docs/blog/2026-08-11-release-0-46.md @@ -1,8 +1,8 @@ --- date: '2026-08-11' title: 'Release 0.46.0' -description: 'Test selection, repeat runs and flaky outcomes, richer CI reports, and diff coverage.' -coverAlt: 'Changed-test selection, flaky-test detection, CI reports and coverage of changed lines' +description: 'Choose tests, find intermittent failures, and report results and changed-line coverage in automated checks.' +coverAlt: 'Selecting changed tests, finding intermittent failures and reporting changed lines reached by tests' aside: false --- @@ -11,39 +11,39 @@ aside: false -Release 0.46.0 makes it easier to choose a run, investigate intermittent failures, and publish results in CI. It also fixes reports that could contain zero tests after a parallel run. +Release 0.46.0 makes it easier to choose tests, investigate failures that happen only sometimes, and publish results from automated checks. It also fixes reports that could contain zero tests after running tests at the same time. ## Inspect and select a run -`--changed` selects test files Git reports as touched since a reference, including staged, unstaged, and untracked changes. It selects changed test files, rather than finding every test affected by a source-code change. Use `--list` to inspect the selected tests without executing them ([#1010](https://github.com/TypedDevs/bashunit/issues/1010), [#1007](https://github.com/TypedDevs/bashunit/issues/1007)). +`--changed` selects test files Git reports as changed since a chosen commit or branch. It includes changes prepared for a commit, other edits, and new files not yet tracked by Git. It selects changed test files, rather than finding every test affected by a source-code change. Use `--list` to inspect the selected tests without executing them ([#1010](https://github.com/TypedDevs/bashunit/issues/1010), [#1007](https://github.com/TypedDevs/bashunit/issues/1007)). ```bash bashunit tests/ --changed origin/main --list bashunit tests/ --list --list-format json ``` -Tag expressions support AND and NOT, while repeated `--tag` options keep their OR behavior. `--exclude-filter` excludes matching test names and takes precedence over inclusion. `--order-by defects` brings the previous run's failures to the front while still running the entire selected suite. +Tag expressions can require two tags together with AND or leave out a tag with NOT. Repeating `--tag` still selects tests that match any of those options. `--exclude-filter` excludes matching test names even when another option selected them. `--order-by defects` runs the previous failures first while still running every selected test. -## Look for intermittent failures +## Find tests that fail only sometimes -`--repeat` runs every selected test several times, reports an aggregate result, and identifies the failed iteration. Retry-assisted passes are now counted as flaky, with the first failure included in reports. They remain inside the pass total unless you request `--fail-on-flaky` ([#1013](https://github.com/TypedDevs/bashunit/issues/1013), [#1012](https://github.com/TypedDevs/bashunit/issues/1012)). +`--repeat` runs every selected test several times, reports one combined result, and identifies which repetition failed. Tests that pass only after a retry are now counted separately as flaky, with the first failure included in reports. They still count as passed, so the run can succeed. Use `--fail-on-flaky` to make those results fail the run ([#1013](https://github.com/TypedDevs/bashunit/issues/1013), [#1012](https://github.com/TypedDevs/bashunit/issues/1012)). ```bash bashunit tests/ --repeat 20 --filter flaky_candidate bashunit tests/ --retry 2 --fail-on-flaky ``` -## Bring useful reports into CI +## Publish useful reports from automated checks -JSON, TAP, HTML, and JUnit file reports now collect results correctly under `--parallel`. JUnit groups tests by file, includes captured output, and carries informative failure messages. Markdown summaries can populate the GitHub Actions step summary, and automatic Actions annotations point to the failing file and line ([#1004](https://github.com/TypedDevs/bashunit/issues/1004), [#1016](https://github.com/TypedDevs/bashunit/issues/1016)). +JSON, TAP, HTML, and JUnit file reports now collect results correctly under `--parallel`. JUnit groups tests by file, includes their recorded output, and carries informative failure messages. Markdown summaries can appear in the GitHub Actions step summary. Automatic error notices in Actions point to the failing file and line ([#1004](https://github.com/TypedDevs/bashunit/issues/1004), [#1016](https://github.com/TypedDevs/bashunit/issues/1016)). -Coverage gains Cobertura XML and `--coverage-diff`, which limits the coverage view and minimum-percentage check to changed lines: +Coverage reports which lines the tests reach. It gains the Cobertura XML format used by other automated-check tools. `--coverage-diff` limits the report and minimum-percentage check to changed lines: ```bash bashunit tests/ --coverage --coverage-diff origin/main --coverage-min 90 ``` -Coverage processing also avoids a process per classified source line. New numeric-range and command-availability assertions round out the release, alongside clearer handling of malformed numeric values and custom-assertion failures. +Preparing coverage reports also avoids starting an extra process to decide whether each source line can run. New checks test whether a number falls within a range and whether a command is available. Invalid numbers and failures from checks you define now receive clearer handling. --- diff --git a/docs/blog/2026-08-13-release-0-47.md b/docs/blog/2026-08-13-release-0-47.md index cceae45e5..52fd3f4a1 100644 --- a/docs/blog/2026-08-13-release-0-47.md +++ b/docs/blog/2026-08-13-release-0-47.md @@ -1,8 +1,8 @@ --- date: '2026-08-13' title: 'Release 0.47.0' -description: 'Reports on stdout, test annotations, named suites, sandboxed commands, and corrected coverage totals.' -coverAlt: 'Structured stdout reports, suite settings, sandbox checks and more complete coverage' +description: 'Pipe reports to other commands, reuse test settings, catch unexpected commands, and include untested files in coverage.' +coverAlt: 'Reports sent to other commands, reusable test settings and coverage including untested files' aside: false --- @@ -11,37 +11,37 @@ aside: false -Release 0.47.0 adds structured reports on stdout, reusable suite settings, and controls for individual tests. Coverage now includes tracked files that no test executed, which changes how you should interpret an upgrade's percentages. +Release 0.47.0 lets you send reports directly to other commands, reuse settings for groups of tests, and control individual tests. Coverage, which reports how much code the tests reach, now includes tracked files that no test ran. Keep that change in mind when comparing percentages after an upgrade. ## Send reports straight to another command -`--output json` and `--output junit` emit a report on stdout without requiring an intermediate report file. File reporters remain available alongside them ([#1018](https://github.com/TypedDevs/bashunit/issues/1018)). +`--output json` and `--output junit` write a report to the normal terminal output, which you can pipe to another command or redirect to a file. You do not need a temporary report file. The existing options that write reports to files remain available alongside them ([#1018](https://github.com/TypedDevs/bashunit/issues/1018)). ```bash bashunit tests/ --output json | jq '.summary' bashunit tests/ --output junit > report.xml ``` -Named `[suite:]` sections in `.bashunitrc` store paths and options. Use `--suite ` to select one or repeat the option to combine suites, and `--list-suites` to see available names ([#1021](https://github.com/TypedDevs/bashunit/issues/1021)). +Named `[suite:]` sections in `.bashunitrc` store paths and options for groups of tests. Use `--suite ` to select one group, repeat the option to combine groups, or use `--list-suites` to see available names ([#1021](https://github.com/TypedDevs/bashunit/issues/1021)). ```bash bashunit --list-suites bashunit --suite unit ``` -## Make test requirements explicit +## Give each test the settings it needs -Per-test `# @timeout`, `# @retry`, and `# @skip` annotations override run-wide settings. Malformed values stop the run instead of quietly falling back. The new conditional skip helpers both mark the test skipped and end it, replacing a separate `return` ([#1020](https://github.com/TypedDevs/bashunit/issues/1020), [#1019](https://github.com/TypedDevs/bashunit/issues/1019)). +The comments `# @timeout`, `# @retry`, and `# @skip` above a test set its time limit, retries, or skipped status. They override settings for the whole run. Invalid values stop the run instead of quietly using another setting. The new helpers for skipping a test under certain conditions both mark it skipped and end it, replacing a separate `return` ([#1020](https://github.com/TypedDevs/bashunit/issues/1020), [#1019](https://github.com/TypedDevs/bashunit/issues/1019)). -`--sandbox` fails a test that invokes an external command it did not mock; `--sandbox-allow` extends the baseline allowlist. For retry-loop tests, `bashunit::mock_sequence` returns successive answers and repeats the final answer when the sequence is exhausted ([#1022](https://github.com/TypedDevs/bashunit/issues/1022), [#1023](https://github.com/TypedDevs/bashunit/issues/1023)). +`--sandbox` fails a test that runs an external command it did not replace with a test-controlled response, except commands already allowed by default. `--sandbox-allow` adds more allowed commands. To test code that retries, `bashunit::mock_sequence` supplies a different answer on each call and repeats the final answer after all the listed answers have been used ([#1022](https://github.com/TypedDevs/bashunit/issues/1022), [#1023](https://github.com/TypedDevs/bashunit/issues/1023)). -## Read the corrected coverage denominator +## Include files no test reached -Previously, coverage considered only files a test executed. Now every file under `--coverage-paths` participates, with untouched files reported at zero coverage. Percentages may drop because the measurement includes more of the code. Diff coverage also includes changed files that no test ran, preventing a new untested file from escaping the minimum-percentage check ([#1053](https://github.com/TypedDevs/bashunit/issues/1053), [#1054](https://github.com/TypedDevs/bashunit/issues/1054)). +Previously, coverage considered only files a test ran. Now it includes every file under `--coverage-paths`, with untouched files reported at zero coverage. Percentages may drop because the report includes more of the code. Reports limited to changed lines also include changed files that no test ran. A new untested file therefore cannot escape the minimum-percentage check ([#1053](https://github.com/TypedDevs/bashunit/issues/1053), [#1054](https://github.com/TypedDevs/bashunit/issues/1054)). -Corrections to case-arm and function-span parsing also change reported coverage details. Report generation performs its classification and output work in one awk invocation per run rather than repeating shell loops and processes per file. +Fixes to how bashunit reads alternatives in `case` statements and finds where functions begin and end also change coverage details. Preparing the report now uses one call to `awk` per run to identify executable lines and write the output, rather than repeating shell loops and starting processes for each file. -Benchmark runs gain JSON and JUnit artifacts and median-based baseline comparisons. `--snapshot-prune` removes unused snapshots only after a full run without failures, printing each deleted path; partial runs cannot prune ([#1029](https://github.com/TypedDevs/bashunit/issues/1029), [#1030](https://github.com/TypedDevs/bashunit/issues/1030)). +Runs that measure execution time can now save JSON and JUnit reports and compare the middle timing sample, called the median, against a saved reference. `--snapshot-prune` removes unused snapshots, the files holding saved expected output, only after a full run without failures. It prints each deleted path. Runs that select only some tests cannot remove them ([#1029](https://github.com/TypedDevs/bashunit/issues/1029), [#1030](https://github.com/TypedDevs/bashunit/issues/1030)). --- diff --git a/docs/blog/2026-08-14-release-0-48.md b/docs/blog/2026-08-14-release-0-48.md index 1727ca87e..3bde3e7ca 100644 --- a/docs/blog/2026-08-14-release-0-48.md +++ b/docs/blog/2026-08-14-release-0-48.md @@ -1,7 +1,7 @@ --- date: '2026-08-14' title: 'Release 0.48.0' -description: 'Faster coverage reports, clearer errors and fixes that keep parallel runs and machine-readable output trustworthy.' +description: 'Faster coverage reports, clearer errors and fixes for missing tests and unreadable reports.' coverAlt: 'Release 0.48.0 highlights' aside: false @@ -11,27 +11,27 @@ aside: false -Release 0.48.0 improves coverage speed and the errors that explain why a run did not execute as expected. It also fixes cases where parallel execution could report success while silently missing tests. +Release 0.48.0 makes coverage reports faster and explains more clearly why a run failed. It also fixes cases where running tests at the same time could report success while silently missing tests. ## Faster coverage and HTML reports -Coverage processing avoids repeated work when reading hits and classifying source lines. In the repository's recorded measurements, a coverage run fell from 16.2 seconds to 2.9 seconds, while generating an HTML report for 128 files fell from 58.7 seconds to 3.1 seconds ([#1092](https://github.com/TypedDevs/bashunit/issues/1092), [#1117](https://github.com/TypedDevs/bashunit/issues/1117)). Those are measurements of those workloads, rather than a promised speedup for every project. +Coverage reports show which lines of code your tests ran. bashunit now does less repeated work when reading those results. In measurements of this repository, a coverage run fell from 16.2 seconds to 2.9 seconds, while creating an HTML report for 128 files fell from 58.7 seconds to 3.1 seconds ([#1092](https://github.com/TypedDevs/bashunit/issues/1092), [#1117](https://github.com/TypedDevs/bashunit/issues/1117)). Other projects will have different timings. -The HTML test report now includes a Failures section with the test name, source location and message. Its summary includes risky and flaky outcomes, and test titles are escaped before they enter the markup ([#1251](https://github.com/TypedDevs/bashunit/issues/1251), [#1252](https://github.com/TypedDevs/bashunit/issues/1252), [#1249](https://github.com/TypedDevs/bashunit/issues/1249)). Coverage reports also handle filenames containing `|`, `<` or `&`. +The HTML test report now includes a Failures section with each failed test's name, file, line and message. It also counts risky tests (which may not have checked anything) and flaky tests (which passed only after a retry). Special characters in test titles are written safely so they cannot become HTML code ([#1251](https://github.com/TypedDevs/bashunit/issues/1251), [#1252](https://github.com/TypedDevs/bashunit/issues/1252), [#1249](https://github.com/TypedDevs/bashunit/issues/1249)). Coverage reports also handle filenames containing `|`, `<` or `&`. -On Bash 3.x, `--verbose` explains that coverage cannot count lines executed inside subshells. Hits inside command substitutions are preserved on supported newer shells, so their work no longer disappears from the result ([#1112](https://github.com/TypedDevs/bashunit/issues/1112), [#1101](https://github.com/TypedDevs/bashunit/issues/1101)). +On Bash 3.x, `--verbose` explains that coverage cannot count code run in a separate shell process. On supported newer shells, coverage now keeps the results from commands run inside `$(...)` instead of losing them ([#1112](https://github.com/TypedDevs/bashunit/issues/1112), [#1101](https://github.com/TypedDevs/bashunit/issues/1101)). ## Missing tests become visible failures -Duplicate test functions are detected in parallel runs again. An undefined data provider, or one that returns no rows, now produces an error naming the provider instead of making the test vanish behind “No tests found” ([#1147](https://github.com/TypedDevs/bashunit/issues/1147), [#1145](https://github.com/TypedDevs/bashunit/issues/1145)). +Repeated test-function names are detected when tests run at the same time. A data provider, the function that supplies inputs for a test, now produces a named error if it is missing or returns no inputs. The test no longer disappears behind “No tests found” ([#1147](https://github.com/TypedDevs/bashunit/issues/1147), [#1145](https://github.com/TypedDevs/bashunit/issues/1145)). -Bootstrap failures exit non-zero wherever a bootstrap is loaded. A report destination that is a directory fails with a clear message, and a benchmark path with no benchmarks also exits non-zero. These failures can now reach CI instead of looking like a passing run. +A setup file that fails to load now makes the run fail wherever that file is needed. Trying to write a report to a folder gives a clear error. Asking for a speed measurement where there are no benchmark functions also fails. Automated checks can now catch these problems instead of treating them as successful runs. -## Output that other tools can read +## Reports that other tools can read -JUnit output is valid XML, and stopping a parallel run after a failure no longer inserts console text into a machine-readable stream. TAP escapes `#` in test names so a name containing `# SKIP` is not mistaken for a directive ([#1239](https://github.com/TypedDevs/bashunit/issues/1239), [#1243](https://github.com/TypedDevs/bashunit/issues/1243), [#1119](https://github.com/TypedDevs/bashunit/issues/1119)). +JUnit reports now contain valid XML. Stopping a parallel run after a failure no longer mixes terminal messages into reports read by other tools. TAP, another test-report format, handles `#` in names so `# SKIP` cannot accidentally make a test look skipped ([#1239](https://github.com/TypedDevs/bashunit/issues/1239), [#1243](https://github.com/TypedDevs/bashunit/issues/1243), [#1119](https://github.com/TypedDevs/bashunit/issues/1119)). -For test authors, `assert_exec` can check an expected non-zero exit under `--strict`, literal backslashes survive comparison normalization, and a provider argument ending in a backslash reaches the test intact. The reference docs now explain lowercase `test_` names, positional installer arguments and how to give each provider row its own named snapshot. +`assert_exec` can now check a command that is expected to fail even with `--strict`. Comparisons preserve literal backslashes, and a supplied test input ending in a backslash reaches the test unchanged. The docs also explain lowercase `test_` names, passing installer options by position, and giving each set of test inputs its own saved expected output. --- diff --git a/docs/blog/2026-08-16-release-0-49.md b/docs/blog/2026-08-16-release-0-49.md index 5aaa0367d..48f26d7d1 100644 --- a/docs/blog/2026-08-16-release-0-49.md +++ b/docs/blog/2026-08-16-release-0-49.md @@ -1,7 +1,7 @@ --- date: '2026-08-16' title: 'Release 0.49.0' -description: 'Choose how empty selections behave, inspect available tags and keep large suites from losing tests or slowing down during cleanup.' +description: 'Choose when an empty run is allowed, list available tags and keep large test runs complete.' coverAlt: 'Release 0.49.0 highlights' aside: false @@ -11,17 +11,17 @@ aside: false -Release 0.49.0 distinguishes an intentionally empty test selection from an invalid path. It also adds tag discovery and fixes resource handling that could stop large suites from executing all their tests. +Release 0.49.0 distinguishes a run with no matching tests from a path that does not exist. It also lists available tags and fixes problems that could stop a large test run before all its tests had executed. -## Allow an empty selection deliberately +## Allow a run with no tests deliberately -By default, selecting no tests remains a failure. `--pass-with-no-tests` makes that case exit successfully while still printing “No tests found”. This is useful for an empty CI shard or a changed-files run with no matching tests ([#1263](https://github.com/TypedDevs/bashunit/issues/1263)). +By default, finding no tests remains a failure. `--pass-with-no-tests` allows that case to succeed while still printing “No tests found”. This helps when automated checks split tests across machines and one machine has none to run, or when none of the changed files contain tests ([#1263](https://github.com/TypedDevs/bashunit/issues/1263)). ```bash bashunit --changed origin/main --pass-with-no-tests tests/ ``` -A nonexistent path is still an error. An explicitly empty directory also no longer falls back to `BASHUNIT_DEFAULT_PATH`, so the runner cannot pass a different suite from the one you requested. +A path that does not exist is still an error. An empty folder you explicitly select also no longer makes bashunit run `BASHUNIT_DEFAULT_PATH` instead. The runner cannot report success for a different set of tests from the one you requested. ## Find the tags you can select @@ -32,15 +32,15 @@ bashunit --list-tags tests/ bashunit --tag slow tests/ ``` -If a tag matches nothing, the runner now lists the tags it saw, or explains that no test carries one. That makes a spelling error easier to distinguish from an empty selection ([#1265](https://github.com/TypedDevs/bashunit/issues/1265)). +If a tag matches nothing, bashunit lists the tags it saw, or explains that no test has one. That makes a spelling mistake easier to distinguish from a run with no matching tests ([#1265](https://github.com/TypedDevs/bashunit/issues/1265)). -## Keep large suites complete +## Keep large test runs complete -Sequential runs no longer leak a file descriptor per test file. The old leak could exhaust the limit, stop executing assertions and still exit successfully. A regression fixture with 120 files and a 120-descriptor limit previously ran only two assertions instead of 120 ([#1271](https://github.com/TypedDevs/bashunit/issues/1271)). +When running files one after another, bashunit now closes the file handles it uses. Previously those handles could reach the system limit, after which tests stopped checking results even though the run still reported success. In a test case with 120 files and a limit of 120 open handles, only two checks ran instead of 120 ([#1271](https://github.com/TypedDevs/bashunit/issues/1271)). -Per-test cleanup also stops scanning the entire shared temporary directory. The recorded 100-test fixture fell from 978 ms to 542 ms with 5,000 leftovers present. Use `bashunit::temp_file` and `bashunit::temp_dir` for automatic cleanup; files written there by hand are no longer removed for you ([#1269](https://github.com/TypedDevs/bashunit/issues/1269)). +Cleanup after each test also stops searching the entire shared temporary folder. The recorded 100-test example fell from 978 ms to 542 ms with 5,000 leftover files present. Use `bashunit::temp_file` and `bashunit::temp_dir` for automatic cleanup; files written there by hand are no longer removed for you ([#1269](https://github.com/TypedDevs/bashunit/issues/1269)). -Snapshot reporting and pruning now find snapshots left by deleted or renamed test files. They still leave snapshots belonging to existing files outside the current run alone. Review the listed paths before pruning: this release widens the set of orphaned snapshots it can remove ([#1194](https://github.com/TypedDevs/bashunit/issues/1194)). +Snapshot files store expected test output. The commands that list or remove unused snapshots now find ones left by deleted or renamed test files. They still leave snapshots belonging to existing files outside the current run alone. Review the listed paths before deleting them: this release can remove more unused snapshots than earlier versions ([#1194](https://github.com/TypedDevs/bashunit/issues/1194)). --- diff --git a/docs/blog/2026-08-18-release-0-50.md b/docs/blog/2026-08-18-release-0-50.md index 4d81bf030..04703044e 100644 --- a/docs/blog/2026-08-18-release-0-50.md +++ b/docs/blog/2026-08-18-release-0-50.md @@ -1,7 +1,7 @@ --- date: '2026-08-18' title: 'Release 0.50.0' -description: 'Safer handling of test filenames, clean report streams, simpler seed replay and faster startup and parallel reporting.' +description: 'Safer test filenames, readable reports, easier replay of random test order and faster test runs.' coverAlt: 'Release 0.50.0 highlights' aside: false @@ -11,23 +11,23 @@ aside: false -Release 0.50.0 fixes a security problem in test-file handling and several cases where report consumers saw different results from the console. It also makes random-order replay simpler and removes the interactive tutorial. +Release 0.50.0 fixes a security problem with test filenames and cases where reports disagreed with the terminal summary. It also makes random test order easier to repeat and removes the interactive tutorial. -## Test filenames are no longer evaluated as shell code +## Test filenames cannot become commands -The per-test exit trap used to embed the test-file path in a string that Bash evaluated again when the trap ran. A filename containing a command substitution could therefore execute that command. This matters when CI checks out a branch whose filenames another contributor controls ([#1315](https://github.com/TypedDevs/bashunit/issues/1315)). +The cleanup command run at the end of each test used to store the test-file path as Bash code. Bash read that code again when the test finished. A filename containing `$(...)` could therefore run a command. This matters when automated checks run tests from a branch whose filenames another contributor controls ([#1315](https://github.com/TypedDevs/bashunit/issues/1315)). -The trap now treats the path as data. Such filenames no longer cause their tests to skip assertions and appear as risky results. Update projects that run tests over files from untrusted branches. +Bash now treats the filename as text. These names also no longer prevent the test's checks from running and make it appear risky, the label used when a test may not have checked anything. Update projects that run tests from untrusted branches. -## Replay a shuffle with just its seed +## Repeat a random order with its seed -`--seed` now implies random order. Copying the seed from a failing run is enough to replay the shuffle, unless you explicitly select another order ([#1287](https://github.com/TypedDevs/bashunit/issues/1287)). +A seed is the number used to reproduce a random test order. Passing `--seed` now selects that random order automatically. Copying the seed from a failing run is enough to repeat its order, unless you explicitly choose another order ([#1287](https://github.com/TypedDevs/bashunit/issues/1287)). ```bash bashunit --seed 12345 tests/ ``` -Snapshot updates also have a shorter spelling, `-u`: +Snapshots save expected test output for later comparison. Updating them also has a shorter spelling, `-u`: ```bash bashunit -u --filter test_render_status tests/ @@ -35,15 +35,15 @@ bashunit -u --filter test_render_status tests/ ## Reports agree with the run -JSON and JUnit output no longer receive stray console text from empty parallel selections, script teardown, duplicate-function errors or worker stderr. Parallel reports count a file-level hook failure once, matching the console summary ([#1295](https://github.com/TypedDevs/bashunit/issues/1295), [#1297](https://github.com/TypedDevs/bashunit/issues/1297), [#1299](https://github.com/TypedDevs/bashunit/issues/1299), [#1301](https://github.com/TypedDevs/bashunit/issues/1301)). +JSON and JUnit reports no longer contain stray terminal text when a parallel run selects no tests, finishes file cleanup, finds repeated function names or reports a command error. Reports also count a failed file setup or cleanup step once, matching the terminal summary ([#1295](https://github.com/TypedDevs/bashunit/issues/1295), [#1297](https://github.com/TypedDevs/bashunit/issues/1297), [#1299](https://github.com/TypedDevs/bashunit/issues/1299), [#1301](https://github.com/TypedDevs/bashunit/issues/1301)). -JUnit and Cobertura escape special characters in paths. Streaming TAP escapes `#` in descriptions, GitHub Actions annotations encode their property values, and a code fence in a failure message cannot truncate the Markdown summary. Benchmark files that fail to load or set up now make `bashunit bench` exit non-zero. +Special characters in paths no longer break JUnit or Cobertura, the XML formats used for test and coverage reports. TAP reports sent directly to the terminal handle `#` in test descriptions. GitHub Actions error messages safely include special characters in titles and paths, and Markdown summaries handle failure messages that contain triple backticks. Benchmark files that fail to load or set up now make `bashunit bench` report failure. -The recorded parallel reporting workload runs about 1.9 times faster and uses about 1.8 times less CPU after removing repeated base64 processes. Startup also saves about 9 ms in the recorded measurement by loading the colour palette without a subprocess for each colour ([#1289](https://github.com/TypedDevs/bashunit/issues/1289), [#1285](https://github.com/TypedDevs/bashunit/issues/1285)). +The recorded parallel reporting example runs about 1.9 times faster and uses about 1.8 times less processor time after removing repeated calls to base64, the tool used to encode report values. Startup saves about 9 ms in the recorded measurement because loading the display colours no longer starts an extra program for each colour ([#1289](https://github.com/TypedDevs/bashunit/issues/1289), [#1285](https://github.com/TypedDevs/bashunit/issues/1285)). ## Tutorial removal -`bashunit learn` has been removed. Calling it explains the removal and points to [the documentation](/installation). Use the guides for learning and examples; the runner no longer ships the interactive tutorial subsystem. +`bashunit learn` has been removed. Calling it explains the removal and points to [the documentation](/installation). The guides provide learning material and examples; the runner no longer includes the interactive tutorial. --- diff --git a/docs/blog/2026-08-22-release-0-50-1.md b/docs/blog/2026-08-22-release-0-50-1.md index a0aa6dfd9..70b7d8c55 100644 --- a/docs/blog/2026-08-22-release-0-50-1.md +++ b/docs/blog/2026-08-22-release-0-50-1.md @@ -1,7 +1,7 @@ --- date: '2026-08-22' title: 'Release 0.50.1' -description: 'Lifecycle cleanup runs after setup failures, timeouts and cancellation, and parallel annotation errors correctly fail the suite.' +description: 'Cleanup runs after setup failures, time limits and interruptions, and invalid test settings correctly fail the run.' coverAlt: 'Release 0.50.1 highlights' aside: false @@ -11,25 +11,25 @@ aside: false -Release 0.50.1 focuses on cleanup. Hooks now release resources across setup failures, early stops, invalid annotations and interrupted runs, with the same ownership boundaries in sequential and parallel execution. +Release 0.50.1 focuses on cleanup. Setup and cleanup functions now release resources after failures, early stops, invalid test settings and interrupted runs. This works both when tests run one after another and when they run at the same time. -## File resources stay alive until their tests finish +## Shared files stay available until their tests finish -Under `--parallel`, `tear_down_after_script` now runs after its own file's tests instead of alongside them. A resource created by `set_up_before_script` therefore remains available while those tests read it ([#1320](https://github.com/TypedDevs/bashunit/issues/1320)). +With `--parallel`, `tear_down_after_script` now runs after all tests in its own file finish. A file or other resource created by `set_up_before_script` therefore stays available while those tests use it ([#1320](https://github.com/TypedDevs/bashunit/issues/1320)). -The same teardown runs when setup fails, when `--stop-on-failure` halts a sequential run, or when invalid `@timeout` or `@retry` metadata aborts a file. Benchmark files also run their teardown before aborting on a malformed annotation ([#1318](https://github.com/TypedDevs/bashunit/issues/1318), [#1321](https://github.com/TypedDevs/bashunit/issues/1321), [#1322](https://github.com/TypedDevs/bashunit/issues/1322), [#1329](https://github.com/TypedDevs/bashunit/issues/1329)). +The same cleanup function runs when setup fails, when `--stop-on-failure` ends a sequential run, or when invalid `@timeout` or `@retry` settings stop a test file. Benchmark files also run their cleanup function before stopping because of an invalid test setting ([#1318](https://github.com/TypedDevs/bashunit/issues/1318), [#1321](https://github.com/TypedDevs/bashunit/issues/1321), [#1322](https://github.com/TypedDevs/bashunit/issues/1322), [#1329](https://github.com/TypedDevs/bashunit/issues/1329)). ## Cleanup after interruption -Ctrl-C reaches the interrupted run's script teardown. In parallel mode, it also reaches the teardown of a test in flight, through the worker that owns those hooks. A second Ctrl-C ends a sequential run even if cleanup does not return ([#1323](https://github.com/TypedDevs/bashunit/issues/1323), [#1331](https://github.com/TypedDevs/bashunit/issues/1331)). +Ctrl-C runs the interrupted file's cleanup function. When tests run at the same time, it also runs the cleanup for a test still in progress. The shell process responsible for those tests handles the interruption. A second Ctrl-C ends a sequential run even if cleanup does not finish ([#1323](https://github.com/TypedDevs/bashunit/issues/1323), [#1331](https://github.com/TypedDevs/bashunit/issues/1331)). -A test killed by `--test-timeout` receives a chance to run `tear_down`. That cleanup is bounded by the watchdog's grace period before it sends SIGKILL, so a hanging hook cannot extend the run indefinitely ([#1324](https://github.com/TypedDevs/bashunit/issues/1324)). +A test stopped by `--test-timeout` gets a chance to run `tear_down`. There is still a time limit on cleanup before bashunit forcibly stops it, so a cleanup function that hangs cannot keep the run open indefinitely ([#1324](https://github.com/TypedDevs/bashunit/issues/1324)). -Temporary files created at the top level with `bashunit::temp_file` are also swept when their test file fails to load. +Temporary files created outside a test function with `bashunit::temp_file` are also removed when their test file fails to load. -## Parallel errors reach CI +## Errors reach automated checks -Malformed timeout or retry annotations in a parallel worker now fail the overall run, even when another file passes. Previously the worker printed the error but the parent could still exit zero ([#1335](https://github.com/TypedDevs/bashunit/issues/1335)). This patch makes cleanup and the final verdict reflect what happened inside each file. +Invalid timeout or retry settings now fail the overall parallel run, even when another file passes. Previously one test process could print the error while the main process still reported success ([#1335](https://github.com/TypedDevs/bashunit/issues/1335)). Cleanup and the final result now reflect what happened in each file. --- diff --git a/docs/blog/2026-09-18-release-0-51.md b/docs/blog/2026-09-18-release-0-51.md index f5feab0f7..adf0d0ea2 100644 --- a/docs/blog/2026-09-18-release-0-51.md +++ b/docs/blog/2026-09-18-release-0-51.md @@ -1,7 +1,7 @@ --- date: '2026-09-18' title: 'Release 0.51.0' -description: 'Less overhead for hooks and test discovery, more accurate multiline coverage and fixes for timeout cleanup and test-name filtering.' +description: 'Faster setup and cleanup, more accurate coverage and fixes for test names and time limits.' coverAlt: 'Release 0.51.0 highlights' aside: false @@ -11,29 +11,29 @@ aside: false -Release 0.51.0 reduces the work surrounding each test while keeping Bash 3.0 as the compatibility floor. It also corrects coverage for multiline statements and several cases involving similar test names or cleanup after timeouts. +Release 0.51.0 reduces the work around each test and still supports Bash 3.0. It also corrects coverage, which shows the code your tests ran, for statements spread across several lines. Similar test names and cleanup after a time limit work more reliably too. -## Faster hooks and counting +## Faster setup, cleanup and test counting -Tests that define `set_up` or `tear_down` no longer create and remove extra output files for every hook. In a recorded macOS arm64, Bash 3.2 measurement, a test with hooks fell from 14.1 ms to 5.4 ms, about 2.6 times faster ([#1345](https://github.com/TypedDevs/bashunit/issues/1345)). +Tests that define `set_up` or `tear_down` no longer create and remove extra output files for each call. In a recorded measurement on a Mac with an ARM processor and Bash 3.2, a test using these functions fell from 14.1 ms to 5.4 ms, about 2.6 times faster ([#1345](https://github.com/TypedDevs/bashunit/issues/1345)). -Source locations are resolved when needed instead of through a subshell for every sequential test. In another measurement on the same platform, a 500-test file fell from 2.75 seconds to 2.40 seconds ([#1346](https://github.com/TypedDevs/bashunit/issues/1346)). +bashunit now looks up a test's file and line only when needed instead of starting a separate shell for every test run in sequence. In another measurement on the same platform, a 500-test file fell from 2.75 seconds to 2.40 seconds ([#1346](https://github.com/TypedDevs/bashunit/issues/1346)). -The header count reuses information from the function scan for files it can count safely. Files with providers, heredocs, multiline strings or dynamic definitions retain the fallback that loads them. Across the repository's 241-file measurement, counting fell from 1.72 seconds to 1.51 seconds ([#1347](https://github.com/TypedDevs/bashunit/issues/1347)). +To show the number of tests before a run, bashunit reuses information it already found while reading test functions. Files whose test count needs more work are still loaded as before. These include files that supply several sets of test inputs, contain text spread across lines, or create functions while they run. Across the repository's 241-file measurement, counting fell from 1.72 seconds to 1.51 seconds ([#1347](https://github.com/TypedDevs/bashunit/issues/1347)). -Parallel runs on shells without `EPOCHREALTIME` also avoid probing the clock once per test. The 500-test regression fixture now executes Perl twice instead of 502 times. +When Bash cannot read the clock directly through `EPOCHREALTIME`, parallel runs also stop checking which clock to use for every test. The 500-test check now starts Perl twice instead of 502 times. ## More accurate coverage -Coverage counts each line of multiline arrays, quoted strings, heredocs and continued statements. Previously an array spread across several lines could look partially uncovered, and on Bash 3.x could look entirely uncovered. Hits on a parent statement no longer mark commands inside substitutions as covered ([#1338](https://github.com/TypedDevs/bashunit/issues/1338)). +Coverage counts every line of arrays, quoted text, blocks of text written with `<<`, and commands continued onto another line. Previously an array spread across several lines could look partly untested, and on Bash 3.x could look entirely untested. Running an outer command also no longer marks commands inside `$(...)` or `<(...)` as tested unless they ran ([#1338](https://github.com/TypedDevs/bashunit/issues/1338)). -## Test selection and cleanup fixes +## Test names and cleanup fixes -`test_a` and `test_ab` are no longer mistaken for duplicate definitions. An `--exclude-filter` value containing a comma stays one test name; repeat the option to exclude several names. The environment setting `BASHUNIT_EXCLUDE_FILTER` keeps its comma-separated behavior. +`test_a` and `test_ab` are no longer mistaken for the same function defined twice. An `--exclude-filter` value containing a comma stays one test name; repeat the option to exclude several names. The environment setting `BASHUNIT_EXCLUDE_FILTER` still uses commas to separate names. -Timed-out tests get a bounded opportunity to finish `tear_down`, with the watchdog waiting for the test body to exit rather than assuming a fixed short delay will always suffice. Parallel runs also stop replaying Bash's process-group warning as if it came from a test file ([#1344](https://github.com/TypedDevs/bashunit/issues/1344)). +Tests that reach their time limit get a limited chance to finish `tear_down`. bashunit waits for the test itself to exit rather than assuming a short fixed delay is always enough. Parallel runs also stop displaying Bash's warning about grouping running processes as though a test file had printed it ([#1344](https://github.com/TypedDevs/bashunit/issues/1344)). -Internally, helpers can select an optimized implementation for a newer Bash once at load time while retaining the Bash 3.0 fallback. This does not raise the minimum supported version. +Helpers can now choose faster code for a newer Bash when loaded, while keeping the existing code for Bash 3.0. The minimum supported version stays the same. --- diff --git a/docs/blog/2026-10-11-release-0-52.md b/docs/blog/2026-10-11-release-0-52.md index de753b62c..30aa00997 100644 --- a/docs/blog/2026-10-11-release-0-52.md +++ b/docs/blog/2026-10-11-release-0-52.md @@ -1,7 +1,7 @@ --- date: '2026-10-11' title: 'Release 0.52.0' -description: 'Fewer processes in providers and reports, reliable parallel row results and cleanup, and shared contributor instructions for Claude Code and Codex.' +description: 'Less work when supplying test inputs and writing reports, reliable parallel results and cleanup, and shared contributor instructions.' coverAlt: 'Release 0.52.0 highlights' aside: false @@ -11,25 +11,25 @@ aside: false -Release 0.52.0 reduces process overhead in data providers and report collection, then tightens the result and cleanup boundaries around parallel tests. Existing quoting, report values and argument behavior are preserved. +Release 0.52.0 does less work when reading test inputs and collecting reports. It also keeps separate test results and cleanup working correctly when tests run at the same time. Quoted inputs, empty values and report contents keep their existing behavior. -## Less work between the tests +## Less work between tests -Parallel reports collect worker results without starting a base64 process for every row. Data providers likewise pass arguments without a base64 process for each argument, preserving quoted and empty values and keeping the parser isolated ([#1371](https://github.com/TypedDevs/bashunit/issues/1371), [#1370](https://github.com/TypedDevs/bashunit/issues/1370)). +Parallel reports no longer start base64, the tool used to encode values, separately for each result. Data providers, functions that supply several sets of inputs to a test, also avoid calling it for each argument. Quotes and empty values are preserved. Reading those arguments still happens in a separate shell so it cannot change the main shell's state ([#1371](https://github.com/TypedDevs/bashunit/issues/1371), [#1370](https://github.com/TypedDevs/bashunit/issues/1370)). -JSON reports avoid a separate process for each ordinary filename, test name or empty message while retaining their escaping rules. Sequential multi-file runs also reuse provider and annotation metadata for unchanged test files up to 512 bytes; the cache is checked against the file's current contents before reuse ([#1369](https://github.com/TypedDevs/bashunit/issues/1369), [#1372](https://github.com/TypedDevs/bashunit/issues/1372)). +JSON reports avoid starting an extra program for each ordinary filename, test name or empty message. Special characters are still written safely. When running files one after another, bashunit also reuses saved information about test inputs and settings for unchanged files up to 512 bytes. It checks that the file still has the same contents before reusing that information ([#1369](https://github.com/TypedDevs/bashunit/issues/1369), [#1372](https://github.com/TypedDevs/bashunit/issues/1372)). -## Every provider row keeps its own result +## Each set of inputs keeps its own result -Concurrent provider rows have separate owners for temporary files, including rows with identical arguments. Rows that run synchronously within a parallel run also retain separate results, so a later passing row cannot hide an earlier failure ([#1379](https://github.com/TypedDevs/bashunit/issues/1379), [#1377](https://github.com/TypedDevs/bashunit/issues/1377)). +When test cases run at the same time, each manages its own temporary files, even if their arguments are identical. Cases that run one after another inside a parallel run also keep separate results, so a later passing case cannot hide an earlier failure ([#1379](https://github.com/TypedDevs/bashunit/issues/1379), [#1377](https://github.com/TypedDevs/bashunit/issues/1377)). -A late timeout signal no longer interrupts `tear_down`. The watchdog still bounds cleanup that hangs. Piped parallel output can also finish without waiting for an inactive spinner's sleep process ([#1376](https://github.com/TypedDevs/bashunit/issues/1376), [#1368](https://github.com/TypedDevs/bashunit/issues/1368)). +A request to stop a test that arrives late no longer interrupts `tear_down`. Cleanup still has a time limit if it hangs. Sending parallel output to another command also no longer waits for the unused progress indicator to finish sleeping ([#1376](https://github.com/TypedDevs/bashunit/issues/1376), [#1368](https://github.com/TypedDevs/bashunit/issues/1368)). ## Shared contributor setup -Repository contributor instructions now come from shared agnostic-ai specs, generated for Claude Code and Codex. The project pins the tool as an npm development dependency and routes task context and model tiers through those sources. Contributors edit `.agnostic-ai/` and regenerate the target files ([#1387](https://github.com/TypedDevs/bashunit/pull/1387)). +Contributor instructions now have one shared source in agnostic-ai, which creates the files read by Claude Code and Codex. The project installs a fixed version of this tool through npm. The shared instructions decide which guidance and model to use for each task. Contributors edit `.agnostic-ai/` and then recreate the tool-specific files ([#1387](https://github.com/TypedDevs/bashunit/pull/1387)). -Release automation also updates and commits both npm lockfiles' project versions and restores them during rollback. CI compatibility checks scan shell source files without treating generated instructions as executable code, and Linux installer acceptance jobs include their required build optimizer. +The release script now updates and commits the project version in both npm lockfiles, which record installed dependencies. It restores those files if local release changes need to be undone. Automated checks for supported Bash versions read shell code without treating generated instructions as code, and the Linux installer checks now install the build tool they require. ---