diff --git a/CHANGELOG.md b/CHANGELOG.md index 7437de43..53cee8da 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,7 @@ - Add `--init [dir]` option to get you started quickly - Optimize `--help` message - Add `--no-output` option +- Add `--doc [search]` option ## [0.21.0](https://github.com/TypedDevs/bashunit/compare/0.20.0...0.21.0) - 2025-06-18 diff --git a/bashunit b/bashunit index b22d4d4a..a925fac1 100755 --- a/bashunit +++ b/bashunit @@ -25,6 +25,7 @@ source "$BASHUNIT_ROOT_DIR/src/console_results.sh" source "$BASHUNIT_ROOT_DIR/src/helpers.sh" source "$BASHUNIT_ROOT_DIR/src/upgrade.sh" source "$BASHUNIT_ROOT_DIR/src/assertions.sh" +source "$BASHUNIT_ROOT_DIR/src/doc.sh" source "$BASHUNIT_ROOT_DIR/src/reports.sh" source "$BASHUNIT_ROOT_DIR/src/runner.sh" source "$BASHUNIT_ROOT_DIR/src/bashunit.sh" @@ -101,6 +102,15 @@ while [[ $# -gt 0 ]]; do console_header::print_version trap '' EXIT && exit 0 ;; + --doc) + if [[ -n ${2:-} && ${2:0:1} != "-" ]]; then + doc::print_asserts "$2" + shift + else + doc::print_asserts + fi + trap '' EXIT && exit 0 + ;; --upgrade) upgrade::upgrade trap '' EXIT && exit 0 diff --git a/docs/assertions.md b/docs/assertions.md index a9cdcdd9..139ae990 100644 --- a/docs/assertions.md +++ b/docs/assertions.md @@ -113,7 +113,7 @@ function test_failure() { Reports an error if `needle` is not a substring of `haystack`. -[assert_not_contains](#assert-not-contains) is the inverse of this assertion and takes the same arguments. +- [assert_not_contains](#assert-not-contains) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -150,7 +150,7 @@ function test_failure() { Reports an error if `actual` is not empty. -[assert_not_empty](#assert-not-empty) is the inverse of this assertion and takes the same arguments. +- [assert_not_empty](#assert-not-empty) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -169,7 +169,7 @@ function test_failure() { Reports an error if `value` does not match the regular expression `pattern`. -[assert_not_matches](#assert-not-matches) is the inverse of this assertion and takes the same arguments. +- [assert_not_matches](#assert-not-matches) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -188,7 +188,7 @@ function test_failure() { Reports an error if `haystack` does not starts with `needle`. -[assert_string_not_starts_with](#assert-string-not-starts-with) is the inverse of this assertion and takes the same arguments. +- [assert_string_not_starts_with](#assert-string-not-starts-with) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -207,7 +207,7 @@ function test_failure() { Reports an error if `haystack` does not ends with `needle`. -[assert_string_not_ends_with](#assert-string-not-ends-with) is the inverse of this assertion and takes the same arguments. +- [assert_string_not_ends_with](#assert-string-not-ends-with) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -247,7 +247,7 @@ function test_failure() { Reports an error if `actual` is not less than `expected`. -[assert_greater_than](#assert-greater-than) is the inverse of this assertion and takes the same arguments. +- [assert_greater_than](#assert-greater-than) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -266,7 +266,7 @@ function test_failure() { Reports an error if `actual` is not less than or equal to `expected`. -[assert_greater_than](#assert-greater-or-equal-than) is the inverse of this assertion and takes the same arguments. +- [assert_greater_than](#assert-greater-or-equal-than) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -289,7 +289,7 @@ function test_failure() { Reports an error if `actual` is not greater than `expected`. -[assert_less_than](#assert-less-than) is the inverse of this assertion and takes the same arguments. +- [assert_less_than](#assert-less-than) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -308,7 +308,7 @@ function test_failure() { Reports an error if `actual` is not greater than or equal to `expected`. -[assert_less_or_equal_than](#assert-less-or-equal-than) is the inverse of this assertion and takes the same arguments. +- [assert_less_or_equal_than](#assert-less-or-equal-than) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -333,7 +333,7 @@ Reports an error if the exit code of `callable` is not equal to `expected`. If `callable` is not provided, it takes the last executed command or function instead. -[assert_successful_code](#assert-successful-code), [assert_general_error](#assert-general-error) and [assert_command_not_found](#assert-command-not-found) +- [assert_successful_code](#assert-successful-code), [assert_general_error](#assert-general-error) and [assert_command_not_found](#assert-command-not-found) are more semantic versions of this assertion, for which you don't need to specify an exit code. ::: code-group @@ -371,7 +371,7 @@ function test_failure() { Reports an error if `needle` is not an element of `haystack`. -[assert_array_not_contains](#assert-array-not-contains) is the inverse of this assertion and takes the same arguments. +- [assert_array_not_contains](#assert-array-not-contains) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -396,7 +396,7 @@ Reports an error if the exit code of `callable` is not successful (`0`). If `callable` is not provided, it takes the last executed command or function instead. -[assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code. +- [assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code. ::: code-group ```bash [Example] @@ -435,7 +435,7 @@ Reports an error if the exit code of `callable` is not a general error (`1`). If `callable` is not provided, it takes the last executed command or function instead. -[assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code. +- [assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code. ::: code-group ```bash [Example] @@ -475,7 +475,7 @@ In other words, if executing `callable` does not return a command not found exit If `callable` is not provided, it takes the last executed command or function instead. -[assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code. +- [assert_exit_code](#assert-exit-code) is the full version of this assertion where you can specify the expected exit code. ::: code-group ```bash [Example] @@ -500,7 +500,7 @@ function test_failure() { Reports an error if `file` does not exists, or it is a directory. -[assert_file_not_exists](#assert-file-not-exists) is the inverse of this assertion and takes the same arguments. +- [assert_file_not_exists](#assert-file-not-exists) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -526,7 +526,7 @@ function test_failure() { Reports an error if `file` does not contains the search string. -[assert_file_not_contains](#assert-file-not-contains) is the inverse of this assertion and takes the same arguments. +- [assert_file_not_contains](#assert-file-not-contains) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -601,7 +601,7 @@ function test_failure() { Reports an error if `directory` does not exist. -[assert_directory_not_exists](#assert-directory-not-exists) is the inverse of this assertion and takes the same arguments. +- [assert_directory_not_exists](#assert-directory-not-exists) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -645,7 +645,7 @@ function test_failure() { Reports an error if `directory` is not an empty directory. -[assert_is_directory_not_empty](#assert-is-directory-not-empty) is the inverse of this assertion and takes the same arguments. +- [assert_is_directory_not_empty](#assert-is-directory-not-empty) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -669,7 +669,7 @@ function test_failure() { Reports an error if `directory` is not a readable directory. -[assert_is_directory_not_readable](#assert-is-directory-not-readable) is the inverse of this assertion and takes the same arguments. +- [assert_is_directory_not_readable](#assert-is-directory-not-readable) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -693,7 +693,7 @@ function test_failure() { Reports an error if `directory` is not a writable directory. -[assert_is_directory_not_writable](#assert-is-directory-not-writable) is the inverse of this assertion and takes the same arguments. +- [assert_is_directory_not_writable](#assert-is-directory-not-writable) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -717,7 +717,7 @@ function test_failure() { Reports an error if `expected` and `actual` are not equals. -[assert_files_not_equals](#assert-files-not-equals) is the inverse of this assertion and takes the same arguments. +- [assert_files_not_equals](#assert-files-not-equals) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -757,7 +757,7 @@ function test_failure() { Reports an error if the two variables `expected` and `actual` are the same value. -[assert_same](#assert-same) is the inverse of this assertion and takes the same arguments. +- [assert_same](#assert-same) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -776,7 +776,7 @@ function test_failure() { Reports an error if `needle` is a substring of `haystack`. -[assert_contains](#assert-contains) is the inverse of this assertion and takes the same arguments. +- [assert_contains](#assert-contains) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -795,7 +795,7 @@ function test_failure() { Reports an error if `haystack` does starts with `needle`. -[assert_string_starts_with](#assert-string-starts-with) is the inverse of this assertion and takes the same arguments. +- [assert_string_starts_with](#assert-string-starts-with) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -814,7 +814,7 @@ function test_failure() { Reports an error if `haystack` does ends with `needle`. -[assert_string_ends_with](#assert-string-ends-with) is the inverse of this assertion and takes the same arguments. +- [assert_string_ends_with](#assert-string-ends-with) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -833,7 +833,7 @@ function test_failure() { Reports an error if `actual` is empty. -[assert_empty](#assert-empty) is the inverse of this assertion and takes the same arguments. +- [assert_empty](#assert-empty) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -852,7 +852,7 @@ function test_failure() { Reports an error if `value` matches the regular expression `pattern`. -[assert_matches](#assert-matches) is the inverse of this assertion and takes the same arguments. +- [assert_matches](#assert-matches) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -871,7 +871,7 @@ function test_failure() { Reports an error if `needle` is an element of `haystack`. -[assert_array_contains](#assert-array-contains) is the inverse of this assertion and takes the same arguments. +- [assert_array_contains](#assert-array-contains) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -894,7 +894,7 @@ function test_failure() { Reports an error if `file` does exists. -[assert_file_exists](#assert-file-exists) is the inverse of this assertion and takes the same arguments. +- [assert_file_exists](#assert-file-exists) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -921,7 +921,7 @@ function test_failed() { Reports an error if `file` contains the search string. -[assert_file_contains](#assert-file-contains) is the inverse of this assertion and takes the same arguments. +- [assert_file_contains](#assert-file-contains) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -946,7 +946,7 @@ function test_failure() { Reports an error if `directory` exists. -[assert_directory_exists](#assert-directory-exists) is the inverse of this assertion and takes the same arguments. +- [assert_directory_exists](#assert-directory-exists) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -969,7 +969,7 @@ function test_failure() { Reports an error if `directory` is empty. -[assert_is_directory_empty](#assert-is-directory-empty) is the inverse of this assertion and takes the same arguments. +- [assert_is_directory_empty](#assert-is-directory-empty) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -993,7 +993,7 @@ function test_failure() { Reports an error if `directory` is readable. -[assert_is_directory_readable](#assert-is-directory-readable) is the inverse of this assertion and takes the same arguments. +- [assert_is_directory_readable](#assert-is-directory-readable) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -1017,7 +1017,7 @@ function test_failure() { Reports an error if `directory` is writable. -[assert_is_directory_writable](#assert-is-directory-writable) is the inverse of this assertion and takes the same arguments. +- [assert_is_directory_writable](#assert-is-directory-writable) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] @@ -1042,7 +1042,7 @@ function test_failure() { Reports an error if `expected` and `actual` are not equals. -[assert_files_equals](#assert-files-equals) is the inverse of this assertion and takes the same arguments. +- [assert_files_equals](#assert-files-equals) is the inverse of this assertion and takes the same arguments. ::: code-group ```bash [Example] diff --git a/docs/command-line.md b/docs/command-line.md index 8f98ea12..d2f27b05 100644 --- a/docs/command-line.md +++ b/docs/command-line.md @@ -382,6 +382,26 @@ Upgrade **bashunit** to latest version. ``` ::: +## Doc + +> `bashunit --doc [filter]` + +Display the documentation for assert functions. When `filter` is provided, +only matching asserts will be shown. + +::: code-group +```bash [Example] +./bashunit --doc same +``` +```bash [Output] +## assert_equals +... + +## assert_not_same +... +``` +::: + ## Init > `bashunit --init [dir]` diff --git a/src/console_header.sh b/src/console_header.sh index 2f64c2c9..a6225de1 100644 --- a/src/console_header.sh +++ b/src/console_header.sh @@ -72,6 +72,10 @@ Options: --debug [file] Enable shell debug mode. Logs to file if provided. + --doc + Display the documentation for assert functions. When a filter is + provided, only matching asserts will be shown. + -e, --env, --boot Load a custom env/bootstrap file to override .env or define globals. diff --git a/src/doc.sh b/src/doc.sh new file mode 100644 index 00000000..cfee922f --- /dev/null +++ b/src/doc.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash + +function doc::print_asserts() { + local filter="${1:-}" + local doc_file="$BASHUNIT_ROOT_DIR/docs/assertions.md" + local line + local docstring="" + local fn="" + local should_print=0 + + while IFS='' read -r line || [[ -n "$line" ]]; do + if [[ $line =~ ^##\ ([A-Za-z0-9_]+) ]]; then + fn="${BASH_REMATCH[1]}" + if [[ -z "$filter" || "$fn" == *"$filter"* ]]; then + should_print=1 + echo "$line" + docstring="" + else + should_print=0 + fi + continue + fi + + if (( should_print )); then + if [[ "$line" =~ ^\`\`\` ]]; then + echo "--------------" + echo "$docstring" + should_print=0 + continue + fi + + [[ "$line" == "::: code-group" ]] && continue + + # Remove markdown link brackets and anchor tags + line="${line//[\[\]]/}" + line="$(sed -E 's/ *\(#[-a-z0-9]+\)//g' <<< "$line")" + docstring+="$line"$'\n' + fi + done < "$doc_file" +} diff --git a/tests/acceptance/bashunit_test.sh b/tests/acceptance/bashunit_test.sh index f5103cbe..32acfee5 100644 --- a/tests/acceptance/bashunit_test.sh +++ b/tests/acceptance/bashunit_test.sh @@ -18,3 +18,13 @@ function test_bashunit_should_display_help() { assert_match_snapshot "$(./bashunit --no-parallel --env "$TEST_ENV_FILE" --help)" assert_successful_code "$(./bashunit --no-parallel --env "$TEST_ENV_FILE" --help)" } + +function test_bashunit_should_display_all_assert_docs() { + assert_match_snapshot "$(./bashunit --no-parallel --env "$TEST_ENV_FILE" --doc)" + assert_successful_code "$(./bashunit --no-parallel --env "$TEST_ENV_FILE" --doc)" +} + +function test_bashunit_should_display_filtered_assert_docs() { + assert_match_snapshot "$(./bashunit --no-parallel --env "$TEST_ENV_FILE" --doc equals)" + assert_successful_code "$(./bashunit --no-parallel --env "$TEST_ENV_FILE" --doc equals)" +} diff --git a/tests/acceptance/snapshots/bashunit_benchmark_test_sh.test_bashunit_functional_benchmark.snapshot b/tests/acceptance/snapshots/bashunit_benchmark_test_sh.test_bashunit_functional_benchmark.snapshot deleted file mode 100644 index ebdd70f1..00000000 --- a/tests/acceptance/snapshots/bashunit_benchmark_test_sh.test_bashunit_functional_benchmark.snapshot +++ /dev/null @@ -1,5 +0,0 @@ -. - -Benchmark Results (avg ms) -Name Revs Its Avg(ms) -bench_run_bashunit_functional 2 1 ::ignore:: diff --git a/tests/acceptance/snapshots/bashunit_benchmark_test_sh.test_bashunit_runs_benchmark_file.snapshot b/tests/acceptance/snapshots/bashunit_benchmark_test_sh.test_bashunit_runs_benchmark_file.snapshot deleted file mode 100644 index fcecaece..00000000 --- a/tests/acceptance/snapshots/bashunit_benchmark_test_sh.test_bashunit_runs_benchmark_file.snapshot +++ /dev/null @@ -1,7 +0,0 @@ -bench bench_sleep [1/2] ::ignore:: -bench bench_sleep [2/2] ::ignore:: - - -Benchmark Results (avg ms) -Name Revs Its Avg(ms) -bench_sleep 5 2 ::ignore:: diff --git a/tests/acceptance/snapshots/bashunit_path_test_sh.test_bashunit_without_path_env_nor_argument.snapshot b/tests/acceptance/snapshots/bashunit_path_test_sh.test_bashunit_without_path_env_nor_argument.snapshot index 4e78a88f..ce3b720a 100644 --- a/tests/acceptance/snapshots/bashunit_path_test_sh.test_bashunit_without_path_env_nor_argument.snapshot +++ b/tests/acceptance/snapshots/bashunit_path_test_sh.test_bashunit_without_path_env_nor_argument.snapshot @@ -19,6 +19,10 @@ Options: --debug [file] Enable shell debug mode. Logs to file if provided. + --doc + Display the documentation for assert functions. When a filter is + provided, only matching asserts will be shown. + -e, --env, --boot Load a custom env/bootstrap file to override .env or define globals. diff --git a/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_all_assert_docs.snapshot b/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_all_assert_docs.snapshot new file mode 100644 index 00000000..e2204851 --- /dev/null +++ b/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_all_assert_docs.snapshot @@ -0,0 +1,179 @@ +## assert_true +-------------- +::ignore:: + +## assert_false +-------------- +::ignore:: + +## assert_same +-------------- +::ignore:: + +## assert_equals +-------------- +::ignore:: + +## assert_contains +-------------- +::ignore:: + +## assert_contains_ignore_case +-------------- +::ignore:: + +## assert_empty +-------------- +::ignore:: + +## assert_matches +-------------- +::ignore:: + +## assert_string_starts_with +-------------- +::ignore:: + +## assert_string_ends_with +-------------- +::ignore:: + +## assert_line_count +-------------- +::ignore:: + +## assert_less_than +-------------- +::ignore:: + +## assert_less_or_equal_than +-------------- +::ignore:: + +## assert_greater_than +-------------- +::ignore:: + +## assert_greater_or_equal_than +-------------- +::ignore:: + +## assert_exit_code +-------------- +::ignore:: + +## assert_array_contains +-------------- +::ignore:: + +## assert_successful_code +-------------- +::ignore:: + +## assert_general_error +-------------- +::ignore:: + +## assert_command_not_found +-------------- +::ignore:: + +## assert_file_exists +-------------- +::ignore:: + +## assert_file_contains +-------------- +::ignore:: + +## assert_is_file +-------------- +::ignore:: + +## assert_is_file_empty +-------------- +::ignore:: + +## assert_directory_exists +-------------- +::ignore:: + +## assert_is_directory +-------------- +::ignore:: + +## assert_is_directory_empty +-------------- +::ignore:: + +## assert_is_directory_readable +-------------- +::ignore:: + +## assert_is_directory_writable +-------------- +::ignore:: + +## assert_files_equals +-------------- +::ignore:: + +## assert_not_same +-------------- +::ignore:: + +## assert_not_contains +-------------- +::ignore:: + +## assert_string_not_starts_with +-------------- +::ignore:: + +## assert_string_not_ends_with +-------------- +::ignore:: + +## assert_not_empty +-------------- +::ignore:: + +## assert_not_matches +-------------- +::ignore:: + +## assert_array_not_contains +-------------- +::ignore:: + +## assert_file_not_exists +-------------- +::ignore:: + +## assert_file_not_contains +-------------- +::ignore:: + +## assert_directory_not_exists +-------------- +::ignore:: + +## assert_is_directory_not_empty +-------------- +::ignore:: + +## assert_is_directory_not_readable +-------------- +::ignore:: + +## assert_is_directory_not_writable +-------------- +::ignore:: + +## assert_files_not_equals +-------------- +::ignore:: + +## fail +-------------- +::ignore:: diff --git a/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_filtered_assert_docs.snapshot b/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_filtered_assert_docs.snapshot new file mode 100644 index 00000000..63c6ee31 --- /dev/null +++ b/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_filtered_assert_docs.snapshot @@ -0,0 +1,25 @@ +## assert_equals +-------------- +> `assert_equals "expected" "actual"` + +Reports an error if the two variables `expected` and `actual` are not equal ignoring the special chars like ANSI Escape Sequences (colors) and other special chars like tabs and new lines. + +- assert_same is similar but including special chars. + + +## assert_files_equals +-------------- +> `assert_files_equals "expected" "actual"` + +Reports an error if `expected` and `actual` are not equals. + +- assert_files_not_equals is the inverse of this assertion and takes the same arguments. + + +## assert_files_not_equals +-------------- +> `assert_files_not_equals "expected" "actual"` + +Reports an error if `expected` and `actual` are not equals. + +- assert_files_equals is the inverse of this assertion and takes the same arguments. diff --git a/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_help.snapshot b/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_help.snapshot index af2e750b..c57d3b1e 100644 --- a/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_help.snapshot +++ b/tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_help.snapshot @@ -18,6 +18,10 @@ Options: --debug [file] Enable shell debug mode. Logs to file if provided. + --doc + Display the documentation for assert functions. When a filter is + provided, only matching asserts will be shown. + -e, --env, --boot Load a custom env/bootstrap file to override .env or define globals.