From 95f94cf36d6459687226d52c8c5ba8505f283ee8 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Mon, 16 Nov 2026 04:10:15 +0000 Subject: [PATCH] test(docs): run the get-started page's commands The doc walkthrough checked the tutorial and the how-to, reference and explanation pages, but not get-started.org, the first page a site administrator reads. A forbidden path in one of its bash blocks, or a quoted output the binary no longer prints, passed the suite: with --out-dir /path/to/eon-inspect in the inspect block and shards=2 in the quoted shard line, main's doc_walkthrough still passes. org_files() now includes get-started.org, so its bash blocks follow the same path rules. get_started_blocks_print_what_the_page_quotes runs each block with the built binary first on PATH and /tmp moved to a temporary directory, and compares stdout with the example block that follows it. The stack admit block must exit 78 and leave its reservation directory empty, as the page says. Both checks fail on those two edits. The page itself needs no change: all four blocks print what it quotes. --- changelog.d/+walkthrough-get-started.misc.md | 1 + tests/doc_walkthrough.rs | 70 ++++++++++++++++++-- 2 files changed, 64 insertions(+), 7 deletions(-) create mode 100644 changelog.d/+walkthrough-get-started.misc.md diff --git a/changelog.d/+walkthrough-get-started.misc.md b/changelog.d/+walkthrough-get-started.misc.md new file mode 100644 index 00000000..e714c65e --- /dev/null +++ b/changelog.d/+walkthrough-get-started.misc.md @@ -0,0 +1 @@ +The doc walkthrough tests cover `get-started.org`: its bash blocks follow the same path rules as the other pages, and each block is run and must print the output the page quotes, with `stack admit` exiting 78. diff --git a/tests/doc_walkthrough.rs b/tests/doc_walkthrough.rs index 6ab280fc..8c80aef8 100644 --- a/tests/doc_walkthrough.rs +++ b/tests/doc_walkthrough.rs @@ -1,8 +1,9 @@ -//! The tutorial, how-tos, reference, and explanation pages are commands -//! a checkout can run. +//! The get-started page, the tutorial, how-tos, reference, and explanation +//! pages are commands a checkout can run. //! //! Bash blocks must not point at a path this repository does not have. -//! The report commands are executed, and the page must quote their output. +//! The report commands and the get-started blocks are executed, and the +//! page must quote their output. use std::path::{Path, PathBuf}; use std::process::Command; @@ -12,7 +13,10 @@ fn root() -> PathBuf { } fn org_files() -> Vec { - let mut files = vec![root().join("docs/orgmode/tutorial.org")]; + let mut files = vec![ + root().join("docs/orgmode/get-started.org"), + root().join("docs/orgmode/tutorial.org"), + ]; for dir in ["howto", "reference", "explanation"] { let path = root().join("docs/orgmode").join(dir); let mut names: Vec<_> = std::fs::read_dir(&path) @@ -27,11 +31,21 @@ fn org_files() -> Vec { } fn bash_blocks(text: &str) -> Vec { + org_blocks(text, "#+begin_src bash\n", "#+end_src") +} + +fn example_blocks(text: &str) -> Vec { + org_blocks(text, "#+begin_example\n", "#+end_example") +} + +fn org_blocks(text: &str, open: &str, close: &str) -> Vec { let mut blocks = Vec::new(); let mut rest = text; - while let Some(start) = rest.find("#+begin_src bash\n") { - rest = &rest[start + "#+begin_src bash\n".len()..]; - let end = rest.find("#+end_src").expect("bash block closed"); + while let Some(start) = rest.find(open) { + rest = &rest[start + open.len()..]; + let end = rest + .find(close) + .unwrap_or_else(|| panic!("{close} missing")); blocks.push(rest[..end].to_string()); rest = &rest[end..]; } @@ -93,6 +107,48 @@ fn howto_bash_blocks_name_files_in_this_checkout() { } } +#[test] +fn get_started_blocks_print_what_the_page_quotes() { + let page = std::fs::read_to_string(root().join("docs/orgmode/get-started.org")).unwrap(); + let commands = bash_blocks(&page); + let quoted = example_blocks(&page); + assert_eq!(commands.len(), quoted.len(), "one quoted output per block"); + // The page writes under /tmp; each run gets its own directory instead. + let tmp = tempfile::tempdir().expect("temp"); + let scratch = format!("{}/", tmp.path().display()); + let bin = Path::new(env!("CARGO_BIN_EXE_eb-stack")).parent().unwrap(); + let path = format!( + "{}:{}", + bin.display(), + std::env::var("PATH").unwrap_or_default() + ); + for (command, expected) in commands.iter().zip("ed) { + let output = Command::new("bash") + .current_dir(root()) + .env("PATH", &path) + .args(["-euo", "pipefail", "-c"]) + .arg(command.replace("/tmp/", &scratch)) + .output() + .expect("spawn bash"); + let stdout = String::from_utf8_lossy(&output.stdout).replace(&scratch, "/tmp/"); + assert_eq!( + &stdout, + expected, + "{command}\nstderr:\n{}", + String::from_utf8_lossy(&output.stderr) + ); + let status = if command.contains("eb-stack stack admit") { + 78 + } else { + 0 + }; + assert_eq!(output.status.code(), Some(status), "{command}"); + } + assert!(page.contains("The exit status is 78.")); + let reservations = tmp.path().join("eb-stack-docs/admit-no"); + assert_eq!(std::fs::read_dir(reservations).unwrap().count(), 0); +} + #[test] fn report_howtos_quote_the_fixture_commands() { let tmp = tempfile::tempdir().expect("temp");