docs: line endings and missing hunks stated once, in the README's writing a test; the userguide points there.
commit 8ab33487b8bd6fbcf2ba12e75cc24168c6d63225 · parent e2e23564a8
· browse this tree
Ximianth, 2026-10-24 16:01:30 UTC
diff --git a/README.md b/README.md index fbec273..d58e490 100644 --- a/README.md +++ b/README.md @@ -81,12 +81,11 @@ Each case runs it in a fresh bash, so it's a clean shell: If it calls helpers, pass them to `testmarktest_provide helper1 helper2` first. **What gets checked** is everything the function prints, stdout and stderr together, in order. -Two things get added, only when they're needed, so the fixture for a tool that works is just its output: +If the function exits nonzero, a last line `exit status: N` is added, so a case can't pass while its tool fails, unless the fixture says it should. +On success nothing is added: the fixture for a tool that works is just its output. -- If the function exits nonzero, a last line `exit status: N`. A case can't pass while its tool fails, unless the fixture says it should. -- If the output doesn't end in a newline, it gets one, then a line `\ No newline at end of output`. - -Output with CRLF line endings fails the case; normalize it in the function, with `tr -d '\r'`. +Line endings don't count. +CRLF reads as LF, and a missing final newline is added, in hunks and in output alike. **`testmarktest_run DOC...`** runs every case, prints a `PASS` or `FAIL` line for each, and writes the docs if `TESTMARK_REGEN` is set. Doc paths are relative to the test script. @@ -100,6 +99,7 @@ testmarktest_rule_basic '*/script' exercise_script testmarktest_rule_basic '*/input' exercise_mytool ``` +Nothing adds hunks. The output hunk must exist already, even if empty: regen fills in a block that's there, and a missing one fails the case. That's why the workflow starts with an empty block. diff --git a/docs/userguide/going-it-alone.md b/docs/userguide/going-it-alone.md index 7bbcac5..24dad95 100644 --- a/docs/userguide/going-it-alone.md +++ b/docs/userguide/going-it-alone.md @@ -102,16 +102,7 @@ Rules to know So feed a check with `testmark_check doc NAME < <(cmd)`, not `cmd | testmark_check doc NAME`; and don't call these inside `$(...)`, or inside a test helper that runs its command there. -### end output with a newline, and don't use CRLF +### all the other usual rules still apply -Hunk bodies are whole lines, and the parser reads CRLF line endings as LF, -so a body always ends in a newline (unless it's empty), and never holds a CRLF. -Output that doesn't fit that could never match, and regen couldn't fix it either: the next parse would read back something different. -So `testmark_check` refuses such output with an error, rather than letting the test fail on every run. -Fix it in the command you're checking, with `| tr -d '\r'`, or by printing the last newline. - -### the hunk must already exist - -Nothing adds hunks. -`testmark_check` and `testmark_patch` need the hunk to be there, in regen too, and `testmark_write` only rewrites the bodies of hunks that are there. -Start with an empty block, and let regen fill it. +The rules in the README's [writing a test](../../README.md#writing-a-test) about line endings and missing hunks hold here too: +those are properties of the primitives.