test: replace fixture prose with field placeholders

tests/cli.rs

@@ -5,16 +5,19 @@
 //! exist in `main.rs`: argument parsing, the directory walk, the exclude rules, the shape of each
 //! subcommand's output, and the exit status.
 //!
-//! The fixtures are deliberately kept small and boring. They exist to be parsed, not read.
+//! The fixtures are deliberately kept small and boring. They exist to be parsed, not read, so a
+//! statement is identified here by its date rather than by its title.
 
 use assert_cmd::Command;
 use predicates::prelude::*;
 
 /// A tree of three files, one per supported language, holding four valid Y-Statements between
-/// them. `storage.rs` holds two so that per-file grouping in `list` output gets exercised.
+/// them, dated 2024-01-15, 2024-01-22, 2024-03-02, and 2024-04-09. `storage.rs` holds the first
+/// two so that per-file grouping in `list` output gets exercised.
 const CLEAN: &str = "tests/fixtures/clean";
 
-/// A tree holding a single Y-Statement whose second paragraph doesn't follow the format.
+/// A tree holding a single Y-Statement, dated 2024-05-20, whose second paragraph doesn't follow
+/// the format.
 const BROKEN: &str = "tests/fixtures/broken";
 
 fn yadr() -> Command {
@@ -37,18 +40,10 @@ fn list_finds_statements_in_every_supported_language() {
         .args(["ls", CLEAN])
         .assert()
         .success()
-        .stdout(predicate::str::contains(
-            "2024-01-15 Store timestamps as UTC",
-        ))
-        .stdout(predicate::str::contains(
-            "2024-01-22 Fail closed on an unreadable file",
-        ))
-        .stdout(predicate::str::contains(
-            "2024-03-02 Retry with exponential backoff",
-        ))
-        .stdout(predicate::str::contains(
-            "2024-04-09 Pin the toolchain in the lock file",
-        ));
+        .stdout(predicate::str::contains("2024-01-15 <title>"))
+        .stdout(predicate::str::contains("2024-01-22 <title>"))
+        .stdout(predicate::str::contains("2024-03-02 <title>"))
+        .stdout(predicate::str::contains("2024-04-09 <title>"));
 }
 
 /// The two statements in `storage.rs` should appear under a single `==>` heading for that file,
@@ -75,7 +70,7 @@ fn list_reports_the_most_recent_change() {
         .assert()
         .success()
         .stdout(predicate::str::contains(
-            "2024-01-15 Store timestamps as UTC (last changed: 2024-02-01)",
+            "2024-01-15 <title> (last changed: 2024-02-01)",
         ));
 }
 
@@ -108,15 +103,12 @@ fn show_prints_one_statement_in_full() {
 
     // the source location, so the reader can go and find it
     assert!(
-        stdout.contains("tests/fixtures/clean/retry.py:3"),
+        stdout.contains("tests/fixtures/clean/retry.py:6"),
         "no source location in:\n{stdout}"
     );
     // reflowed onto one line per paragraph, rather than as it was wrapped in the comment
     assert!(
-        stdout.contains(
-            "In the context of talking to an upstream service that occasionally rejects requests, \
-             we faced the question of how quickly to retry."
-        ),
+        stdout.contains("In the context of <ctx>, we faced <con>."),
         "paragraph was not reflowed in:\n{stdout}"
     );
     // and only the statement that was asked for

tests/fixtures/broken/malformed.rs

@@ -5,10 +5,9 @@
 // decided for", so the diagnostic should name paragraph 2.
 
 /*
- * YADR: 2024-05-20 A statement that does not follow the format
+ * YADR: 2024-05-20 <title>
  *
- * In the context of testing what yadr reports for a malformed statement, we faced the need
- * for an input that is recognisably a Y-Statement but does not parse as one.
+ * In the context of <ctx>, we faced <con>.
  *
  * We chose one of the options available to us, and forgot to write the rest of the format.
  */

tests/fixtures/clean/retry.py

@@ -1,17 +1,17 @@
 # A fixture for yadr's end-to-end tests. Never executed; only ever read as text.
+#
+# The first paragraph is wrapped across two comment lines even though it would fit on one, so that
+# `show_prints_one_statement_in_full` in `tests/cli.rs` has a reflow to catch.
 
-# YADR: 2024-03-02 Retry with exponential backoff
+# YADR: 2024-03-02 <title>
 #
-# In the context of talking to an upstream service that occasionally rejects requests, we
-# faced the question of how quickly to retry.
+# In the context of <ctx>, we
+# faced <con>.
 #
-# We decided for doubling the delay after each attempt up to a ceiling, and neglected both
-# retrying immediately and giving up after the first failure.
+# We decided for <opt>, and neglected <alt>.
 #
-# We did this to achieve recovery from brief outages without adding load to a service that is
-# already struggling, accepting that a request can take much longer than usual to resolve.
+# We did this to achieve <qua>, accepting <dwn>.
 #
-# We think this is the right trade-off because the outages we see in practice are short, and
-# a caller that cannot wait can impose its own deadline.
+# We think this is the right trade-off because <why>.
 def fetch():
     pass

tests/fixtures/clean/storage.rs

@@ -1,37 +1,30 @@
 // A fixture for yadr's end-to-end tests. This file is never compiled; the test suite only ever
 // runs the `yadr` binary over it and asserts on what comes out. Two Y-Statements live here so that
-// the tests cover a file containing more than one.
+// the tests cover a file containing more than one, and they use different comment syntaxes so that
+// both of Rust's are covered.
 
 /*
- * YADR: 2024-01-15 Store timestamps as UTC
+ * YADR: 2024-01-15 <title>
  *
- * In the context of comparing event timestamps recorded on different machines, we faced
- * ambiguity about which offset a bare local timestamp had been written in.
+ * In the context of <ctx>, we faced <con>.
  *
- * We decided for storing every timestamp in UTC, and neglected recording the local offset
- * alongside each timestamp.
+ * We decided for <opt>, and neglected <alt>.
  *
- * We did this to achieve unambiguous ordering of events no matter where they were recorded,
- * accepting that rendering a timestamp in the recorder's own time zone needs a separate
- * lookup.
+ * We did this to achieve <qua>, accepting <dwn>.
  *
- * We think this is the right trade-off because ordering matters everywhere in the system,
- * whereas local-time rendering matters only in the user interface.
+ * We think this is the right trade-off because <why>.
  *
- * 2024-02-01: noted that the user interface is where the offset lookup happens.
+ * 2024-02-01: <chg>
  */
 fn store() {}
 
-// YADR: 2024-01-22 Fail closed on an unreadable file
+// YADR: 2024-01-22 <title>
 //
-// In the context of walking a source tree we do not control, we faced the question of what
-// to do when a file cannot be read.
+// In the context of <ctx>, we faced <con>.
 //
-// We decided for aborting the whole run, and neglected skipping the file with a warning.
+// We decided for <opt>, and neglected <alt>.
 //
-// We did this to achieve a guarantee that a successful run really did inspect everything,
-// accepting that one unreadable file stops the run.
+// We did this to achieve <qua>, accepting <dwn>.
 //
-// We think this is the right trade-off because a partial pass reported as a success is worse
-// than an obvious failure.
+// We think this is the right trade-off because <why>.
 fn read() {}

tests/fixtures/clean/toolchain.nix

@@ -1,17 +1,12 @@
 # A fixture for yadr's end-to-end tests. Never evaluated; only ever read as text.
 
-# YADR: 2024-04-09 Pin the toolchain in the lock file
+# YADR: 2024-04-09 <title>
 #
-# In the context of builds that have to reproduce on a colleague's machine and in CI, we
-# faced drift between whichever toolchain each of them happened to have installed.
+# In the context of <ctx>, we faced <con>.
 #
-# We decided for pinning an exact toolchain version in the lock file, and neglected tracking
-# the latest stable release.
+# We decided for <opt>, and neglected <alt>.
 #
-# We did this to achieve builds that produce the same result everywhere, accepting that
-# picking up a new compiler becomes a deliberate change rather than something that happens on
-# its own.
+# We did this to achieve <qua>, accepting <dwn>.
 #
-# We think this is the right trade-off because a build that only fails on someone else's
-# machine costs far more to chase down than an occasional version bump.
+# We think this is the right trade-off because <why>.
 { }