From 7c4a1cba1a76d6c6f49f8d467b12453edbc1cda8 Mon Sep 17 00:00:00 2001 From: Eugene Volen Date: Wed, 11 Nov 2026 15:15:18 +0200 Subject: [PATCH] feat(diagnose): take the symptom from a file or stdin with --symptom-file A pasted error does not survive a shell as an argument: bash and PowerShell run a $(...) even inside double quotes, a stray quote ends the argument early, cmd.exe has no single quotes, and an error starting with "-" is refused as a flag. `rocm diagnose --symptom-file ` reads the text from a file, or from standard input when PATH is "-", so the shell only ever parses the fixed command. The text that arrives is matched as --symptom would match it, with one trailing line break removed (heredocs, editors and PowerShell's pipe to a native command each add one). A UTF-8 byte-order mark is dropped and UTF-16 with a byte-order mark, which Windows PowerShell's ">" writes, is decoded; anything else must be UTF-8. An unreadable file, input that is not text, or input over 16 MiB is a usage error (exit 2) with the diagnose usage line, never a panic. With a terminal on stdin the CLI says how to end the paste. The two flags are mutually exclusive. Windows PowerShell 5.1 pipes text to a native program as ASCII, turning every other character into "?", so the docs have PowerShell users save the clipboard with `Get-Clipboard -Raw > error.txt` and pass that file rather than pipe it. The serve OOM note keeps printing `rocm diagnose --symptom ''`: it already falls back to a canonical symptom when the line cannot be one intact single-quoted word, and it is only printed where vLLM runs (Linux, WSL), so the printed command stays runnable as is. The advised-command scanner now treats a heredoc ("<<") as a redirection rather than the start of a , so the documented bash form is checked and a command after it in the same list is still split off and checked. Covered by unit tests for decoding, trimming and the error paths, a clap test, a scanner test, and diagnose-59 to diagnose-61: a paste full of quotes, $(...) and a leading "-" piped through bash, cmd.exe and Windows PowerShell gets the same causes, scores and evidence as the same text passed as one argument; a paste typed at a terminal is explained and leaves a screen containing the whole report the argument form prints, which must differ from the report without a symptom (Linux only, like the suite's other pseudo-terminal scenarios); and unusable files are refused as usage errors. ROCMAI-955 Signed-off-by: Eugene Volen --- README.md | 35 +- apps/rocm/src/advised_commands.rs | 48 ++- apps/rocm/src/cli.rs | 55 ++- apps/rocm/src/main.rs | 4 + apps/rocm/src/symptom_input.rs | 340 +++++++++++++++ docs/architecture.md | 2 + docs/manual-testing.md | 35 ++ docs/testing.md | 59 +++ docs/wsl.md | 2 +- tests/e2e-cucumber/features/diagnose.feature | 47 ++ tests/e2e-cucumber/tests/e2e.rs | 11 + .../tests/e2e/symptom_file_steps.rs | 405 ++++++++++++++++++ 12 files changed, 1038 insertions(+), 5 deletions(-) create mode 100644 apps/rocm/src/symptom_input.rs create mode 100644 tests/e2e-cucumber/tests/e2e/symptom_file_steps.rs diff --git a/README.md b/README.md index 6cd4841af2..d95eff8b2e 100644 --- a/README.md +++ b/README.md @@ -356,7 +356,7 @@ Windows. The Vulkan driver version is not shown. ### Diagnose and fix ``` -rocm diagnose [--symptom TEXT] [--top N] [--json] [--distro [NAME] | --report [--send]] +rocm diagnose [--symptom TEXT | --symptom-file PATH] [--top N] [--json] [--distro [NAME] | --report [--send]] rocm diagnose --model [--context-size N] [--kv-cache-type f16|q8_0|q4_0] [--json] rocm fix [] [--yes] [--dry-run] [--device-index N] [--json] ``` @@ -373,7 +373,38 @@ position. `rocm diagnose` takes these flags: -- `--symptom` takes raw error text to sharpen keyword scoring. +- `--symptom` takes raw error text to sharpen keyword scoring. Your shell + reads that text first: quotes, `$(...)` and a leading `-` in a pasted error + can be changed, run, or taken as a flag. +- `--symptom-file PATH` reads the same text from a file instead, or from + standard input when PATH is `-`, so no quoting is needed. It cannot be + combined with `--symptom`. The text that arrives is matched as `--symptom` + would match it, minus one trailing line break. A UTF-8 byte-order mark is + dropped and a UTF-16 file with a byte-order mark (what Windows PowerShell's + `>` writes) is decoded; anything else must be UTF-8. A file that cannot be + read, input that is not text, or input larger than 16 MiB is a usage error + (exit code 2). With nothing piped in, paste the error at the terminal and + end it with Ctrl-D at the start of a line (Ctrl-Z then Enter on Windows). + + ```bash + # bash (Linux, WSL): the quoted 'EOF' keeps the shell out of the paste + rocm diagnose --symptom-file - <<'EOF' + + EOF + ``` + + ```powershell + # PowerShell: save the clipboard to a file first. Windows PowerShell 5.1 + # pipes text to a program as ASCII, so `Get-Clipboard | rocm ...` would + # turn every non-ASCII character in the error into "?". + Get-Clipboard -Raw > error.txt + rocm diagnose --symptom-file error.txt + ``` + + ```bat + :: cmd.exe: save the error to a file first + rocm diagnose --symptom-file error.txt + ``` - On Windows, `diagnose` also checks the age of the Visual C++ runtime, not only whether it is there. The runtime in `System32` must be 14.40 or newer (`fix-21-msvc-redist-outdated`). Programs built with a recent toolset, such diff --git a/apps/rocm/src/advised_commands.rs b/apps/rocm/src/advised_commands.rs index 61d7e2b9ec..6f5791ffd6 100644 --- a/apps/rocm/src/advised_commands.rs +++ b/apps/rocm/src/advised_commands.rs @@ -640,6 +640,13 @@ fn split_shell_list(text: &str) -> Vec { } match ch { '"' | '\'' => quote = Some(ch), + // `<<` starts a heredoc, a redirection, not a ``: + // taken whole, so neither `<` opens one. + '<' if next == Some('<') => { + current.push_str("<<"); + index += 2; + continue; + } // `<` opens a placeholder only at a word start and before a // non-space: ` < file` is a redirection. '<' if at_word_start && next.is_some_and(|c| !c.is_whitespace()) => closers.push('>'), @@ -677,7 +684,7 @@ pub(crate) fn command_parts(raw: &str) -> Vec { } let mut command = command.to_owned(); for marker in [ - " >> ", " > ", " < ", " 2>", " (", " —", " –", " → ", " before ", " then ", + " >> ", " > ", " <<", " < ", " 2>", " (", " —", " –", " → ", " before ", " then ", ] { if let Some(position) = command.find(marker) { command.truncate(position); @@ -2109,6 +2116,45 @@ fn every_command_in_a_shell_list_is_checked() { ); } +/// A heredoc is a redirection like ` < file`: `rocm diagnose --symptom-file - +/// <<'EOF'` hands the command a paste on standard input, so the `<<` and its +/// delimiter are not arguments. +#[test] +fn a_heredoc_ends_the_command() { + for raw in [ + "rocm diagnose --symptom-file - <<'EOF'", + "rocm diagnose --symptom-file - <<\"EOF\"", + "rocm diagnose --symptom-file - << EOF", + "rocm diagnose --symptom-file - <`, so a command after it in the + // same list is still split off and checked. + for raw in [ + "rocm diagnose --symptom-file - <<'EOF' && rocm frobnicate --x", + "rocm diagnose --symptom-file - <, + /// Read the error text from a file instead, or from standard input + /// when PATH is `-`, so no shell quoting is needed. + /// + /// The text that arrives is matched as `--symptom` would match it, + /// with one trailing line break removed (shells and editors add one). + /// A UTF-8 byte-order mark is dropped, and a file with a UTF-16 + /// byte-order mark, as Windows PowerShell's `>` writes, is decoded; + /// anything else must be UTF-8. An unreadable file, input that is not + /// text, or input larger than 16 MiB is a usage error (exit code 2). + /// For example: `rocm diagnose --symptom-file error.txt`. In + /// PowerShell, save the clipboard first + /// (`Get-Clipboard -Raw > error.txt`): Windows PowerShell 5.1 pipes + /// text to a program as ASCII, turning any other character into `?`. + /// With nothing piped in, paste the text at the terminal and end it + /// with Ctrl-D at the start of a line (Ctrl-Z then Enter on Windows). + #[arg(long, value_name = "PATH", conflicts_with = "symptom")] + symptom_file: Option, /// Show at most this many matches (default 5). #[arg(long, default_value_t = 5)] top: usize, @@ -1894,6 +1915,38 @@ mod tests { Cli::try_parse_from(argv) } + // `--symptom-file` exists because a pasted error does not survive the shell + // as an argument: one starting with `-` is not even accepted as + // `--symptom`'s value. The file form takes `-` (stdin) and any path, and + // the two sources cannot both be given. + #[test] + fn diagnose_takes_the_symptom_from_a_file_or_stdin_but_not_with_symptom() { + assert!( + parse_diagnose(&["--symptom", "-x HIP error"]).is_err(), + "a leading minus is read as a flag, which is what --symptom-file avoids" + ); + for path in ["-", "error.txt"] { + match parse_diagnose(&["--symptom-file", path]) { + Ok(Cli { + command: + Some(Command::Diagnose { + symptom, + symptom_file, + .. + }), + .. + }) => { + assert_eq!(symptom, None); + assert_eq!(symptom_file, Some(PathBuf::from(path))); + } + other => panic!("expected diagnose for {path:?}, got {other:?}"), + } + } + let error = parse_diagnose(&["--symptom", "oom", "--symptom-file", "-"]) + .expect_err("--symptom and --symptom-file are exclusive"); + assert_eq!(error.kind(), clap::error::ErrorKind::ArgumentConflict); + } + // The context options describe the model being asked about, so without // `--model` they would be accepted and silently do nothing. #[test] diff --git a/apps/rocm/src/main.rs b/apps/rocm/src/main.rs index 776590c87d..f788a51dcd 100644 --- a/apps/rocm/src/main.rs +++ b/apps/rocm/src/main.rs @@ -72,6 +72,7 @@ mod services_text; mod setup_cmd; mod shell_quote; mod storage; +mod symptom_input; mod system_packages; #[cfg(test)] mod test_support; @@ -659,6 +660,7 @@ fn dispatch(cli: Cli) -> Result<()> { Some(Command::Examine { json, framework }) => examine(json, framework.into()), Some(Command::Diagnose { symptom, + symptom_file, top, json, distro, @@ -668,6 +670,8 @@ fn dispatch(cli: Cli) -> Result<()> { report, send, }) => { + let symptom = symptom_input::resolve(symptom, symptom_file.as_deref()) + .map_err(|error| clap_exit_code(symptom_input::usage_error(&error)))?; let model = model.map(|model_ref| { diagnose_model::ModelQuery::new(model_ref, context_size, kv_cache_type) }); diff --git a/apps/rocm/src/symptom_input.rs b/apps/rocm/src/symptom_input.rs new file mode 100644 index 0000000000..162af5b07e --- /dev/null +++ b/apps/rocm/src/symptom_input.rs @@ -0,0 +1,340 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! `rocm diagnose --symptom-file `: reading the symptom text from a file, +//! or from standard input when the path is `-`, instead of from a shell +//! argument. +//! +//! A pasted error is hostile to every shell's argument parser: bash runs a +//! `$(...)` inside double quotes, PowerShell does the same and also treats a +//! leading `-` and a stray quote its own way, and cmd.exe has no single-quote at +//! all. Reading the text as data sidesteps all three, so the only rule this +//! module adds is how the bytes become the string `--symptom` would have +//! delivered: +//! +//! - one trailing line break (`\n` or `\r\n`) is removed. A heredoc, `echo`, +//! an editor's final newline and PowerShell's pipe to a native command each +//! add exactly one, and none of them is part of the paste. Only one: any +//! other whitespace is the user's own text and is passed through unchanged; +//! - a UTF-8 byte-order mark is dropped (PowerShell adds one when +//! `$OutputEncoding` is UTF-8 with a BOM, and `Out-File -Encoding utf8` writes +//! one), and text with a UTF-16 byte-order mark, which Windows PowerShell's +//! `>` writes, is decoded. On Windows `--symptom` arrives as UTF-16 and is +//! converted the same way, so the matcher sees the same string; +//! - anything else must be UTF-8. Input that is not, an unreadable path, and +//! input past [`MAX_SYMPTOM_BYTES`] are refused with a [`SymptomFileError`], +//! which the dispatcher turns into a usage error (exit code 2). +//! +//! When the path is `-` and standard input is a terminal, nothing has been +//! piped in, so the user is told on stderr how to paste the text and end it +//! ([`TERMINAL_PASTE_HINT`]); otherwise the command would wait silently. + +use std::fmt; +use std::io::{self, IsTerminal, Read, Write as _}; +use std::path::Path; + +/// The `--symptom-file` value that means standard input. +pub(crate) const STDIN_PATH: &str = "-"; + +/// The most a symptom may be. A whole engine log fits; a device or an endless +/// pipe passed by mistake does not get read into memory without bound. +pub(crate) const MAX_SYMPTOM_BYTES: u64 = 16 * 1024 * 1024; + +/// Printed on stderr when `--symptom-file -` finds standard input is a +/// terminal: the user is expected to paste now, and must be told how to finish. +/// Ctrl-D at the start of a line ends terminal input on Linux; on Windows the +/// console's end-of-input is Ctrl-Z followed by Enter. +pub(crate) const TERMINAL_PASTE_HINT: &str = "Paste the error text, then end it with Ctrl-D at the \ +start of a line (Ctrl-Z then Enter on Windows)."; + +/// Why a `--symptom-file` could not be turned into symptom text. +#[derive(Debug)] +pub(crate) enum SymptomFileError { + /// The file could not be opened or read. + Unreadable { source: String, error: io::Error }, + /// The bytes are not UTF-8 (or UTF-16 with a byte-order mark). + NotText { source: String, detail: String }, + /// More than [`MAX_SYMPTOM_BYTES`]. + TooLarge { source: String }, +} + +impl fmt::Display for SymptomFileError { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::Unreadable { source, error } => { + write!(f, "could not read the symptom from {source}: {error}") + } + Self::NotText { source, detail } => write!( + f, + "the symptom in {source} is not text: {detail}. Save it as UTF-8 text and try again" + ), + Self::TooLarge { source } => write!( + f, + "the symptom in {source} is larger than {} MiB; pass only the lines around the failure", + MAX_SYMPTOM_BYTES / (1024 * 1024) + ), + } + } +} + +impl std::error::Error for SymptomFileError {} + +/// `error` as the usage error clap would have raised for a bad +/// `--symptom-file` value: printed with `rocm diagnose`'s usage line, exit +/// code 2. The file is read after parsing, so clap cannot raise it itself. +pub(crate) fn usage_error(error: &SymptomFileError) -> clap::Error { + let mut command = ::command(); + // Building sets each subcommand's full `rocm diagnose` name for the usage line. + command.build(); + command + .find_subcommand_mut("diagnose") + .expect("the diagnose subcommand is defined") + .error( + clap::error::ErrorKind::ValueValidation, + format!("--symptom-file: {error}"), + ) +} + +/// The symptom text `rocm diagnose` matches on: `--symptom` as given, or the +/// contents of `--symptom-file` (clap makes the two mutually exclusive). +pub(crate) fn resolve( + symptom: Option, + symptom_file: Option<&Path>, +) -> Result, SymptomFileError> { + let Some(path) = symptom_file else { + return Ok(symptom); + }; + if path.as_os_str() == STDIN_PATH { + let stdin = io::stdin(); + if stdin.is_terminal() { + // A closed stderr must not turn the hint into a panic. + let _ = writeln!(io::stderr(), "{TERMINAL_PASTE_HINT}"); + } + return read_symptom(stdin.lock(), "standard input").map(Some); + } + let source = path.display().to_string(); + let file = std::fs::File::open(path).map_err(|error| SymptomFileError::Unreadable { + source: source.clone(), + error, + })?; + read_symptom(file, &source).map(Some) +} + +/// Read at most [`MAX_SYMPTOM_BYTES`] from `reader` and decode it as described +/// in the module docs. `source` names the input in an error. +fn read_symptom(reader: impl Read, source: &str) -> Result { + let mut bytes = Vec::new(); + reader + .take(MAX_SYMPTOM_BYTES + 1) + .read_to_end(&mut bytes) + .map_err(|error| SymptomFileError::Unreadable { + source: source.to_owned(), + error, + })?; + if bytes.len() as u64 > MAX_SYMPTOM_BYTES { + return Err(SymptomFileError::TooLarge { + source: source.to_owned(), + }); + } + let text = decode(bytes).map_err(|detail| SymptomFileError::NotText { + source: source.to_owned(), + detail, + })?; + Ok(trim_one_trailing_line_break(text)) +} + +/// UTF-8 (a leading byte-order mark dropped), or UTF-16 announced by its +/// byte-order mark. The error says where decoding failed. Takes the buffer by +/// value so UTF-8 becomes the string in place, without a second buffer. +fn decode(mut bytes: Vec) -> Result { + if bytes.starts_with(&[0xEF, 0xBB, 0xBF]) { + bytes.drain(..3); + return utf8(bytes); + } + if let Some(rest) = bytes.strip_prefix(&[0xFF, 0xFE]) { + return utf16(rest, u16::from_le_bytes); + } + if let Some(rest) = bytes.strip_prefix(&[0xFE, 0xFF]) { + return utf16(rest, u16::from_be_bytes); + } + utf8(bytes) +} + +fn utf8(bytes: Vec) -> Result { + String::from_utf8(bytes).map_err(|error| { + format!( + "it is not valid UTF-8 (invalid byte at offset {})", + error.utf8_error().valid_up_to() + ) + }) +} + +fn utf16(bytes: &[u8], unit: fn([u8; 2]) -> u16) -> Result { + let chunks = bytes.chunks_exact(2); + if !chunks.remainder().is_empty() { + return Err( + "it starts with a UTF-16 byte-order mark but has an odd number of bytes".into(), + ); + } + let units: Vec = chunks.map(|pair| unit([pair[0], pair[1]])).collect(); + String::from_utf16(&units) + .map_err(|_| "it starts with a UTF-16 byte-order mark but is not valid UTF-16".into()) +} + +/// Remove one trailing `\n` or `\r\n`, and nothing else. +fn trim_one_trailing_line_break(mut text: String) -> String { + if text.ends_with("\r\n") { + text.truncate(text.len() - 2); + } else if text.ends_with('\n') { + text.pop(); + } + text +} + +#[cfg(test)] +mod tests { + use super::*; + + /// A paste every shell would mangle: double and single quotes, a command + /// substitution, a leading minus, a backtick and a percent sign. + const HOSTILE_PASTE: &str = + "-x \"HSA_STATUS_ERROR_INVALID_ISA\" it's $(touch pwned) `id` %PATH% & echo"; + + fn read(bytes: &[u8]) -> Result { + read_symptom(bytes, "test input") + } + + #[test] + fn a_paste_reaches_the_matcher_unchanged() { + assert_eq!(read(HOSTILE_PASTE.as_bytes()).unwrap(), HOSTILE_PASTE); + } + + #[test] + fn exactly_one_trailing_line_break_is_removed() { + assert_eq!(read(b"oom\n").unwrap(), "oom"); + assert_eq!(read(b"oom\r\n").unwrap(), "oom"); + assert_eq!(read(b"oom\n\n").unwrap(), "oom\n"); + assert_eq!(read(b"oom\r\n\r\n").unwrap(), "oom\r\n"); + // A bare `\r` is a progress-bar repaint, not a line ending a shell added. + assert_eq!(read(b"oom\r").unwrap(), "oom\r"); + assert_eq!(read(b" oom ").unwrap(), " oom "); + assert_eq!(read(b"").unwrap(), ""); + assert_eq!(read(b"a\nb\n").unwrap(), "a\nb"); + } + + #[test] + fn a_utf8_byte_order_mark_is_dropped() { + let mut bytes = vec![0xEF, 0xBB, 0xBF]; + bytes.extend_from_slice(HOSTILE_PASTE.as_bytes()); + bytes.extend_from_slice(b"\r\n"); + assert_eq!(read(&bytes).unwrap(), HOSTILE_PASTE); + } + + #[test] + fn utf16_with_a_byte_order_mark_is_decoded() { + let text = format!("{HOSTILE_PASTE} \u{00e9}\u{1F600}\r\n"); + let mut le = vec![0xFF, 0xFE]; + let mut be = vec![0xFE, 0xFF]; + for unit in text.encode_utf16() { + le.extend_from_slice(&unit.to_le_bytes()); + be.extend_from_slice(&unit.to_be_bytes()); + } + let expected = format!("{HOSTILE_PASTE} \u{00e9}\u{1F600}"); + assert_eq!(read(&le).unwrap(), expected); + assert_eq!(read(&be).unwrap(), expected); + } + + #[test] + fn input_that_is_not_text_is_refused_with_where_it_failed() { + let error = read(b"HIP error \xff\xfe at").unwrap_err(); + assert!( + matches!(error, SymptomFileError::NotText { .. }), + "{error:?}" + ); + let message = error.to_string(); + assert!(message.contains("test input"), "{message}"); + assert!(message.contains("offset 10"), "{message}"); + assert!(message.contains("UTF-8"), "{message}"); + + // A UTF-16 BOM with an odd tail, and one with a lone surrogate. + assert!(matches!( + read(&[0xFF, 0xFE, 0x41]), + Err(SymptomFileError::NotText { .. }) + )); + assert!(matches!( + read(&[0xFF, 0xFE, 0x00, 0xD8]), + Err(SymptomFileError::NotText { .. }) + )); + } + + #[test] + fn input_past_the_limit_is_refused_without_reading_it_all() { + let endless = io::repeat(b'a'); + let error = read_symptom(endless, "an endless pipe").unwrap_err(); + assert!( + matches!(error, SymptomFileError::TooLarge { .. }), + "{error:?}" + ); + assert!(error.to_string().contains("16 MiB"), "{error}"); + + let at_limit = vec![b'a'; MAX_SYMPTOM_BYTES as usize]; + assert_eq!(read(&at_limit).unwrap().len(), at_limit.len()); + } + + #[test] + fn a_missing_file_is_unreadable_and_names_the_path() { + let dir = tempfile::tempdir().unwrap(); + let missing = dir.path().join("no-such-error.txt"); + let error = resolve(None, Some(&missing)).unwrap_err(); + assert!( + matches!(error, SymptomFileError::Unreadable { .. }), + "{error:?}" + ); + assert!( + error.to_string().contains(&missing.display().to_string()), + "{error}" + ); + } + + #[test] + fn a_file_is_read_and_symptom_alone_passes_through() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("error.txt"); + std::fs::write(&path, format!("{HOSTILE_PASTE}\n")).unwrap(); + assert_eq!( + resolve(None, Some(&path)).unwrap().as_deref(), + Some(HOSTILE_PASTE) + ); + assert_eq!( + resolve(Some("as typed\n".into()), None).unwrap().as_deref(), + Some("as typed\n"), + "--symptom is never trimmed: only a file's trailing line break is" + ); + assert_eq!(resolve(None, None).unwrap(), None); + } + + #[test] + fn a_bad_file_is_a_usage_error_naming_the_command() { + let error = usage_error(&SymptomFileError::TooLarge { + source: "standard input".into(), + }); + assert_eq!(error.exit_code(), 2); + let rendered = error.render().to_string(); + assert!( + rendered.contains("--symptom-file: the symptom in standard input is larger"), + "{rendered}" + ); + assert!(rendered.contains("Usage: rocm diagnose"), "{rendered}"); + } + + #[test] + fn a_directory_is_unreadable_not_a_panic() { + let dir = tempfile::tempdir().unwrap(); + let error = resolve(None, Some(dir.path())).unwrap_err(); + assert!( + matches!(error, SymptomFileError::Unreadable { .. }), + "{error:?}" + ); + } +} diff --git a/docs/architecture.md b/docs/architecture.md index fbd94b8757..a6e4e5584c 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -130,6 +130,7 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an | [`setup_cmd.rs`](../apps/rocm/src/setup_cmd.rs) | `rocm setup` (`setup`): the `setup status` text and `setup reset`, which clears the saved first-time prompt state. | relocation | | [`shell_quote.rs`](../apps/rocm/src/shell_quote.rs) | The CLI's one POSIX shell quoter (`shell_quote`, over `rocm-core`'s) and `has_terminal_control_character`, the predicate the chat tool-call guards refuse on. | flat | | [`storage.rs`](../apps/rocm/src/storage.rs) | `rocm storage`: a read-only report of what runtimes, downloads and engine installs occupy on disk, and guarded removal of old installs and downloads. | domain | +| [`symptom_input.rs`](../apps/rocm/src/symptom_input.rs) | `rocm diagnose --symptom-file`: turns a file, or standard input (`-`), into the symptom string `--symptom` would have delivered (`resolve`): one trailing line break removed, a UTF-8 byte-order mark dropped, UTF-16 with a byte-order mark decoded, a size cap (`MAX_SYMPTOM_BYTES`), and the hint printed when standard input is a terminal (`TERMINAL_PASTE_HINT`). Its `SymptomFileError` becomes a clap usage error (exit code 2) through `usage_error`, which `dispatch()` in [`main.rs`](../apps/rocm/src/main.rs) hands to `clap_exit_code` before calling `diagnose()` in [`diagnose_cmd.rs`](../apps/rocm/src/diagnose_cmd.rs), so the handler still receives a plain `Option`. Reached by qualified path. | domain | | [`system_packages.rs`](../apps/rocm/src/system_packages.rs) | Host system-package installs for SDK and engine installs: the distro-aware OpenMPI, libatomic and libnuma plans, the consent decision, and running them without a shell. | domain | | [`test_support.rs`](../apps/rocm/src/test_support.rs) | Test-only fixtures shared across the crate's module test suites, including the process-environment lock. | flat | | [`therock.rs`](../apps/rocm/src/therock.rs) | TheRock SDK install orchestration (`install_sdk`, the wheel and tarball paths) and the helpers that name an install and its folders; parent of the `therock/` children. | domain | @@ -856,6 +857,7 @@ Gherkin `.feature` files under `features/` backed by Rust step functions that dr | [`tests/e2e/serving_steps.rs`](../tests/e2e-cucumber/tests/e2e/serving_steps.rs) | Steps for [`model_serving.feature`](../tests/e2e-cucumber/features/model_serving.feature) and the serve steps other features reuse: `rocm serve` on each engine, ports, managed services and inference. | flat | | [`tests/e2e/skill_steps.rs`](../tests/e2e-cucumber/tests/e2e/skill_steps.rs) | Steps for [`rocm_doctor_skill.feature`](../tests/e2e-cucumber/features/rocm_doctor_skill.feature): drive `rocm` through the sequence the rocm-doctor skill prescribes and check its literal claims. | flat | | [`tests/e2e/storage_steps.rs`](../tests/e2e-cucumber/tests/e2e/storage_steps.rs) | Steps for [`storage.feature`](../tests/e2e-cucumber/features/storage.feature) and [`local_server_records.feature`](../tests/e2e-cucumber/features/local_server_records.feature): `rocm storage report` and the confirmation gate on `remove-downloads`. | flat | +| [`tests/e2e/symptom_file_steps.rs`](../tests/e2e-cucumber/tests/e2e/symptom_file_steps.rs) | Steps for the `rocm diagnose --symptom-file` scenarios of [`diagnose.feature`](../tests/e2e-cucumber/features/diagnose.feature) (diagnose-59 to diagnose-61): a hostile paste piped through each available shell, a paste typed at a pseudo-terminal through [`tui_driver.rs`](../tests/e2e-cucumber/tests/e2e/tui_driver.rs), and error files that cannot be read or are not text. | flat | | [`tests/e2e/therock_steps.rs`](../tests/e2e-cucumber/tests/e2e/therock_steps.rs) | Steps for [`therock_next_generation.feature`](../tests/e2e-cucumber/features/therock_next_generation.feature) and [`download_progress_pty.feature`](../tests/e2e-cucumber/features/download_progress_pty.feature): release layouts served from a loopback server, and one real GPU install. | flat | | [`tests/e2e/tui_driver.rs`](../tests/e2e-cucumber/tests/e2e/tui_driver.rs) | Pseudo-terminal driver for the dash and chat TUI: spawns the real binary under `portable-pty`, sends keys and reads the emulated `vt100` screen. | flat | | [`tests/e2e/uninstall_steps.rs`](../tests/e2e-cucumber/tests/e2e/uninstall_steps.rs) | Steps for [`uninstall.feature`](../tests/e2e-cucumber/features/uninstall.feature): `rocm uninstall` confined to the scenario root with `--keep-binaries` and redirected caches. | flat | diff --git a/docs/manual-testing.md b/docs/manual-testing.md index a2eb7dd454..35cbde7524 100644 --- a/docs/manual-testing.md +++ b/docs/manual-testing.md @@ -1556,3 +1556,38 @@ anything. Finally, `rocm diagnose --report --model /:Q4_K_M --context-size 8192` prints the report with no model section, and stderr says that `--model, --context-size were ignored` and nothing about the model was fetched. + +## 13. Pasting An Error Into `rocm diagnose` + +`rocm diagnose --symptom-file` takes a pasted error without shell quoting. +Copy a line that would break an argument, for example: + +```text +-v "HSA_STATUS_ERROR_INVALID_ISA" isn't it? $(echo ran > ran.txt) & echo ran > ran.txt +``` + +Then, in an empty directory, hand it over in each shell you have: + +- bash (Linux or WSL): run `rocm diagnose --symptom-file - <<'EOF'`, paste, + then type `EOF` on its own line. +- PowerShell (5.1 and 7): `Get-Clipboard -Raw > error.txt`, then + `rocm diagnose --symptom-file error.txt`. Not `Get-Clipboard | rocm ...`: + Windows PowerShell 5.1 pipes text to a program as ASCII and turns every + other character into `?`. +- cmd.exe: save the paste to `error.txt` with an editor, then + `rocm diagnose --symptom-file error.txt`. +- Any shell, nothing piped in: `rocm diagnose --symptom-file -`, paste at the + prompt, and end the input as the hint printed on the first line says. + +Expected result: + +- Each run reports the same causes as `rocm diagnose --symptom-file error.txt` + with the paste saved in `error.txt`, and exits 0. +- No `ran.txt` appears in the directory. +- `rocm diagnose --symptom-file no-such-file.txt`, the same flag on a binary + file (an image, say) and on a file larger than 16 MiB each print one error + naming the file and why, then the `Usage: rocm diagnose` line, and exit 2. +- In Windows PowerShell 5.1, `Get-Clipboard -Raw > error.txt` writes UTF-16; + the same command reading that file still reports the same causes, and a + paste with a non-ASCII character in it (`é`, `→`, a typographic quote) + reports the same causes as in PowerShell 7. diff --git a/docs/testing.md b/docs/testing.md index baa36d0792..83a2b45561 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -4364,6 +4364,65 @@ Windows: cargo xtask e2e -- -n '(diagnose-48)' ``` +## Symptom From A File Or Standard Input + +`rocm diagnose --symptom-file ` reads the symptom from a file, or from +standard input when PATH is `-`, so a pasted error never passes through a +shell's argument parser. How the bytes become the `--symptom` string (one +trailing line break removed, a UTF-8 byte-order mark dropped, UTF-16 with a +byte-order mark decoded, anything else UTF-8, and more than 16 MiB a usage +error) is in [symptom_input.rs](../apps/rocm/src/symptom_input.rs), and its +unit tests there pin each rule, including that a paste full of quotes, +`$(...)`, a backtick and a leading `-` comes back byte for byte. They are the +only tests that would fail if the trailing line break were kept: no scenario +below depends on it, since a line break changes no cause. The clap rules (the +two flags exclude each other, `-` is accepted as a path, a leading `-` is +refused as `--symptom`'s value) are pinned by +`diagnose_takes_the_symptom_from_a_file_or_stdin_but_not_with_symptom` in +[cli.rs](../apps/rocm/src/cli.rs). + +```bash +cargo nextest run -p rocm -E 'test(symptom)' +``` + +Three scenarios in +[diagnose.feature](../tests/e2e-cucumber/features/diagnose.feature), with their +steps in +[symptom_file_steps.rs](../tests/e2e-cucumber/tests/e2e/symptom_file_steps.rs), +hold the behaviour end to end, GPU or not: + +- `diagnose-59` pipes a hostile paste through the platform's own shells (bash + on Linux and WSL; cmd.exe and Windows PowerShell on Windows) and requires + each diagnosis to equal the one for the same text passed as a single + argument with no shell in between: every cause, score and piece of + evidence, and every run exiting 0. The paste carries quotes, `$(...)` and a + leading `-`, but no shell parses it (each reads it from a file into the + pipe), so nothing in it can run by construction; the scenario asserts the + diagnosis, not the absence of something no shell could do. The paste is + ASCII: Windows PowerShell 5.1 pipes text as ASCII, which is why the docs + send PowerShell users through a file instead. +- `diagnose-60` (Linux and WSL lanes only, like every pseudo-terminal + scenario here; the Windows key is checked by hand in + [manual-testing.md](manual-testing.md) section 13) runs + `rocm diagnose --symptom-file -` on a pseudo-terminal tall enough to keep + the whole exchange on screen (it has no scrollback), requires the hint + telling the user how to end the paste, then types the paste and Ctrl-D, the + Linux end-of-input key the hint names, and requires the screen, which also + holds the hint and the echoed paste, to contain the whole report the + argument form prints. It first requires that report to differ from the one + with no symptom, so a paste that was read and then dropped fails rather than + passing on a host where the host's own causes fill the report. +- `diagnose-61` points the flag at a missing file and at one that is not + UTF-8, and requires a usage error (exit code 2) that names the file and the + reason, with nothing on stdout. + +None of them asserts which catalog entry matched, for the reason given at the +top of that feature file: they compare two routes on the same host. + +```bash +cargo xtask e2e -- -n 'diagnose-(59|60|61) ' +``` + ## Model Fit Preflight `rocm diagnose --model ` answers whether a model will run on this host diff --git a/docs/wsl.md b/docs/wsl.md index a0a8aa6029..666f5e9e25 100644 --- a/docs/wsl.md +++ b/docs/wsl.md @@ -189,7 +189,7 @@ Eight entries that are not WSL-specific also run on WSL: `fix-1-arch`, `fix-2-unset-override`, `fix-6-path`, `fix-8-wheel-rocm`, `fix-16-vllm-oom`, `fix-17-torch-dlpack`, `fix-18-comgr-conflict`, and `fix-19-shm-too-small`. `fix-16-vllm-oom` and `fix-17-torch-dlpack` are driven by the error text you -pass with `--symptom` and read nothing from the environment or the ROCm +pass with `--symptom` (or `--symptom-file`) and read nothing from the environment or the ROCm install. `fix-18-comgr-conflict` and `fix-19-shm-too-small` apply when you run `rocm diagnose` inside the distro. A `--distro` run skips both (see diff --git a/tests/e2e-cucumber/features/diagnose.feature b/tests/e2e-cucumber/features/diagnose.feature index 0fff0679ef..a94f59e824 100644 --- a/tests/e2e-cucumber/features/diagnose.feature +++ b/tests/e2e-cucumber/features/diagnose.feature @@ -867,3 +867,50 @@ Feature: Diagnosing failures and listing fixes Given a simulated Linux machine whose only GPU is a released one When the user asks the CLI what that machine's report would carry in machine-readable form Then the report names the CLI version that `rocm version` leads with + + # A pasted error is hostile to every shell's argument parser: bash and + # PowerShell run a `$(...)` even inside double quotes, a stray quote ends the + # argument early, cmd.exe has no single quotes at all, and an error that + # starts with `-` is read as a flag. `--symptom-file -` takes the paste on + # standard input instead, so the shell only ever parses the fixed command. + # Each platform's own shells do the piping -- bash on Linux and WSL, cmd.exe + # and Windows PowerShell on Windows -- and each result is compared with the + # same text handed over as one argument with no shell involved. The paste + # matches a catalog entry that scores on every platform, so the comparison is + # between two real diagnoses rather than two empty ones; which entry it is, + # is not asserted (see the note at the top of this file). Nothing in the + # paste can run or be read as a flag: each shell only reads it from a file + # (cat, type, Get-Content) into the pipe and never parses it. That holds by + # how the paste is handed over, so it is stated here rather than asserted. + @id:diagnose-a-piped-paste-is-diagnosed-as-pasted + Scenario: diagnose-59 - A pasted error piped to the diagnosis is diagnosed the same as if it had been passed safely + Given a pasted error containing quotes, a command substitution and a leading minus sign + When the user pipes it to the diagnosis instead of passing it as an argument + Then the diagnosis matches the same failure modes as the same text passed safely as an argument + + # Typing `rocm diagnose --symptom-file -` with nothing piped in leaves the CLI + # waiting on the terminal. It says so, and how to end the paste; the user + # pastes, ends it the way they were told, and the terminal then contains the + # whole report the same text passed as an argument gets, below the hint and + # the echoed paste. The step first requires that report to differ from the + # one without any symptom, so a paste that was read and then dropped cannot + # pass. + # @requires-os:linux like every other pseudo-terminal scenario in this suite: + # on Windows the step hangs under the harness's pseudo-console before the + # paste is diagnosed (not investigated further; the console is started with + # cursor inheritance, which waits on a reply the screen emulator does not + # send). That leaves the Windows half of the hint (Ctrl-Z then Enter) without + # an e2e check; docs/manual-testing.md section 13 covers it by hand. + @id:diagnose-a-paste-at-the-terminal-is-explained-and-diagnosed @requires-os:linux + Scenario: diagnose-60 - Pasting the error at the terminal is explained, and the paste is diagnosed when the user ends it + Given a pasted error containing quotes, a command substitution and a leading minus sign + When the user asks to paste the error at the terminal, pastes it and ends it as told + Then the CLI told the user how to end the paste + And the terminal shows the whole report the same text passed safely as an argument gets + + @id:diagnose-an-unreadable-error-file-is-a-usage-error + Scenario: diagnose-61 - An error file that cannot be read, or is not text, is refused as a usage error + Given an error file that does not exist and one that is not text + When the user asks the CLI to diagnose the error in each file + Then each is refused as a usage error that names the file and says why + And nothing is diagnosed diff --git a/tests/e2e-cucumber/tests/e2e.rs b/tests/e2e-cucumber/tests/e2e.rs index 0bd56572ce..296bb51ef5 100644 --- a/tests/e2e-cucumber/tests/e2e.rs +++ b/tests/e2e-cucumber/tests/e2e.rs @@ -46,6 +46,7 @@ mod e2e { pub mod serving_steps; pub mod skill_steps; pub mod storage_steps; + pub mod symptom_file_steps; pub mod therock_steps; pub mod tui_driver; pub mod uninstall_steps; @@ -201,6 +202,14 @@ pub struct E2eWorld { /// field rather than borrowing `model_name`, which means a served model and /// has nothing to do with a user's error report. pub skill_symptom: Option, + /// The pasted error a diagnose-59 or diagnose-60 scenario hands to + /// `rocm diagnose --symptom-file`. Its own field for the reason + /// `skill_symptom` is. + pub symptom_paste: Option, + /// The `rocm diagnose --symptom-file` runs a diagnose-59 to diagnose-61 + /// scenario made: one per shell that piped a paste, or one per file the + /// CLI was pointed at. + pub symptom_file_runs: Vec, /// The background helper (`rocm daemon`) a scenario saw running, captured /// while it was known live, so `Drop` can stop it by a verified identity if /// an earlier step failed before the scenario disabled the watcher. @@ -391,6 +400,8 @@ impl Default for E2eWorld { lifecycle: None, skill_reference: None, skill_symptom: None, + symptom_paste: None, + symptom_file_runs: Vec::new(), helper_identity: None, recorded_process: None, recorded_descendant: None, diff --git a/tests/e2e-cucumber/tests/e2e/symptom_file_steps.rs b/tests/e2e-cucumber/tests/e2e/symptom_file_steps.rs new file mode 100644 index 0000000000..10d3fd7e48 --- /dev/null +++ b/tests/e2e-cucumber/tests/e2e/symptom_file_steps.rs @@ -0,0 +1,405 @@ +// Copyright © Advanced Micro Devices, Inc., or its affiliates. +// +// SPDX-License-Identifier: MIT + +//! Steps for `rocm diagnose --symptom-file` (diagnose-59 to diagnose-61): a +//! pasted error handed over on standard input or in a file instead of as a +//! shell argument. + +use std::path::{Path, PathBuf}; +use std::process::Command; + +use cucumber::{given, then, when}; + +use crate::E2eWorld; +use crate::e2e::tui_driver::{TuiSession, default_timeout}; + +/// A pasted error that no shell passes through intact as an argument: it +/// starts with `-`, carries double and single quotes, a `$(...)` that bash and +/// PowerShell would run, and a cmd.exe `&` chain. Those commands are there to +/// make the text the kind `--symptom-file` exists for; nothing looks for what +/// they would write, because handed over as data the paste is never parsed by +/// a shell. What the scenarios check is that the text, read from a file and +/// piped by each shell, is diagnosed with the same causes, scores and evidence +/// as the same text passed as one argument, and that typed at a terminal it +/// leaves a screen containing that argument form's whole report. The keyword +/// it carries scores a catalog entry on every platform (see +/// `KNOWN_SYMPTOM` in `diagnose_steps.rs`), so the diagnosis it gets is a real +/// one. ASCII only, because Windows PowerShell 5.1's pipe to a native command +/// encodes text as ASCII and would turn any other character into `?`. +const HOSTILE_PASTE: &str = "-v \"HSA_STATUS_ERROR_INVALID_ISA\" isn't it? \ + $(echo ran > shell-ran-the-paste) & echo ran > shell-ran-the-paste"; + +/// The args every piped run hands `rocm`, for the coverage report. +const PIPED_ARGS: [&str; 4] = ["diagnose", "--symptom-file", "-", "--json"]; + +/// The terminal scenario's command, with the default `--top`, so the cause the +/// paste scores is listed even where causes found on the host outrank it. +const TERMINAL_ARGS: [&str; 3] = ["diagnose", "--symptom-file", "-"]; + +/// Rows of the terminal the paste is typed into: enough for the hint, the +/// echoed paste and a whole report at the default `--top`, because the +/// emulated screen keeps no scrollback and a scrolled-off row reads as absent. +const TERMINAL_ROWS: u16 = 400; + +/// One `rocm diagnose --symptom-file` run: which shell piped it (or which file +/// it was pointed at), and what came back. +#[derive(Debug)] +pub struct SymptomFileRun { + pub label: String, + pub path: Option, + pub rc: i32, + pub stdout: String, + pub stderr: String, +} + +/// The scenario's own directory for the paste and anything a shell writes. +fn paste_dir(world: &E2eWorld) -> PathBuf { + let dir = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .join("paste"); + std::fs::create_dir_all(&dir).expect("failed to create the paste directory"); + dir +} + +/// Run one shell pipeline in the paste directory, with the scenario's +/// isolated environment, and record it as the `rocm` invocation it wraps. +fn run_piped(world: &E2eWorld, label: &str, mut cmd: Command) -> SymptomFileRun { + cmd.current_dir(paste_dir(world)); + world.isolate_cmd(&mut cmd); + let output = cmd + .output() + .unwrap_or_else(|e| panic!("failed to start {label}: {e}")); + let rc = output.status.code().unwrap_or(-1); + let stdout = String::from_utf8_lossy(&output.stdout).into_owned(); + crate::record_command(world.current_scenario.as_deref(), &PIPED_ARGS, rc, &stdout); + SymptomFileRun { + label: label.to_owned(), + path: None, + rc, + stdout, + stderr: String::from_utf8_lossy(&output.stderr).into_owned(), + } +} + +/// The pipelines a user on this platform would type: the paste comes from a +/// file through the shell's own pipe, so the shell parses only the command. +#[cfg(not(windows))] +fn platform_pipelines(rocm: &str, paste: &Path) -> Vec<(&'static str, Command)> { + let mut bash = Command::new("bash"); + bash.arg("-c") + .arg(r#"cat -- "$1" | "$0" diagnose --symptom-file - --json"#) + .arg(rocm) + .arg(paste); + vec![("bash", bash)] +} + +#[cfg(windows)] +fn platform_pipelines(rocm: &str, paste: &Path) -> Vec<(&'static str, Command)> { + use std::os::windows::process::CommandExt as _; + + let paste = paste.display().to_string(); + // `/s` strips exactly the outer pair of quotes, leaving each path quoted. + let mut cmd = Command::new("cmd.exe"); + cmd.raw_arg(format!( + r#"/d /s /c "type "{paste}" | "{rocm}" diagnose --symptom-file - --json""# + )); + // PowerShell's pipe to a native command appends a line break, which + // `--symptom-file` removes. The comparison here would not notice if it + // did not (a trailing line break changes no cause), so that rule is held + // by the unit tests in `symptom_input.rs`. `exit $LASTEXITCODE` hands back + // rocm's own exit code rather than PowerShell's success flag. + let single = |text: &str| text.replace('\'', "''"); + let mut powershell = Command::new("powershell.exe"); + powershell.args([ + "-NoProfile", + "-NonInteractive", + "-Command", + &format!( + "Get-Content -Raw -LiteralPath '{}' | & '{}' diagnose --symptom-file - --json; \ + exit $LASTEXITCODE", + single(&paste), + single(rocm) + ), + ]); + vec![("cmd.exe", cmd), ("Windows PowerShell", powershell)] +} + +/// The diagnosis of `paste` handed over as one argument with no shell in +/// between: the reference every other route must agree with. +fn diagnose_as_argument(world: &E2eWorld, paste: &str) -> serde_json::Value { + let flag = format!("--symptom={paste}"); + let stdout = crate::run_rocm_ok(world, &["diagnose", &flag, "--json"]); + let report: serde_json::Value = serde_json::from_str(&stdout) + .unwrap_or_else(|e| panic!("diagnose --json did not emit JSON ({e}):\n{stdout}")); + assert_eq!( + report.get("has_match").and_then(serde_json::Value::as_bool), + Some(true), + "the paste must be recognised when passed as an argument, or the comparison \ + would be between two empty diagnoses:\n{stdout}" + ); + report +} + +/// What two diagnoses must agree on: every cause, its score and its evidence. +fn causes(report: &serde_json::Value) -> Vec<(String, i64, serde_json::Value)> { + report + .get("matched") + .and_then(serde_json::Value::as_array) + .expect("the report carries a matched list") + .iter() + .map(|cause| { + ( + cause["id"].as_str().unwrap_or_default().to_owned(), + cause["score"].as_i64().unwrap_or_default(), + cause["evidence"].clone(), + ) + }) + .collect() +} + +/// `text` with all whitespace removed, so a line the terminal wrapped +/// compares equal to the same line unwrapped. +fn squeeze(text: &str) -> String { + text.split_whitespace().collect() +} + +// ── Given ────────────────────────────────────────────────────────── + +#[given("a pasted error containing quotes, a command substitution and a leading minus sign")] +async fn a_hostile_paste(world: &mut E2eWorld) { + // Saved without a trailing line break, as a clipboard holds it. + std::fs::write(paste_dir(world).join("paste.txt"), HOSTILE_PASTE) + .expect("failed to save the paste"); + world.symptom_paste = Some(HOSTILE_PASTE.to_owned()); +} + +#[given("an error file that does not exist and one that is not text")] +async fn unusable_error_files(world: &mut E2eWorld) { + let dir = paste_dir(world); + // Starts with a letter, so it is not mistaken for a UTF-16 byte-order mark. + std::fs::write(dir.join("capture.bin"), [b'H', 0xFF, 0xFE, 0x00, 0x81]) + .expect("failed to write the binary file"); + world.symptom_file_runs = vec![ + SymptomFileRun { + label: "missing".into(), + path: Some(dir.join("no-such-error.txt")), + rc: -1, + stdout: String::new(), + stderr: String::new(), + }, + SymptomFileRun { + label: "not text".into(), + path: Some(dir.join("capture.bin")), + rc: -1, + stdout: String::new(), + stderr: String::new(), + }, + ]; +} + +// ── When ─────────────────────────────────────────────────────────── + +#[when("the user pipes it to the diagnosis instead of passing it as an argument")] +async fn pipe_the_paste(world: &mut E2eWorld) { + let paste = paste_dir(world).join("paste.txt"); + let rocm = crate::rocm_binary(); + let runs: Vec = platform_pipelines(&rocm, &paste) + .into_iter() + .map(|(label, cmd)| run_piped(world, label, cmd)) + .collect(); + world.symptom_file_runs = runs; +} + +#[when("the user asks to paste the error at the terminal, pastes it and ends it as told")] +async fn paste_at_the_terminal(world: &mut E2eWorld) { + let paste = world.symptom_paste.clone().expect("no paste set"); + let mut session = TuiSession::spawn(world, &TERMINAL_ARGS) + .unwrap_or_else(|e| panic!("failed to start the diagnosis: {e}")); + session + .grow_rows(TERMINAL_ROWS) + .unwrap_or_else(|e| panic!("failed to grow the terminal: {e}")); + // Waits for the hint's last words too: it is wider than the terminal, so + // its first row can be on screen before the rest has been drawn. + session + .wait_for_screen_where( + "the CLI asked for the paste", + |screen| screen.contains("Paste the error text") && screen.contains("Windows)."), + default_timeout(), + ) + .await + .unwrap_or_else(|e| panic!("the CLI never asked for the paste: {e}")); + // What the hint tells the user to press: Ctrl-D at the start of a line, + // or on Windows Ctrl-Z then Enter. + let end = if cfg!(windows) { "\u{1a}\r" } else { "\u{4}" }; + session + .send(&format!("{paste}\r{end}")) + .unwrap_or_else(|e| panic!("failed to type the paste: {e}")); + let rc = session + .wait_for_exit_code(default_timeout()) + .await + .unwrap_or_else(|e| panic!("the CLI did not finish after the paste was ended: {e}")); + world.cli_output = Some(session.screen_text()); + world.cli_rc = Some(rc); + world.tui = Some(session); +} + +#[when("the user asks the CLI to diagnose the error in each file")] +async fn diagnose_each_file(world: &mut E2eWorld) { + let mut runs = std::mem::take(&mut world.symptom_file_runs); + for run in &mut runs { + let path = run + .path + .as_ref() + .expect("no file set") + .display() + .to_string(); + let (stdout, stderr, rc) = + crate::run_rocm(world, &["diagnose", "--symptom-file", &path, "--json"]); + run.rc = rc; + run.stdout = stdout; + run.stderr = stderr; + } + world.symptom_file_runs = runs; +} + +// ── Then ─────────────────────────────────────────────────────────── + +#[then( + "the diagnosis matches the same failure modes as the same text passed safely as an argument" +)] +async fn piped_matches_argument(world: &mut E2eWorld) { + let paste = world.symptom_paste.clone().expect("no paste set"); + let expected = causes(&diagnose_as_argument(world, &paste)); + assert!( + !world.symptom_file_runs.is_empty(), + "no shell piped the paste" + ); + for run in &world.symptom_file_runs { + assert_eq!( + run.rc, 0, + "{} pipe: diagnose should exit 0\nstdout:\n{}\nstderr:\n{}", + run.label, run.stdout, run.stderr + ); + let report: serde_json::Value = serde_json::from_str(&run.stdout).unwrap_or_else(|e| { + panic!( + "{} pipe: diagnose --json did not emit JSON ({e}):\n{}\nstderr:\n{}", + run.label, run.stdout, run.stderr + ) + }); + assert_eq!( + causes(&report), + expected, + "{} pipe: the piped paste was diagnosed differently from the same text \ + passed as an argument", + run.label + ); + } +} + +#[then("the CLI told the user how to end the paste")] +async fn told_how_to_end(world: &mut E2eWorld) { + let screen = world.cli_output.as_deref().expect("no terminal output"); + // The hint's own words. The end-of-input key it names is the one the When + // step pressed, and the CLI finished because of it -- for the Linux key: + // the scenario runs on Linux and WSL only, and the Windows key (Ctrl-Z then + // Enter) is checked by hand in docs/manual-testing.md section 13. The hint + // is wider than the terminal, so where it wraps is ignored. + assert!( + squeeze(screen).contains(&squeeze( + "Paste the error text, then end it with Ctrl-D at the start of a line \ + (Ctrl-Z then Enter on Windows)." + )), + "the terminal never showed how to end the paste:\n{screen}" + ); + assert_eq!( + world.cli_rc, + Some(0), + "the paste ended and diagnose exits 0:\n{screen}" + ); +} + +#[then("the terminal shows the whole report the same text passed safely as an argument gets")] +async fn terminal_paste_matches_argument(world: &mut E2eWorld) { + let paste = world.symptom_paste.clone().expect("no paste set"); + // Establishes that the paste is recognised at all. + diagnose_as_argument(world, &paste); + let flag = format!("--symptom={paste}"); + let reference = crate::run_rocm_ok(world, &["diagnose", &flag]); + // The comparison below shows the paste was used only if the paste changes + // the report. Where causes found on the host alone would print the same + // report, it could not tell a paste that was read from one that was + // dropped, so that is a failure rather than a pass. + let without = crate::run_rocm_ok(world, &["diagnose"]); + assert_ne!( + squeeze(&reference), + squeeze(&without), + "the report is the same with and without the paste on this host, so the terminal \ + run cannot show that the paste was used:\n{reference}" + ); + // The screen also holds the hint and the echoed paste, so it must contain + // the whole report the argument form prints, compared without the + // terminal's line wrapping. + let screen = world.cli_output.as_deref().expect("no terminal output"); + assert!( + squeeze(screen).contains(&squeeze(&reference)), + "the terminal does not contain the report the same text passed as an argument \ + gets.\n--- argument form ---\n{reference}\n--- terminal ---\n{screen}" + ); +} + +#[then("each is refused as a usage error that names the file and says why")] +async fn each_file_refused(world: &mut E2eWorld) { + assert_eq!( + world.symptom_file_runs.len(), + 2, + "both files must have been tried" + ); + for run in &world.symptom_file_runs { + let path = run + .path + .as_ref() + .expect("no file set") + .display() + .to_string(); + let why = if run.label == "missing" { + "could not read the symptom from" + } else { + "is not valid UTF-8" + }; + assert_eq!( + run.rc, 2, + "{} file: a usage error exits 2\nstderr:\n{}", + run.label, run.stderr + ); + for needed in [path.as_str(), why, "Usage: rocm diagnose"] { + assert!( + run.stderr.contains(needed), + "{} file: the refusal must say {needed:?}:\n{}", + run.label, + run.stderr + ); + } + assert!( + !run.stderr.contains("panicked"), + "{} file: refused by a panic:\n{}", + run.label, + run.stderr + ); + } +} + +#[then("nothing is diagnosed")] +async fn nothing_diagnosed(world: &mut E2eWorld) { + for run in &world.symptom_file_runs { + assert!( + run.stdout.trim().is_empty(), + "{} file: a refused file must not produce a diagnosis:\n{}", + run.label, + run.stdout + ); + } +}