Skip to content

docs(assert): correct the assert_true guidance — arguments need an eval prefix - #993

Merged
Chemaclass merged 1 commit into
mainfrom
docs/assert-true-eval-prefix
Aug 8, 2026
Merged

docs(assert): correct the assert_true guidance — arguments need an eval prefix#993
Chemaclass merged 1 commit into
mainfrom
docs/assert-true-eval-prefix

Conversation

@Chemaclass

Copy link
Copy Markdown
Member

🤔 Background

#991 documented assert_true "test -d /tmp" as the way to test a condition. That doesn't 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 literally named test -d /tmp. The assertion fails with unknown command: test -d /tmp — correct behaviour, wrong advice.

💡 The forms that actually work

Each verified by running it, not 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, which made the single-word restriction look like a bug rather than a calling convention.

📋 Follow-up

Whether requiring eval is the right interface at all — given how surprising it is that assert_true "grep -q foo file" fails — is worth deciding separately, and I'll file it.

✅ Verification

Doc snapshot regenerated. make sa · make lint · full suite and acceptance green.

…al prefix

#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.
@Chemaclass Chemaclass added the documentation Improvements or additions to documentation label Aug 8, 2026
@Chemaclass Chemaclass self-assigned this Aug 8, 2026
@Chemaclass
Chemaclass merged commit 0d311e4 into main Aug 8, 2026
37 checks passed
@Chemaclass
Chemaclass deleted the docs/assert-true-eval-prefix branch August 8, 2026 12:14
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant