From 7604a3d31b739b5eff4cd3e06470f5cbe2d23aae Mon Sep 17 00:00:00 2001
From: Chemaclass <chemaclass@outlook.es>
Date: Sat, 8 Aug 2026 14:08:50 +0200
Subject: [PATCH] =?UTF-8?q?docs(assert):=20correct=20the=20assert=5Ftrue?=
 =?UTF-8?q?=20guidance=20=E2=80=94=20arguments=20need=20an=20eval=20prefix?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

#991 documented `assert_true "test -d /tmp"` as the way to test a condition.
That does not work, and I should have run it before writing it down.

bashunit::run_command_or_eval invokes its argument as a *single command word*.
It never splits on whitespace, so `test -d /tmp` is looked up as a command whose
name is literally "test -d /tmp", which does not exist. The assertion fails with
`unknown command: test -d /tmp` -- correct behaviour, wrong advice.

The forms that work, each verified rather than assumed:

    assert_true "my_function"            # bare name
    assert_true "eval test -d /tmp"      # arguments need eval
    assert_true "eval [ -d /tmp ]"       # brackets work too, with eval

The `eval ` prefix is already a supported branch in run_command_or_eval; it was
simply never documented, so the single-word restriction looked like a bug rather
than a calling convention.

Snapshot regenerated. The underlying question -- whether requiring `eval` is the
right interface, given how surprising `assert_true "grep -q foo file"` failing
is -- is filed separately.
---
 docs/assertions.md                            | 20 ++++++++++++++-----
 ...it_should_display_all_assert_docs.snapshot | 13 +++++-------
 2 files changed, 20 insertions(+), 13 deletions(-)

diff --git a/docs/assertions.md b/docs/assertions.md
index 3591065d..783edbb8 100644
--- a/docs/assertions.md
+++ b/docs/assertions.md
@@ -36,11 +36,21 @@ to narrow it (`bashunit doc json`).
 ## assert_true
 > `assert_true bool|function|command`
 
-Takes a **command**, not a test expression. A bracketed condition of the form
-used inside `if` is run as a command word, so the shell reports exit code 127 and
-the assertion fails with `unknown command`. Use the `test` builtin instead —
-`assert_true "test -d /tmp"` — or a purpose-built assertion such as
-`assert_directory_exists`.
+The argument is run as a **single command word**, so it must be a bare command or
+function name with no arguments. Anything with arguments — including a bracketed
+condition of the form used inside `if` — is treated as one long command name, and
+the assertion fails with `unknown command`.
+
+Prefix with `eval` to run anything more than a bare name:
+
+```bash
+assert_true "my_function"            # bare name: works
+assert_true "eval test -d /tmp"      # arguments: needs eval
+assert_true "eval grep -q foo file"  # arguments: needs eval
+```
+
+A purpose-built assertion is usually clearer still — `assert_directory_exists`
+rather than a hand-rolled `test -d`.
 
 Reports an error if the argument result in a truthy value: `true` or `0`.
 
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
index 53f416a7..2139b6f3 100644
--- 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
@@ -2,15 +2,12 @@
 --------------
 > `assert_true bool|function|command`
 
-Takes a **command**, not a test expression. A bracketed condition of the form
-used inside `if` is run as a command word, so the shell reports exit code 127 and
-the assertion fails with `unknown command`. Use the `test` builtin instead —
-`assert_true "test -d /tmp"` — or a purpose-built assertion such as
-`assert_directory_exists`.
+The argument is run as a **single command word**, so it must be a bare command or
+function name with no arguments. Anything with arguments — including a bracketed
+condition of the form used inside `if` — is treated as one long command name, and
+the assertion fails with `unknown command`.
 
-Reports an error if the argument result in a truthy value: `true` or `0`.
-
-- assert_false is similar but different.
+Prefix with `eval` to run anything more than a bare name:
 
 
 ## assert_false