From 62a9d096f2337d5cec92e84781c384c2e190685b Mon Sep 17 00:00:00 2001
From: Chemaclass <chemaclass@outlook.es>
Date: Fri, 7 Aug 2026 13:39:04 +0200
Subject: [PATCH] perf(snapshot): bypass matcher for literals

---
 src/assert/snapshot.sh             | 26 ++++++++++++----
 tests/unit/assert/snapshot_test.sh | 50 ++++++++++++++++++++++++++++++
 2 files changed, 70 insertions(+), 6 deletions(-)

diff --git a/src/assert/snapshot.sh b/src/assert/snapshot.sh
index aff3a23e..d0f6afef 100644
--- a/src/assert/snapshot.sh
+++ b/src/assert/snapshot.sh
@@ -288,12 +288,26 @@ function bashunit::snapshot::compare() {
   snapshot=$(<"$snapshot_path")
   snapshot="${snapshot//$'\r'/}"
 
-  if ! bashunit::snapshot::match_with_placeholder "$actual" "$snapshot"; then
-    local label=$(bashunit::helper::normalize_test_function_name "$func_name")
-    bashunit::state::add_assertions_failed
-    bashunit::console_results::print_failed_snapshot_test "$label" "$snapshot_path" "$actual"
-    return 1
+  # Literal snapshots need only a builtin string comparison. The placeholder
+  # matcher shells out to sed and perl/grep, so reserve it for snapshots that
+  # actually contain the configured marker.
+  if [ "$actual" = "$snapshot" ]; then
+    bashunit::state::add_assertions_passed
+    return
   fi
 
-  bashunit::state::add_assertions_passed
+  local placeholder="${BASHUNIT_SNAPSHOT_PLACEHOLDER:-::ignore::}"
+  case "$snapshot" in
+  *"$placeholder"*)
+    if bashunit::snapshot::match_with_placeholder "$actual" "$snapshot"; then
+      bashunit::state::add_assertions_passed
+      return
+    fi
+    ;;
+  esac
+
+  local label=$(bashunit::helper::normalize_test_function_name "$func_name")
+  bashunit::state::add_assertions_failed
+  bashunit::console_results::print_failed_snapshot_test "$label" "$snapshot_path" "$actual"
+  return 1
 }
diff --git a/tests/unit/assert/snapshot_test.sh b/tests/unit/assert/snapshot_test.sh
index cdc68a71..365b72bc 100644
--- a/tests/unit/assert/snapshot_test.sh
+++ b/tests/unit/assert/snapshot_test.sh
@@ -131,6 +131,56 @@ function test_assert_snapshot_with_custom_placeholder() {
 
 # --- internals ---------------------------------------------------------------
 
+function test_snapshot_compare_bypasses_placeholder_matcher_for_literal_match() {
+  local snapshot_path
+  snapshot_path="$(bashunit::temp_dir)/literal-match.snapshot"
+  printf 'plain snapshot\n' >"$snapshot_path"
+
+  # Invoked indirectly by snapshot::compare.
+  # shellcheck disable=SC2329
+  function bashunit::snapshot::match_with_placeholder() { return 1; }
+
+  bashunit::snapshot::compare "plain snapshot" "$snapshot_path" "test_literal_match"
+}
+
+function test_snapshot_compare_bypasses_placeholder_matcher_for_literal_mismatch() {
+  local snapshot_path
+  snapshot_path="$(bashunit::temp_dir)/literal-mismatch.snapshot"
+  printf 'expected\n' >"$snapshot_path"
+
+  # Must not be invoked by snapshot::compare.
+  # shellcheck disable=SC2329
+  function bashunit::snapshot::match_with_placeholder() { return 0; }
+
+  local output status=0
+  output="$(bashunit::snapshot::compare \
+    "actual" "$snapshot_path" "test_literal_mismatch")" || status=$?
+
+  assert_same 1 "$status"
+  assert_contains "Expected to match the snapshot" "$output"
+}
+
+function test_snapshot_compare_uses_placeholder_matcher_when_marker_is_present() {
+  local snapshot_path
+  snapshot_path="$(bashunit::temp_dir)/placeholder-match.snapshot"
+  printf 'expected ::ignore::\n' >"$snapshot_path"
+
+  # Invoked indirectly by snapshot::compare.
+  # shellcheck disable=SC2329
+  function bashunit::snapshot::match_with_placeholder() { return 0; }
+
+  bashunit::snapshot::compare "different fixed text" "$snapshot_path" "test_placeholder_match"
+}
+
+function test_snapshot_compare_routes_a_custom_placeholder_to_the_matcher() {
+  local snapshot_path
+  snapshot_path="$(bashunit::temp_dir)/custom-placeholder-match.snapshot"
+  printf 'value <<ANY>>\n' >"$snapshot_path"
+
+  BASHUNIT_SNAPSHOT_PLACEHOLDER="<<ANY>>" \
+    bashunit::snapshot::compare "value 42" "$snapshot_path" "test_custom_placeholder"
+}
+
 function test_snapshot_normalize_actual_strips_cr_and_trailing_newlines() {
   local _snapshot_normalized
   bashunit::snapshot::normalize_actual $'line1\r\nline2\r\n\n\n'