Merge pull request #407 from TypedDevs/chore/use-at-data_provider

Deprecate data_provider in favor of @data_provider

Author: Chemaclass

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Fix asserts on test doubles in subshell
 - Allow interpolating arguments in data providers output
+- Deprecate `# data_provider` in favor of `# @data_provider`
 
 ## [0.19.1](https://github.com/TypedDevs/bashunit/compare/0.19.0...0.19.1) - 2025-05-23
 

adrs/adr-004-metadata-prefix.md

@@ -0,0 +1,37 @@
+# Title: Prefix metadata comments with @
+
+* Status: accepted
+* Authors: @Chemaclass
+* Date: 2025-05-29
+
+
+## Context and Problem Statement
+
+Data providers are defined via a special comment `# data_provider`. We want to
+clearly differentiate these meta comments from ordinary comments.
+
+## Considered Options
+
+* Keep using `# data_provider` as is.
+* Introduce an `@` prefix for special comments while supporting the old syntax.
+
+## Decision Outcome
+
+We decided to prefix the metadata provider directives with `@`,
+eg: using `# @data_provider provider_name`.
+
+> The previous form without the prefix is still supported for backward compatibility but is now deprecated.
+
+### Positive Consequences
+
+* Highlights special bashunit directives clearly.
+* Allows future directives to consistently use the `@` prefix.
+
+### Negative Consequences
+
+* Projects must eventually update old comments to the new syntax.
+
+## Technical Details
+
+`helper::get_provider_data` now matches both `# @data_provider` and the old
+`# data_provider` when locating provider functions.

docs/blog/2024-09-01-release-0-15.md

@@ -51,7 +51,7 @@ BASHUNIT_REPORT_HTML=
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directory_exists() {
   local outro=$1
   local directory=$2

docs/data-providers.md

@@ -13,9 +13,12 @@ Each run is treated as a separate test, so it can pass or fail independently. Pl
 
 A data provider function is specified as follows:
 
+> **Note**: The previous `# data_provider` syntax is still supported but
+> deprecated. Prefer using the `@` prefix going forward.
+
 ::: code-group
 ```bash [Example]
-# data_provider provider_function_name
+# @data_provider provider_function_name
 function test_my_test_case() {
   ...
 }
@@ -32,7 +35,7 @@ argument position.
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider fizz_numbers
+# @data_provider fizz_numbers
 function test_returns_fizz_when_multiple_of_::1::_like_::2::_given() {
   # ...
 }
@@ -53,7 +56,7 @@ Running example_test.sh
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directories_exists() {
   local dir1=$1
   local dir2=$2
@@ -78,7 +81,7 @@ Running example_test.sh
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directory_exists() {
   local directory=$1
 
@@ -103,7 +106,7 @@ Running example_test.sh
 
 ::: code-group
 ```bash [example_test.sh]
-# data_provider provider_directories
+# @data_provider provider_directories
 function test_directory_exists() {
   local outro=$1
   local directory=$2

src/helpers.sh

@@ -158,9 +158,9 @@ function helper::get_provider_data() {
   fi
 
   data_provider_function=$(\
-    grep -B 1 "function $function_name()" "$script" |\
-    grep "# data_provider " |\
-    sed -E -e 's/\ *# data_provider (.*)$/\1/g'\
+    grep -B 2 "function $function_name()" "$script" |\
+    grep -E "# *@?data_provider " |\
+    sed -E -e 's/\ *# *@?data_provider (.*)$/\1/g'\
     || true
   )
 

tests/functional/provider_test.sh

@@ -5,7 +5,7 @@ function set_up() {
   _GLOBAL="aa-bb"
 }
 
-# data_provider provide_multiples_values
+# @data_provider provide_multiples_values
 function test_multiple_values_from_data_provider() {
   local first=$1
   local second=$2
@@ -17,7 +17,7 @@ function provide_multiples_values() {
   echo "aa" "bb"
 }
 
-# data_provider provide_single_values
+# @data_provider provide_single_values
 function test_single_values_from_data_provider() {
   local data="$1"
 
@@ -30,7 +30,7 @@ function provide_single_values() {
   echo "three"
 }
 
-# data_provider provide_single_value
+# @data_provider provide_single_value
 function test_single_value_from_data_provider() {
   local current_data="$1"
 

tests/unit/assert_test.sh

@@ -11,7 +11,7 @@ function test_unsuccessful_fail() {
     "$(fail "Failure message")"
 }
 
-# data_provider provider_successful_assert_true
+# @data_provider provider_successful_assert_true
 function test_successful_assert_true() {
   # shellcheck disable=SC2086
   assert_empty "$(assert_true $1)"
@@ -45,7 +45,7 @@ function test_unsuccessful_assert_true_on_function() {
     "$(assert_true "eval return 2")"
 }
 
-# data_provider provider_successful_assert_false
+# @data_provider provider_successful_assert_false
 function test_successful_assert_false() {
   # shellcheck disable=SC2086
   assert_empty "$(assert_false $1)"

tests/unit/check_os_test.sh

@@ -40,7 +40,7 @@ function test_detect_osx_os() {
   assert_equals "OSX" "$_OS"
 }
 
-# data_provider window_linux_variations
+# @data_provider window_linux_variations
 function test_detect_windows_os() {
   local windows_linux="$1"
   mock uname echo "$windows_linux"

tests/unit/helpers_test.sh

@@ -123,7 +123,7 @@ function fake_provider_data_string() {
 
 function test_get_provider_data() {
   # shellcheck disable=SC2317
-  # data_provider fake_provider_data_string
+  # @data_provider fake_provider_data_string
   function fake_function_get_provider_data() {
     return 0
   }
@@ -137,8 +137,8 @@ function fake_provider_data_array() {
 }
 
 function test_get_provider_data_array() {
+  # @data_provider fake_provider_data_array
   # shellcheck disable=SC2317
-  # data_provider fake_provider_data_array
   function fake_function_get_provider_data_array() {
     return 0
   }
@@ -150,7 +150,7 @@ function test_get_provider_data_array() {
 
 function test_get_provider_data_should_returns_empty_when_not_exists_provider_function() {
   # shellcheck disable=SC2317
-  # data_provider not_existing_provider
+  # @data_provider not_existing_provider
   function fake_function_get_not_existing_provider_data() {
     return 0
   }