Merge pull request #111 from mbland/test-namespace

Put all `lib/testing` functions in `@go.` namespace

Author: mbland

lib/testing/environment

@@ -39,7 +39,7 @@ readonly TEST_GO_PLUGINS_DIR="$TEST_GO_SCRIPTS_DIR/plugins"
 #
 # Call this from `teardown` if your tests create any files or directories in
 # `TEST_GO_ROOTDIR`.
-remove_test_go_rootdir() {
+@go.remove_test_go_rootdir() {
   remove_bats_test_dirs
 }
 
@@ -50,7 +50,7 @@ remove_test_go_rootdir() {
 #
 # Arguments:
 #   ...:  Lines comprising the `./go` script
-create_test_go_script() {
+@go.create_test_go_script() {
   create_bats_test_script 'go' \
     ". '$_GO_CORE_DIR/go-core.bash' '$TEST_GO_SCRIPTS_RELATIVE_DIR'" \
     "$@"
@@ -82,7 +82,7 @@ test-go() {
 # Arguments:
 #   script_name:  Name of the command script
 #   ...:          Lines comprising the `./go` command script
-create_test_command_script() {
+@go.create_test_command_script() {
   create_bats_test_script "$TEST_GO_SCRIPTS_RELATIVE_DIR/$1" "${@:2}"
 }
 
@@ -97,14 +97,14 @@ create_test_command_script() {
 # Arguments:
 #   parent_name:  Name of the "parent" command script
 #   ...:          Names of "child" command scripts
-create_parent_and_subcommands() {
+@go.create_parent_and_subcommands() {
   local parent="$1"
   shift
   local subcommand
 
-  create_test_command_script "$parent"
+  @go.create_test_command_script "$parent"
 
   for subcommand in "$@"; do
-    create_test_command_script "$parent.d/$subcommand"
+    @go.create_test_command_script "$parent.d/$subcommand"
   done
 }

lib/testing/log

@@ -20,8 +20,8 @@ export _GO_LOG_TIMESTAMP_FORMAT=
 #
 # Arguments:
 #   ...:  Lines comprising the `./go` script
-create_log_script(){
-  create_test_go_script \
+@go.create_log_script(){
+  @go.create_test_go_script \
     ". \"\$_GO_USE_MODULES\" 'log'" \
     'if [[ -n "$TEST_LOG_FILE" ]]; then' \
     '  @go.log_add_output_file "$TEST_LOG_FILE"' \
@@ -31,17 +31,17 @@ create_log_script(){
 
 # Creates and executes a `./go` script that imports the `log` module
 #
-# Globals and arguments are identical to `create_log_script`.
-run_log_script() {
-  create_log_script "$@"
+# Globals and arguments are identical to `@go.create_log_script`.
+@go.run_log_script() {
+  @go.create_log_script "$@"
   run "$TEST_GO_SCRIPT"
 }
 
 # Format a `log` module log level label
 #
 # Arguments:
 #   label:  Log level label to format
-format_log_label() {
+@go.format_log_label() {
   local label="$1"
 
   . "$_GO_USE_MODULES" 'log'
@@ -65,6 +65,10 @@ format_log_label() {
 # plaintext label or a label formatted with `format_log_label`. Any unknown
 # labels will be parsed as "a single string without a log label prefix".
 #
+# If the log label contains format codes, a formatting reset code will
+# automatically get appended to the expected log message, so there's no need to
+# add it explicitly.
+#
 # If you aren't looking for exact log output, consider using one of the standard
 # assertions from `_GO_CORE_DIR/lib/bats/assertions` instead.
 #
@@ -73,7 +77,7 @@ format_log_label() {
 #
 # Arguments:
 #   ...:  Lines of expected log output
-assert_log_equals() {
+@go.assert_log_equals() {
   set "$BATS_ASSERTION_DISABLE_SHELL_OPTIONS"
   local __log_level_label
   local expected=()
@@ -83,7 +87,7 @@ assert_log_equals() {
   _@go.log_init
 
   for ((i=0; $# != 0; ++i)); do
-    if __parse_log_level_label "$1"; then
+    if __@go.parse_log_level_label "$1"; then
       expected+=("$__log_level_label $2")
 
       if [[ "${__log_level_label:0:1}" == $'\e' ]]; then
@@ -111,30 +115,30 @@ assert_log_equals() {
 # Validates that a file matches the expected `@go.log` output
 #
 # Aside from the first file path argument, the remaining arguments and semantics
-# are exactly the same as `assert_log_equals`.
+# are exactly the same as `@go.assert_log_equals`.
 #
 # In cases where `@go.log_add_output_file` is used to add a `TEST_LOG_FILE` to
 # all levels, and all test output comes from `@go.log`, this may be invoked
-# following `assert_log_equals` like so to ensure the log file output matches
-# standard output and standard error:
+# following `@go.assert_log_equals` like so to ensure the log file output
+# matches standard output and standard error:
 #
-#   assert_log_file_equals "$TEST_LOG_FILE" "${lines[@]}"
+#   @go.assert_log_file_equals "$TEST_LOG_FILE" "${lines[@]}"
 #
 # If you aren't looking for exact log output, consider using one of the standard
 # assertions from `_GO_CORE_DIR/lib/bats/assertions` instead.
 #
 # Arguments:
 #   log_file:  Path to the log file to validate
 #   ...:       Lines of expected log output
-assert_log_file_equals() {
+@go.assert_log_file_equals() {
   set "$BATS_ASSERTION_DISABLE_SHELL_OPTIONS"
   local log_file="$1"
   shift
 
   if ! set_bats_output_and_lines_from_file "$log_file"; then
     return_from_bats_assertion '1'
   else
-    assert_log_equals "$@"
+    @go.assert_log_equals "$@"
     return_from_bats_assertion "$?"
   fi
 }
@@ -151,16 +155,16 @@ assert_log_file_equals() {
 #   LOG_COMMAND_STACK_TRACE_ITEMS:
 #     Stack trace lines from `@go.log_command` comprising the command logging
 #     mechanism
-set_log_command_stack_trace_items() {
+@go.set_log_command_stack_trace_items() {
   if [[ "${#LOG_COMMAND_STACK_TRACE_ITEMS[@]}" -eq '0' ]]; then
     export LOG_COMMAND_STACK_TRACE_ITEMS
     LOG_COMMAND_STACK_TRACE_ITEMS=(
-      "$(stack_trace_item "$_GO_CORE_DIR/lib/log" '_@go.log_command_invoke' \
-        '  "${__go_log_command_args[@]}" 2>&1')"
+      "$(@go.stack_trace_item "$_GO_CORE_DIR/lib/log" \
+        '_@go.log_command_invoke' '  "${__go_log_command_args[@]}" 2>&1')"
         # For some reason, with the process redirection at the end of the
         # `while` loop, the stack trace reports the opening line of the function
         # definition, not the actual `done < <(_@go.log_command_invoke)` line.
-      "$(stack_trace_item "$_GO_CORE_DIR/lib/log" '@go.log_command')")
+      "$(@go.stack_trace_item "$_GO_CORE_DIR/lib/log" '@go.log_command')")
   fi
 }
 
@@ -180,7 +184,7 @@ set_log_command_stack_trace_items() {
 # Returns:
 #   zero if `level_label` exists in `_GO_LOG_LEVELS`, nonzero otherwise
 #   __log_level_label:  Assigned the padded version of `level_label` if valid
-__parse_log_level_label() {
+__@go.parse_log_level_label() {
   local level_label="$1"
   local try_level
   local __go_log_level_index

lib/testing/stack-trace

@@ -5,18 +5,18 @@
 # You must source `_GO_CORE_DIR/lib/testing/environment` before this file.
 
 # Get the stack trace of a line from a file or function as it would appear in
-# @go.print_stack_trace output.
+# `@go.print_stack_trace` output.
 #
 # Arguments:
 #   filepath:       Path to the file containing the line
 #   function_name:  Function in which the line appears, 'main', or 'source'
 #   target_line:    Line for which to produce a stack trace line
-stack_trace_item() {
+@go.stack_trace_item() {
   local filepath="$1"
   local function_name="$2"
   local target_line="$3"
 
-  __check_file_path_specified_and_present "$filepath"
+  __@go.check_file_path_specified_and_present "$filepath"
 
   if [[ -z "$function_name" ]]; then
     printf 'No function name specified for `%s`.\n' "$FUNCNAME" >&2
@@ -48,7 +48,7 @@ stack_trace_item() {
 #   GO_CORE_STACK_TRACE_COMPONENTS:
 #     Stack trace lines from `go-core.bash` comprising the command script
 #     dispatch mechanism
-set_go_core_stack_trace_components() {
+@go.set_go_core_stack_trace_components() {
   local go_core_file="$_GO_CORE_DIR/go-core.bash"
   local stack_item
   local script="$TEST_GO_ROOTDIR/generate-go-core-stack-trace"
@@ -58,7 +58,7 @@ set_go_core_stack_trace_components() {
     create_bats_test_script "${script#$TEST_GO_ROOTDIR}" \
       ". '$_GO_CORE_DIR/go-core.bash' '$TEST_GO_SCRIPTS_RELATIVE_DIR'" \
       '@go "$@"'
-    create_test_command_script 'print-stack-trace' '@go.print_stack_trace'
+    @go.create_test_command_script 'print-stack-trace' '@go.print_stack_trace'
 
     for stack_item in $("$script" 'print-stack-trace'); do
       if [[ "$stack_item" =~ $go_core_file ]]; then
@@ -81,15 +81,15 @@ set_go_core_stack_trace_components() {
 #   filepath:  Path to the file used to generate the stack trace item
 #   offset:    Offset from the last line to get the line number (default 0)
 #   funcname:  Name of the function expected in the stack trace (default 'main')
-stack_trace_item_from_offset() {
+@go.stack_trace_item_from_offset() {
   local filepath="${1}"
   local offset="${2:-0}"
   local funcname="${3:-main}"
   local num_lines='0'
   local lineno
 
-  __check_file_path_specified_and_present "$filepath"
-  count_lines "$filepath" 'num_lines'
+  __@go.check_file_path_specified_and_present "$filepath"
+  @go.count_lines "$filepath" 'num_lines'
   lineno="$((num_lines - offset))"
   printf '  %s:%d %s\n' "$filepath" "$lineno" "$funcname"
 }
@@ -99,13 +99,13 @@ stack_trace_item_from_offset() {
 # Arguments:
 #   filepath:     Path to the file
 #   result_name:  Name of the caller's variable in which to store the result
-count_lines() {
+@go.count_lines() {
   local filepath="$1"
   local result_name="$2"
   local line
   local i='0'
 
-  __check_file_path_specified_and_present "$filepath"
+  __@go.check_file_path_specified_and_present "$filepath"
   if [[ -z "$result_name" ]]; then
     printf 'No result variable specified for `%s`.\n' "$FUNCNAME" >&2
     exit 1
@@ -129,7 +129,7 @@ count_lines() {
 #
 # Arguments:
 #   filepath:  File path value to confirm
-__check_file_path_specified_and_present() {
+__@go.check_file_path_specified_and_present() {
   if [[ -z "$1" ]]; then
     printf 'No file specified for `%s`.\n' "${FUNCNAME[1]}" >&2
     exit 1

lib/testing/stack-trace-item

@@ -7,7 +7,7 @@
 
 . "$_GO_CORE_DIR/lib/bats/helpers"
 
-__stack_trace_item() {
+__@go.stack_trace_item() {
   local filepath="$1"
   local function_name="$2"
   local target_line="$3"
@@ -86,4 +86,4 @@ __stack_trace_item() {
   exit 1
 }
 
-__stack_trace_item "$@"
+__@go.stack_trace_item "$@"

lib/testing/stubbing

@@ -4,16 +4,16 @@
 
 # Replace a module in `_GO_CORE_DIR/lib` with a stub implementation
 #
-# THIS IS POTENTIALLY DANGEROUS and you MUST call `restore_stubbed_core_modules`
-# in your `teardown` function if you use it!
+# THIS IS POTENTIALLY DANGEROUS and you MUST call
+# `@go.restore_stubbed_core_modules` in your `teardown` function if you use it!
 #
 # Useful when you need to model core module behavior, but don't want it to do
 # real work or want to avoid a potentially complicated test setup.
 #
 # Arguments:
 #   module_name:  Name of the module to stub from `_GO_CORE_DIR/lib`
 #   ...:          Lines comprising the stubbed module implementation
-create_core_module_stub() {
+@go.create_core_module_stub() {
   local module_path="$_GO_CORE_DIR/lib/$1"
   shift
 
@@ -28,10 +28,10 @@ create_core_module_stub() {
   chmod 600 "$module_path"
 }
 
-# Restore all `_GO_CORE_DIR/lib` modules stubbed by `create_core_module_stub`
+# Restore all core modules stubbed by `@go.create_core_module_stub`
 #
-# YOU MUST CALL THIS FROM TEARDOWN IF YOU USE `create_core_module_stub`!
-restore_stubbed_core_modules() {
+# YOU MUST CALL THIS FROM TEARDOWN IF YOU USE `@go.create_core_module_stub`!
+@go.restore_stubbed_core_modules() {
   local module
 
   for module in "$_GO_CORE_DIR/lib"/*.stubbed; do

tests/builtins/doc-only-scripts.bats

@@ -11,14 +11,14 @@
 load ../environment
 
 teardown() {
-  remove_test_go_rootdir
+  @go.remove_test_go_rootdir
 }
 
 @test "$SUITE: 'edit' script should exit with an error" {
   local expected="ERROR: \"$TEST_GO_SCRIPT edit\" "
   expected+='is implemented directly within the @go function.'
 
-  create_test_go_script "_@go.source_builtin 'edit'"
+  @go.create_test_go_script "_@go.source_builtin 'edit'"
   run "$TEST_GO_SCRIPT"
   assert_failure "$expected"
 }
@@ -27,7 +27,7 @@ teardown() {
   local expected="ERROR: \"$TEST_GO_SCRIPT run\" "
   expected+='is implemented directly within the @go function.'
 
-  create_test_go_script "_@go.source_builtin 'run'"
+  @go.create_test_go_script "_@go.source_builtin 'run'"
   run "$TEST_GO_SCRIPT"
   assert_failure "$expected"
 }
@@ -37,7 +37,7 @@ teardown() {
   expected+='is implemented in the function generated by '
   expected+="\"$TEST_GO_SCRIPT env\"."
 
-  create_test_go_script "_@go.source_builtin 'unenv'"
+  @go.create_test_go_script "_@go.source_builtin 'unenv'"
   run "$TEST_GO_SCRIPT"
   assert_failure "$expected"
 }

tests/changes.bats

@@ -7,7 +7,7 @@ setup() {
 }
 
 teardown() {
-  remove_test_go_rootdir
+  @go.remove_test_go_rootdir
 }
 
 @test "$SUITE: tab completions" {

tests/command-descriptions.bats

@@ -7,11 +7,11 @@ setup() {
 }
 
 teardown() {
-  rm -rf "$TEST_GO_ROOTDIR"
+  @go.remove_test_go_rootdir
 }
 
 create_cmd_path_and_name_go_script() {
-  create_test_go_script \
+  @go.create_test_go_script \
     ". '$_GO_CORE_DIR/lib/internal/command_descriptions'" \
     'declare __go_cmd_name' \
     'if _@go.check_command_path_and_parse_command_name "$@"; then' \
@@ -23,14 +23,14 @@ create_cmd_path_and_name_go_script() {
 
 @test "$SUITE: check command path and parse command name passes" {
   create_cmd_path_and_name_go_script
-  create_test_command_script 'foo'
+  @go.create_test_command_script 'foo'
   run "$TEST_GO_SCRIPT" "$TEST_GO_SCRIPTS_DIR/foo"
   assert_success '__go_cmd_name: foo'
 }
 
 @test "$SUITE: check sub-command path and parse command name passes" {
   create_cmd_path_and_name_go_script
-  create_test_command_script 'foo.d/bar.d/baz'
+  @go.create_test_command_script 'foo.d/bar.d/baz'
   run "$TEST_GO_SCRIPT" "$TEST_GO_SCRIPTS_DIR/foo.d/bar.d/baz"
   assert_success '__go_cmd_name: foo bar baz'
 }