feat(assert): extend date format auto-detection with space-separated datetime and tz offset

Author: Chemaclass

CHANGELOG.md

@@ -4,7 +4,7 @@
 
 ### Added
 - Add date comparison assertions: `assert_date_equals`, `assert_date_before`, `assert_date_after`, `assert_date_within_range`, `assert_date_within_delta`
-    - Accepts epoch seconds (integers) or ISO 8601 dates (`2023-11-14`, `2023-11-14T12:00:00`)
+    - Accepts epoch seconds, ISO 8601 (`2023-11-14`, `2023-11-14T12:00:00`, `2023-11-14T12:00:00Z`, `2023-11-14T12:00:00+0100`), or space-separated datetime (`2023-11-14 12:00:00`)
     - Auto-detects format and converts ISO 8601 to epoch via `bashunit::date::to_epoch`
     - Mixed formats supported (one epoch, one ISO) in the same assertion call
     - Fully portable across GNU and BSD systems

docs/assertions.md

@@ -359,9 +359,17 @@ function test_failure() {
 ## assert_date_equals
 > `assert_date_equals "expected" "actual"`
 
-Reports an error if the two epoch timestamps `expected` and `actual` are not equal.
+Reports an error if the two date values `expected` and `actual` are not equal.
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. Supported formats:
+- Epoch seconds (integers): `1700000000`
+- ISO 8601 date: `2023-11-14`
+- ISO 8601 datetime: `2023-11-14T12:00:00`
+- ISO 8601 datetime with UTC Z: `2023-11-14T12:00:00Z`
+- ISO 8601 datetime with timezone offset: `2023-11-14T12:00:00+0100`
+- Space-separated datetime: `2023-11-14 12:00:00`
+
+You can mix formats in the same assertion (e.g., one epoch, one ISO).
 
 ::: code-group
 ```bash [Example]
@@ -383,7 +391,7 @@ function test_failure() {
 
 Reports an error if `actual` is not before `expected` (i.e. `actual` must be less than `expected`).
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. See [assert_date_equals](#assert_date_equals) for supported formats.
 
 ::: code-group
 ```bash [Example]
@@ -402,7 +410,7 @@ function test_failure() {
 
 Reports an error if `actual` is not after `expected` (i.e. `actual` must be greater than `expected`).
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. See [assert_date_equals](#assert_date_equals) for supported formats.
 
 ::: code-group
 ```bash [Example]
@@ -421,7 +429,7 @@ function test_failure() {
 
 Reports an error if `actual` does not fall between `from` and `to` (inclusive).
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. See [assert_date_equals](#assert_date_equals) for supported formats.
 
 ::: code-group
 ```bash [Example]
@@ -440,7 +448,7 @@ function test_failure() {
 
 Reports an error if `actual` is not within `delta` seconds of `expected`.
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. See [assert_date_equals](#assert_date_equals) for supported formats.
 
 ::: code-group
 ```bash [Example]

src/assert_dates.sh

@@ -12,18 +12,28 @@ function bashunit::date::to_epoch() {
     ;;
   esac
 
-  # ISO 8601 conversion (GNU vs BSD date)
+  # Format conversion (GNU vs BSD date)
   local epoch
   # Try GNU date first (-d flag)
   epoch=$(date -d "$input" +%s 2>/dev/null) && {
     echo "$epoch"
     return 0
   }
-  # Try BSD date (-j -f flag) with datetime format
+  # Try BSD date (-j -f flag) with ISO 8601 datetime + timezone offset
+  epoch=$(date -j -f "%Y-%m-%dT%H:%M:%S%z" "$input" +%s 2>/dev/null) && {
+    echo "$epoch"
+    return 0
+  }
+  # Try BSD date with ISO 8601 datetime format
   epoch=$(date -j -f "%Y-%m-%dT%H:%M:%S" "$input" +%s 2>/dev/null) && {
     echo "$epoch"
     return 0
   }
+  # Try BSD date with space-separated datetime format
+  epoch=$(date -j -f "%Y-%m-%d %H:%M:%S" "$input" +%s 2>/dev/null) && {
+    echo "$epoch"
+    return 0
+  }
   # Try BSD date with date-only format
   epoch=$(date -j -f "%Y-%m-%d" "$input" +%s 2>/dev/null) && {
     echo "$epoch"

tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_all_assert_docs.snapshot

@@ -154,9 +154,17 @@ Reports an error if `actual` is not greater than or equal to `expected`.
 --------------
 > `assert_date_equals "expected" "actual"`
 
-Reports an error if the two epoch timestamps `expected` and `actual` are not equal.
+Reports an error if the two date values `expected` and `actual` are not equal.
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. Supported formats:
+- Epoch seconds (integers): `1700000000`
+- ISO 8601 date: `2023-11-14`
+- ISO 8601 datetime: `2023-11-14T12:00:00`
+- ISO 8601 datetime with UTC Z: `2023-11-14T12:00:00Z`
+- ISO 8601 datetime with timezone offset: `2023-11-14T12:00:00+0100`
+- Space-separated datetime: `2023-11-14 12:00:00`
+
+You can mix formats in the same assertion (e.g., one epoch, one ISO).
 
 
 ## assert_date_before
@@ -165,7 +173,7 @@ All inputs are **epoch seconds** (integers), generated via `date +%s`.
 
 Reports an error if `actual` is not before `expected` (i.e. `actual` must be less than `expected`).
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. See assert_date_equals(#assert_date_equals) for supported formats.
 
 
 ## assert_date_after
@@ -174,7 +182,7 @@ All inputs are **epoch seconds** (integers), generated via `date +%s`.
 
 Reports an error if `actual` is not after `expected` (i.e. `actual` must be greater than `expected`).
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. See assert_date_equals(#assert_date_equals) for supported formats.
 
 
 ## assert_date_within_range
@@ -183,7 +191,7 @@ All inputs are **epoch seconds** (integers), generated via `date +%s`.
 
 Reports an error if `actual` does not fall between `from` and `to` (inclusive).
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. See assert_date_equals(#assert_date_equals) for supported formats.
 
 
 ## assert_date_within_delta
@@ -192,7 +200,7 @@ All inputs are **epoch seconds** (integers), generated via `date +%s`.
 
 Reports an error if `actual` is not within `delta` seconds of `expected`.
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. See assert_date_equals(#assert_date_equals) for supported formats.
 
 
 ## assert_exit_code
@@ -566,5 +574,3 @@ Reports an error if `command` completes in `threshold_ms` milliseconds or less.
 
 Unambiguously reports an error message. Useful for reporting specific message
 when testing situations not covered by any `assert_*` functions.
-
-

tests/acceptance/snapshots/bashunit_test_sh.test_bashunit_should_display_filtered_assert_docs.snapshot

@@ -11,9 +11,17 @@ Reports an error if the two variables `expected` and `actual` are not equal igno
 --------------
 > `assert_date_equals "expected" "actual"`
 
-Reports an error if the two epoch timestamps `expected` and `actual` are not equal.
+Reports an error if the two date values `expected` and `actual` are not equal.
 
-All inputs are **epoch seconds** (integers), generated via `date +%s`.
+Inputs are automatically converted to epoch seconds. Supported formats:
+- Epoch seconds (integers): `1700000000`
+- ISO 8601 date: `2023-11-14`
+- ISO 8601 datetime: `2023-11-14T12:00:00`
+- ISO 8601 datetime with UTC Z: `2023-11-14T12:00:00Z`
+- ISO 8601 datetime with timezone offset: `2023-11-14T12:00:00+0100`
+- Space-separated datetime: `2023-11-14 12:00:00`
+
+You can mix formats in the same assertion (e.g., one epoch, one ISO).
 
 
 ## assert_files_equals
@@ -39,5 +47,3 @@ Reports an error if `expected` and `actual` are not equals.
 > `assert_json_equals "expected" "actual"`
 
 Reports an error if the two JSON strings are not structurally equal. Key order is ignored. Requires `jq` to be installed; if missing the test is skipped.
-
-

tests/unit/assert_dates_test.sh

@@ -129,3 +129,37 @@ function test_successful_assert_date_within_delta_with_iso_datetime() {
   assert_empty\
     "$(assert_date_within_delta "2023-11-14T12:00:00" "2023-11-14T12:00:05" "10")"
 }
+
+# Space-separated datetime format tests
+
+function test_successful_assert_date_equals_with_space_separated_datetime() {
+  assert_empty "$(assert_date_equals "2023-11-14 12:00:00" "2023-11-14 12:00:00")"
+}
+
+function test_successful_assert_date_equals_iso_vs_space_separated() {
+  assert_empty "$(assert_date_equals "2023-11-14T12:00:00" "2023-11-14 12:00:00")"
+}
+
+function test_successful_assert_date_before_with_space_separated_datetime() {
+  assert_empty "$(assert_date_before "2023-11-14 13:00:00" "2023-11-14 12:00:00")"
+}
+
+function test_successful_assert_date_equals_epoch_vs_space_separated() {
+  local epoch
+  epoch=$(date -d "2023-11-14 12:00:00" +%s 2>/dev/null) \
+    || epoch=$(date -j -f "%Y-%m-%d %H:%M:%S" "2023-11-14 12:00:00" +%s 2>/dev/null)
+
+  assert_empty "$(assert_date_equals "$epoch" "2023-11-14 12:00:00")"
+}
+
+# UTC Z suffix test (documents existing behavior)
+
+function test_successful_assert_date_equals_with_utc_z_suffix() {
+  assert_empty "$(assert_date_equals "2023-11-14T12:00:00" "2023-11-14T12:00:00Z")"
+}
+
+# Timezone offset tests
+
+function test_successful_assert_date_equals_with_tz_offset() {
+  assert_empty "$(assert_date_equals "2023-11-14T12:00:00+0100" "2023-11-14T12:00:00+0100")"
+}