ps-qa 0.4.1

//! What a check is, and what its verdict means.
//!
//! # Why this exists
//!
//! A DOM-only test environment answers questions about a tree the user never
//! sees. It has no compositor, no hit-testing and no layout, so it reports a
//! node as fine while the screen shows nothing. A green suite over jsdom says
//! the code is self-consistent, not that the interface works.
//!
//! Two failure classes make the point, and both have shipped past a green unit
//! suite in a real application:
//!
//! - **Artwork that lays out and does not draw.** The semantic tree reports a
//!   node whether or not a pixel was painted, and a node can have a correct box
//!   and a correct stroke colour while drawing nothing at all. A renderer that
//!   parses each inline `<svg>` from that element's markup alone will resolve a
//!   reference into a shared sprite to nothing. jsdom cannot see this: its
//!   `<svg>` is a well-behaved object that never goes near a rasteriser.
//! - **Controls that only exist while hovered.** A test that never moves a
//!   pointer cannot see them at all.
//!
//! # What a check is
//!
//! A [`Check`] is a precondition, an action, and an assertion about the state
//! after it, all expressed against the running application. Every part is
//! observed rather than assumed, and [`Paints`](Expect::Paints) fails if the
//! element is in the tree with no box - which is the thing the semantic tree
//! alone will not tell you.
//!
//! Checks are data, and they belong to the application under test rather than
//! to this crate. See [`checks`] for where they are read from.
//!
//! ```sh
//! ps-qa qa           # every check
//! ps-qa qa icons     # one group
//! ```

use blitz_control_protocol::SemanticNode;
use std::collections::HashMap;

/// What a single check asserts once its action has run.
///
/// The full vocabulary is kept whether or not a check currently uses every
/// variant. These are the choices available when writing one, documented with
/// the failure each is right for, and a variant deleted for being momentarily
/// unused is a distinction the next person has to rediscover. `Grows` went
/// unconstructed the moment one check was strengthened to `PaintsMore`; it is
/// still the correct assertion for anything that mounts without painting.
#[allow(dead_code)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum Expect {
    /// The named node exists, is visible, and has a non-zero box.
    ///
    /// Non-zero is the part that matters. A node with a box of `0x0` is in the
    /// tree and on no screen, which is how a broken control passes a test that
    /// only asked whether it existed.
    Paints,
    /// A painted named node is enabled after the action.
    ///
    /// Use this for validation flows where entering a valid value unlocks a
    /// Save or Send control without changing its geometry.
    Enabled,
    /// A painted named node refuses input after the action.
    ///
    /// This is the observable completion state for actions such as clearing a
    /// saved value: the control remains visible, but cannot be invoked again
    /// until there is something new to act on.
    Disabled,
    /// No node matching the name exists.
    ///
    /// The assertion for a control that must *not* be reachable, and for
    /// checking that a destructive action did not fire.
    Absent,
    /// The node may remain in the tree, but nothing matching it is on screen.
    ///
    /// The inverse of [`Paints`](Expect::Paints), and the right question for
    /// anything that closes. A dismissed dialog is not removed: measured after
    /// a dialog's Cancel, the dialog's own content is still in the tree at
    /// `0x0 HIDDEN`. Asking for absence there reports a working control as
    /// broken, while asking for a box distinguishes dismissed from trapped -
    /// full size while open, nothing once closed.
    Vanishes,
    /// The count of matching nodes changed in the given direction.
    Grows,
    /// More matching nodes are *on screen* than before.
    ///
    /// [`Grows`](Expect::Grows) counts tree membership, which is the wrong
    /// question for a control that reveals something already mounted. The
    /// rename editor is built for the life of its component and merely hidden,
    /// so the node count does not move when it opens - only its box does.
    ///
    /// Counting painted nodes is also what makes the check falsifiable. A
    /// `Paints` assertion on `textbox` stays green while the pencil is dead,
    /// because the composer and the search field are textboxes that always
    /// paint; verified by reintroducing the bug and watching it pass.
    PaintsMore,
    /// The count of matching nodes did not change.
    Holds,
    /// A node matching *both* a name and a role paints.
    ///
    /// The precise form of [`Paints`](Expect::Paints), for the common case
    /// where a control and the thing it opens share an accessible name.
    /// An in-place rename control does exactly that: `Rename <subject>`
    /// resolves to a button that always paints *and* a textbox that paints only
    /// while editing, so a name-only `Paints` is satisfied by the pencil
    /// whether or not the editor ever opens.
    ///
    /// A count-based assertion is not the answer either. `PaintsMore` over
    /// every `textbox` in the tree is fragile to whatever else happens to be
    /// on screen - a composer, a search field, an editor left open by an
    /// earlier check - and reported `2 -> 2` on a run where the editor
    /// demonstrably opened. Asking about one node by name and role is the
    /// question the check actually means.
    ///
    /// Written as `role:name`, e.g. `textbox:Rename thing`.
    ///
    /// Judged on geometry, not on the tree's `visible` flag, because the two
    /// disagree. Measured on one node at one instant: `paint` reported the
    /// rename editor `300.0x21.1 at 87,236 fg=#b0b5b9ff opacity=1.00 Visible`
    /// while `dom` reported the same id `HIDDEN`. `paint` reads what the
    /// render pass resolved; `visible` walks ancestors looking for
    /// `display:none` and `aria-hidden`, and a wrapper whose class no longer
    /// says `hidden` was still carrying it in the style tree while its subtree
    /// laid out and drew.
    ///
    /// So a check that trusts `visible` calls a control a person can see and
    /// type into dead. Geometry plus a position is the honest question here.
    PaintsNamed,
    /// Every painted node in the matching family occupies its own position.
    ///
    /// A repeated family can expose correct state and non-zero boxes while
    /// every member is stacked on the same coordinates. This is the rendered
    /// contract for layouts such as a colour flower.
    DistinctPositions,
    /// The exact accessible name selected for this check's click still paints.
    ///
    /// Use this for a row action whose label includes the row identity. It
    /// proves that exact row survived without comparing a broad family count
    /// that hover-revealed neighbours can legitimately change.
    TargetPaints,
    /// The named subject paints above the named comparison control.
    ///
    /// This is a rendered-order assertion, not DOM order. It verifies list
    /// placement using the boxes a person actually sees.
    Above,
    /// The exact semantic node's exposed value changed after the action.
    ///
    /// This is the outcome for sliders, switches, and other value-bearing
    /// controls whose geometry does not change when they work. The node id is
    /// carried from the before snapshot so a repeated accessible name cannot
    /// satisfy the assertion with a neighbouring row.
    ValueChanges,
    /// The exact semantic node's selected/pressed state changed.
    ///
    /// Radios and `aria-pressed` buttons expose selection as a boolean rather
    /// than inventing a string value. This follows the activated node id, so a
    /// neighbouring swatch cannot satisfy the verdict.
    SelectionChanges,
    /// The exact subject node's accessible name changed after the action.
    ///
    /// Use this for status text that reports a completed refresh or re-check.
    /// Following the node id prevents an unrelated new status row from
    /// satisfying the outcome.
    NameChanges,
}

/// One thing that must be true of the running panel.
#[derive(Clone, Debug, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Check {
    /// Stable name for this one check, so a failure can be re-run alone.
    ///
    /// The group is too coarse for that: chasing one fix meant re-running its
    /// neighbours every time, and each run drives the real app. `what` is prose
    /// and changes when the wording improves, so it cannot be the handle.
    /// This is the handle - `ps-qa qa rename-opens-editor`.
    pub id: String,
    /// Group, so a failing area can be re-run alone.
    pub group: String,
    /// What this proves, in the words you would use to report it.
    pub what: String,
    /// Press this first, to reach the surface the check is about.
    ///
    /// Checks run in sequence against one instance and start wherever the app
    /// opens, so anything not on that first surface is unreachable without a
    /// navigation step. A control that lives on only one surface fails with
    /// "no visible, enabled, sized button" when the check never got there,
    /// which reads as a missing control rather than a missing navigation.
    pub open: Option<String>,
    /// Activate this semantic control after navigation and before measuring
    /// the action baseline.
    ///
    /// This gives a check an explicit state precondition without making it
    /// depend on a preceding check. For example, select one tab here, then
    /// activate another and require its selected state to change.
    #[serde(default)]
    pub prepare: Option<String>,
    /// Use a real pointer press for [`prepare`](Self::prepare).
    ///
    /// Focus-sensitive popovers can legitimately distinguish a human press
    /// from a bare semantic activation. Keep this separate from `press`, since
    /// the prepared trigger and measured action may have different roles.
    #[serde(default)]
    pub prepare_press: bool,
    /// Send this key to [`prepare`](Self::prepare) instead of activating it.
    ///
    /// This keeps focus-sensitive controls self-contained: a select check can
    /// open its listbox with the component's authored keyboard contract, then
    /// measure an option selection without depending on an earlier check.
    #[serde(default)]
    pub prepare_key: Option<String>,
    /// Hover this node first, if the control is revealed on hover.
    pub hover: Option<String>,
    /// Click this node, if the check is about an action.
    pub click: Option<String>,
    /// Focus this named text field and enter [`text`](Self::text).
    pub type_into: Option<String>,
    /// Literal text to enter after the click step.
    pub text: Option<String>,
    /// A final named key such as Enter or Escape, sent to `type_into`.
    pub key: Option<String>,
    /// Focus this named semantic control before sending `key`.
    ///
    /// Unlike `type_into`, this accepts any value-bearing role, including a
    /// slider. Name resolution produces a node id before the action is sent.
    pub key_on: Option<String>,
    /// The second named node for a relative-position expectation.
    pub compare: Option<String>,
    /// Additional controls covered by this same rendered contract.
    ///
    /// Use this only for a repeated family produced from one component and
    /// one data array, such as every `Offer {model}` checkbox. The action and
    /// verdict still address one exact semantic node; these selectors let the
    /// inventory credit its identical siblings without pretending a substring
    /// chosen for activation is itself an outcome.
    #[serde(default)]
    pub covers: Vec<String>,
    /// Opt into generic coordinate-pointer activation instead of semantic
    /// node activation. Application suites omit this unless they explicitly
    /// intend to test hit-testing.
    #[serde(default)]
    pub press: bool,
    /// Optional unmeasured quiet window after this verdict.
    ///
    /// Use this only when an application paints optimistically and then begins
    /// durable work that temporarily occupies its control transport. The
    /// rendered action still has to pass the one-second budget.
    #[serde(default)]
    pub settle_after_ms: u64,
    /// The node the assertion is about.
    pub subject: String,
    pub expect: Expect,
}

/// Every check, in the order they run, read from the application's own files.
///
/// # Why these are not compiled in
///
/// They used to be Rust, in a `tests/ps-qa/` module inside this crate, which was
/// wrong twice over. It put one product's promises - its control names, its
/// section labels, its fixture names - inside a general harness, so pointing
/// this binary at a second application meant editing the harness.
/// And it made changing a selector a recompile: correcting one hardcoded
/// fixture name after a profile rebuild touched 15 references across 6 files
/// and needed a build to try.
///
/// A check is data. It is a precondition, an action and an assertion, with no
/// behaviour of its own, so it belongs in a file the application owns and
/// anybody can edit between runs.
///
/// Read from `<dir>/*.ron`, where `<dir>` is `--checks <path>` or `tests/ps-qa/`
/// under the working directory. Files are read in name order and concatenated,
/// so the group order is the filename order.
pub fn checks(dir: Option<&std::path::Path>) -> Result<Vec<Check>, String> {
    let dir = dir
        .map(std::path::Path::to_path_buf)
        .unwrap_or_else(|| std::path::PathBuf::from("tests/ps-qa"));
    if !dir.is_dir() {
        return Err(format!(
            "no checks at {}. Point --checks at the application's check \
             directory.",
            dir.display()
        ));
    }
    let mut files: Vec<std::path::PathBuf> = std::fs::read_dir(&dir)
        .map_err(|error| format!("could not read {}: {error}", dir.display()))?
        .filter_map(Result::ok)
        .map(|entry| entry.path())
        .filter(|path| path.extension().is_some_and(|ext| ext == "ron"))
        .collect();
    // Name order, so a run is reproducible rather than dependent on whatever
    // order the filesystem happens to hand back.
    files.sort();

    let mut all = Vec::new();
    for file in files {
        let text = std::fs::read_to_string(&file)
            .map_err(|error| format!("could not read {}: {error}", file.display()))?;
        let group: Vec<Check> = ron::from_str(&text)
            .map_err(|error| format!("could not parse {}: {error}", file.display()))?;
        all.extend(group);
    }
    Ok(all)
}

fn matching<'a>(nodes: &'a [SemanticNode], want: &str) -> Vec<&'a SemanticNode> {
    nodes
        .iter()
        .filter(|node| {
            /*
             * `@slot` addresses the part a component library named, rather than
             * the text the part happens to carry. A trigger and the thing it
             * opens routinely share an accessible name - an in-place editor
             * labels both `Rename <subject>` - so a check written against the
             * name is satisfied by whichever of them paints, which is the
             * trigger, whether or not activating it did anything.
             */
            if let Some(slot) = want.strip_prefix('@') {
                return node.slot.as_deref().is_some_and(|have| have == slot);
            }
            if let Some((role, name)) = want.split_once(':') {
                return node.role.eq_ignore_ascii_case(role)
                    && node.name.to_lowercase().contains(&name.to_lowercase());
            }
            node.name.to_lowercase().contains(&want.to_lowercase())
                || node.role.to_lowercase().contains(&want.to_lowercase())
        })
        .collect()
}

/// Whether a node is on screen with a box worth painting.
///
/// A zero-area box is the failure this exists to catch: present in the tree,
/// absent from the window.
fn paints(node: &SemanticNode) -> bool {
    /*
     * Geometry alone, because `visible` and the renderer disagree.
     *
     * Measured on one node at one instant: `paint` reported the rename editor
     * `300.0x21.1 at 87,236 opacity=1.00 Visible` while the semantic tree
     * reported that same id `HIDDEN`. `visible` walks ancestors for
     * `display:none` and `aria-hidden`, and a wrapper whose class no longer
     * says `hidden` was still carrying it in the style tree while its subtree
     * laid out and drew.
     *
     * Trusting the flag called controls dead that a person can see and use -
     * the icons group reported "246 exist, none paints" for an app visibly
     * full of icons. A non-zero box at a real position is what can be checked
     * honestly from here; `ps-qa paint` is the tool for the pixels themselves.
     */
    node.bounds.is_some_and(|b| b[2] > 0.0 && b[3] > 0.0)
}

/// The verdict for one check, given the tree before and after its action.
pub fn verdict(
    check: &Check,
    before: &[SemanticNode],
    after: &[SemanticNode],
) -> Result<(), String> {
    let found = matching(after, &check.subject);
    match check.expect {
        Expect::Vanishes => {
            let on_screen: Vec<&SemanticNode> =
                found.iter().copied().filter(|node| paints(node)).collect();
            if let Some(node) = on_screen.first() {
                let b = node.bounds.unwrap_or([0.0; 4]);
                return Err(format!(
                    "{:?} is still on screen at {:.0}x{:.0}; it did not close",
                    check.subject, b[2], b[3]
                ));
            }
        }
        Expect::Paints => {
            if found.is_empty() {
                return Err(format!("no node matching {:?} exists", check.subject));
            }
            if !found.iter().any(|node| paints(node)) {
                /*
                 * Say which half of "paints" failed.
                 *
                 * Hidden-but-sized and visible-but-zero-area are different
                 * bugs: the first is a node the panel deliberately keeps
                 * offscreen, the second is a control the user is meant to see
                 * and cannot. Reporting them as one message sent me looking at
                 * the wrong one.
                 */
                let hidden = found.iter().filter(|node| !node.visible).count();
                let zero = found
                    .iter()
                    .filter(|node| {
                        node.visible && !node.bounds.is_some_and(|b| b[2] > 0.0 && b[3] > 0.0)
                    })
                    .count();
                let boxes: Vec<String> = found
                    .iter()
                    .take(3)
                    .map(|node| {
                        let size = node
                            .bounds
                            .map(|b| format!("{:.0}x{:.0}", b[2], b[3]))
                            .unwrap_or_else(|| "no box".into());
                        format!("{size}{}", if node.visible { "" } else { " hidden" })
                    })
                    .collect();
                return Err(format!(
                    "{} node(s) matching {:?} exist but none paints: \
                     {hidden} hidden, {zero} visible with no area ({})",
                    found.len(),
                    check.subject,
                    boxes.join(", ")
                ));
            }
        }
        Expect::Enabled => {
            if found.iter().any(|node| paints(node) && node.enabled) {
                return Ok(());
            }
            let states = found
                .iter()
                .take(3)
                .map(|node| {
                    format!(
                        "id={} role={:?} name={:?} enabled={} bounds={:?}",
                        node.id, node.role, node.name, node.enabled, node.bounds
                    )
                })
                .collect::<Vec<_>>();
            return Err(format!(
                "no painted, enabled node matching {:?} ({})",
                check.subject,
                states.join(", ")
            ));
        }
        Expect::Disabled => {
            if found.iter().any(|node| paints(node) && !node.enabled) {
                return Ok(());
            }
            let states = found
                .iter()
                .take(3)
                .map(|node| {
                    format!(
                        "id={} role={:?} name={:?} enabled={} bounds={:?}",
                        node.id, node.role, node.name, node.enabled, node.bounds
                    )
                })
                .collect::<Vec<_>>();
            return Err(format!(
                "no painted, disabled node matching {:?} ({})",
                check.subject,
                states.join(", ")
            ));
        }
        Expect::Absent => {
            if !found.is_empty() {
                return Err(format!(
                    "{} node(s) matching {:?} should not exist",
                    found.len(),
                    check.subject
                ));
            }
        }
        Expect::PaintsNamed => {
            let (role, name) = check
                .subject
                .split_once(':')
                .unwrap_or(("", &check.subject));
            let hit = after
                .iter()
                .filter(|node| node.role == role && node.name.contains(name))
                .find(|node| node.bounds.is_some_and(|b| b[2] > 0.0 && b[3] > 0.0));
            if hit.is_none() {
                let matches: Vec<_> = after
                    .iter()
                    .filter(|node| node.role == role && node.name.contains(name))
                    .collect();
                let state = matches
                    .iter()
                    .map(|node| {
                        format!(
                            "id={} parent={:?} visible={} bounds={:?}",
                            node.id, node.parent, node.visible, node.bounds
                        )
                    })
                    .collect::<Vec<_>>()
                    .join("; ");
                let other_painted = after
                    .iter()
                    .filter(|node| {
                        node.role != role
                            && node.name.contains(name)
                            && node.bounds.is_some_and(|b| b[2] > 0.0 && b[3] > 0.0)
                    })
                    .take(3)
                    .map(|node| format!("{} id={}", node.role, node.id))
                    .collect::<Vec<_>>()
                    .join(", ");
                let other_painted = if other_painted.is_empty() {
                    "none".to_owned()
                } else {
                    other_painted
                };
                return Err(format!(
                    "no {role} named {name:?} has a box ({} in the tree: {state}); \
                     other painted matches: {other_painted}",
                    matches.len(),
                ));
            }
        }
        Expect::DistinctPositions => {
            let painted: Vec<_> = found.iter().copied().filter(|node| paints(node)).collect();
            if painted.len() < 2 {
                return Err(format!(
                    "{:?} has {} painted match(es); expected a positioned family",
                    check.subject,
                    painted.len()
                ));
            }
            let positions: std::collections::HashSet<(i64, i64)> = painted
                .iter()
                .map(|node| {
                    let bounds = node.bounds.expect("painted nodes have bounds");
                    (
                        ((bounds[0] + bounds[2] / 2.0) * 10.0).round() as i64,
                        ((bounds[1] + bounds[3] / 2.0) * 10.0).round() as i64,
                    )
                })
                .collect();
            if positions.len() != painted.len() {
                return Err(format!(
                    "{} painted node(s) matching {:?} occupy only {} distinct position(s)",
                    painted.len(),
                    check.subject,
                    positions.len()
                ));
            }
        }
        Expect::TargetPaints => {
            return Err("TargetPaints must be resolved by the live QA runner".to_owned());
        }
        Expect::Above => {
            let compare = check
                .compare
                .as_deref()
                .ok_or_else(|| "Above requires compare".to_owned())?;
            let subject_node = found
                .iter()
                .find(|node| paints(node))
                .ok_or_else(|| format!("no painted node matching {:?}", check.subject))?;
            let subject = subject_node.bounds.expect("painted nodes have bounds");
            let other = matching(after, compare)
                .into_iter()
                .filter(|node| node.id != subject_node.id)
                .find_map(|node| paints(node).then_some(node.bounds).flatten())
                .ok_or_else(|| format!("no painted comparison node matching {compare:?}"))?;
            if subject[1] >= other[1] {
                return Err(format!(
                    "{:?} is at y={:.0}, not above {compare:?} at y={:.0}",
                    check.subject, subject[1], other[1]
                ));
            }
        }
        Expect::PaintsMore => {
            let was = matching(before, &check.subject)
                .into_iter()
                .filter(|node| paints(node))
                .count();
            let now = found.iter().filter(|node| paints(node)).count();
            if now <= was {
                return Err(format!(
                    "{:?} on screen went {was} -> {now}, expected one more",
                    check.subject
                ));
            }
        }
        Expect::Grows => {
            let was = matching(before, &check.subject).len();
            let now = found.len();
            if now <= was {
                return Err(format!(
                    "{:?} went {was} -> {now}, expected more",
                    check.subject
                ));
            }
        }
        Expect::Holds => {
            let was = matching(before, &check.subject).len();
            let now = found.len();
            if now != was {
                return Err(format!(
                    "{:?} went {was} -> {now}, expected no change",
                    check.subject
                ));
            }
        }
        Expect::ValueChanges => {
            let before_node = matching(before, &check.subject)
                .into_iter()
                .find(|node| paints(node))
                .ok_or_else(|| {
                    format!("no painted node matching {:?} before action", check.subject)
                })?;
            value_changed(before_node.id, before, after)?;
        }
        Expect::SelectionChanges => {
            let before_node = matching(before, &check.subject)
                .into_iter()
                .find(|node| paints(node))
                .ok_or_else(|| {
                    format!("no painted node matching {:?} before action", check.subject)
                })?;
            selection_changed(before_node.id, before, after)?;
        }
        Expect::NameChanges => {
            let before_node = matching(before, &check.subject)
                .into_iter()
                .find(|node| paints(node))
                .ok_or_else(|| {
                    format!("no painted node matching {:?} before action", check.subject)
                })?;
            name_changed(before_node.id, before, after)?;
        }
    }
    Ok(())
}

/// Assert that one exact semantic node changed its exposed value.
///
/// The live runner uses this after a named action has already resolved to an
/// id. Re-resolving by name here would let a neighbouring same-name row decide
/// the verdict instead of the control that was actually activated.
pub fn value_changed(
    node_id: u64,
    before: &[SemanticNode],
    after: &[SemanticNode],
) -> Result<(), String> {
    let before_node = before
        .iter()
        .find(|node| node.id == node_id)
        .ok_or_else(|| format!("node {node_id} was absent before action"))?;
    let after_node = after
        .iter()
        .find(|node| node.id == node_id)
        .ok_or_else(|| format!("node {node_id} disappeared after action"))?;
    let old = before_node
        .value
        .as_deref()
        .ok_or_else(|| format!("node {node_id} has no semantic value before action"))?;
    let new = after_node
        .value
        .as_deref()
        .ok_or_else(|| format!("node {node_id} has no semantic value after action"))?;
    if old == new {
        return Err(format!("semantic value for node {node_id} stayed {old:?}"));
    }
    Ok(())
}

/// Assert that one exact semantic node changed selected/pressed state.
pub fn selection_changed(
    node_id: u64,
    before: &[SemanticNode],
    after: &[SemanticNode],
) -> Result<(), String> {
    let before_node = before
        .iter()
        .find(|node| node.id == node_id)
        .ok_or_else(|| format!("node {node_id} was absent before action"))?;
    let after_node = after
        .iter()
        .find(|node| node.id == node_id)
        .ok_or_else(|| format!("node {node_id} disappeared after action"))?;
    if before_node.selected == after_node.selected {
        return Err(format!(
            "selected state for node {node_id} stayed {}",
            before_node.selected
        ));
    }
    Ok(())
}

/// Assert that one exact semantic node changed its accessible name.
pub fn name_changed(
    node_id: u64,
    before: &[SemanticNode],
    after: &[SemanticNode],
) -> Result<(), String> {
    let before_node = before
        .iter()
        .find(|node| node.id == node_id)
        .ok_or_else(|| format!("node {node_id} was absent before action"))?;
    let after_node = after
        .iter()
        .find(|node| node.id == node_id)
        .ok_or_else(|| format!("node {node_id} disappeared after action"))?;
    if before_node.name == after_node.name {
        return Err(format!(
            "accessible name for node {node_id} stayed {:?}",
            before_node.name
        ));
    }
    Ok(())
}

/// Every check, grouped, with what it drives and what it asserts.
///
/// Printed by `ps-qa list`, and generated from [`checks`] rather than written
/// down, so it cannot drift from what actually runs. This is the inventory: it
/// answers "what is covered" without launching the app, which is the question
/// that had no answer while the audit was a list of button names in a handover.
pub fn manifest(dir: Option<&std::path::Path>) -> Result<String, String> {
    let all = checks(dir)?;
    let mut out = String::new();
    let mut current = String::new();
    for check in &all {
        if check.group != current {
            current = check.group.clone();
            out.push_str(&format!("\n{current}\n"));
        }
        let action = action_description(check);
        out.push_str(&format!(
            "  {:<26} {}\n{:<29}{} -> {:?} {:?}\n",
            check.id, check.what, "", action, check.expect, check.subject
        ));
        if !check.covers.is_empty() {
            out.push_str(&format!("{:<29}covers {:?}\n", "", check.covers));
        }
    }
    out.push_str(&format!("\n{} checks in {} groups\n", all.len(), {
        all.iter()
            .map(|check| check.group.as_str())
            .collect::<std::collections::HashSet<_>>()
            .len()
    }));
    Ok(out)
}

fn action_description(check: &Check) -> String {
    let mut action = match (&check.hover, &check.click, check.press) {
        (Some(h), Some(c), true) => format!("hover {h:?}, press {c:?}"),
        (Some(h), Some(c), false) => format!("hover {h:?}, activate {c:?}"),
        (Some(h), None, _) => format!("hover {h:?}"),
        (None, Some(c), true) => format!("press {c:?}"),
        (None, Some(c), false) => format!("activate {c:?}"),
        (None, None, _) => "observe only".to_owned(),
    };
    if let Some(prepare) = check.prepare.as_deref() {
        let preparation = if let Some(key) = check.prepare_key.as_deref() {
            format!("prepare-key {key:?} on {prepare:?}")
        } else if check.prepare_press {
            format!("prepare-press {prepare:?}")
        } else {
            format!("prepare {prepare:?}")
        };
        action = format!("{preparation}, {action}");
    }
    if let Some(field) = check.type_into.as_deref() {
        let typed = check.text.as_deref().map_or_else(
            || format!("focus {field:?}"),
            |value| format!("type {value:?} into {field:?}"),
        );
        if action == "observe only" {
            action = typed;
        } else {
            action.push_str(&format!(", {typed}"));
        }
    }
    if let (Some(key), Some(target)) = (
        &check.key,
        check.key_on.as_ref().or(check.type_into.as_ref()),
    ) {
        action.push_str(&format!(", key {key:?} on {target:?}"));
    }
    action
}

/// Count matching nodes per group, for the summary line.
pub fn tally<'a>(results: &[(&'a Check, Result<(), String>)]) -> HashMap<&'a str, (usize, usize)> {
    let mut by_group: HashMap<&str, (usize, usize)> = HashMap::new();
    for (check, outcome) in results {
        let entry = by_group.entry(check.group.as_str()).or_insert((0, 0));
        entry.1 += 1;
        if outcome.is_ok() {
            entry.0 += 1;
        }
    }
    by_group
}

#[cfg(test)]
mod tests {
    use super::{
        Check, Expect, action_description, name_changed, selection_changed, value_changed, verdict,
    };
    use blitz_control_protocol::SemanticNode;

    fn parse(extra: &str) -> Check {
        let ron = format!(
            "(id:\"action\",group:\"group\",what:\"outcome\",open:None,hover:None,\
             click:Some(\"Save\"),{extra}subject:\"Saved\",expect:Paints)"
        );
        ron::from_str(&ron).expect("check parses")
    }

    #[test]
    fn checks_default_to_semantic_actions_and_can_opt_into_pointer_press() {
        assert!(!parse("").press);
        assert!(parse("press:true,").press);
    }

    #[test]
    fn checks_can_prepare_a_semantic_state_before_the_measured_action() {
        let check = parse("prepare:Some(\"Draft\"),");
        assert_eq!(check.prepare.as_deref(), Some("Draft"));
        assert_eq!(
            action_description(&check),
            "prepare \"Draft\", activate \"Save\""
        );
    }

    #[test]
    fn checks_can_prepare_with_a_real_pointer_without_changing_the_action_mode() {
        let check = parse("prepare:Some(\"Draft\"),prepare_press:true,");
        assert!(check.prepare_press);
        assert!(!check.press);
        assert_eq!(
            action_description(&check),
            "prepare-press \"Draft\", activate \"Save\""
        );
    }

    #[test]
    fn checks_can_prepare_with_a_key_without_changing_the_measured_action() {
        let check = parse("prepare:Some(\"Menu\"),prepare_key:Some(\"ArrowDown\"),");
        assert_eq!(check.prepare_key.as_deref(), Some("ArrowDown"));
        assert!(!check.press);
        assert_eq!(
            action_description(&check),
            "prepare-key \"ArrowDown\" on \"Menu\", activate \"Save\""
        );
    }

    #[test]
    fn checks_can_describe_literal_semantic_input() {
        let check = parse(
            "type_into:Some(\"New record\"),text:Some(\"latest fixture\"),\
             key:Some(\"Enter\"),compare:Some(\"older\"),\
             covers:[\"button:Save row \"],settle_after_ms:1200,",
        );
        assert_eq!(check.type_into.as_deref(), Some("New record"));
        assert_eq!(check.text.as_deref(), Some("latest fixture"));
        assert_eq!(check.key.as_deref(), Some("Enter"));
        assert_eq!(check.compare.as_deref(), Some("older"));
        assert_eq!(check.covers, ["button:Save row "]);
        assert_eq!(check.settle_after_ms, 1200);
        assert_eq!(
            action_description(&check),
            "activate \"Save\", type \"latest fixture\" into \"New record\", key \"Enter\" on \"New record\""
        );
    }

    #[test]
    fn a_value_check_follows_the_same_node_id() {
        let check = Check {
            id: "slider".into(),
            group: "settings".into(),
            what: "the slider moves".into(),
            open: None,
            prepare: None,
            prepare_press: false,
            prepare_key: None,
            hover: None,
            click: None,
            type_into: None,
            text: None,
            key: Some("Right".into()),
            key_on: Some("Output level".into()),
            compare: None,
            covers: Vec::new(),
            press: false,
            settle_after_ms: 0,
            subject: "Output level".into(),
            expect: Expect::ValueChanges,
        };
        let node = |id, value: &str| SemanticNode {
            id,
            parent: None,
            role: "slider".into(),
            name: "Output level".into(),
            value: Some(value.into()),
            enabled: true,
            visible: true,
            selected: false,
            bounds: Some([0.0, 0.0, 100.0, 20.0]),
            slot: None,
        };

        assert!(verdict(&check, &[node(7, "0")], &[node(7, "1")]).is_ok());
        assert!(verdict(&check, &[node(7, "0")], &[node(7, "0")]).is_err());
        assert!(
            verdict(&check, &[node(7, "0")], &[node(7, "0"), node(8, "1")],).is_err(),
            "a neighbouring repeated control cannot satisfy the check"
        );
        assert!(
            value_changed(
                8,
                &[node(7, "0"), node(8, "0")],
                &[node(7, "1"), node(8, "0")],
            )
            .is_err(),
            "the exact activated id cannot be replaced by a same-name neighbour"
        );
    }

    #[test]
    fn a_selection_check_follows_the_same_node_id() {
        let before = SemanticNode {
            id: 7,
            parent: None,
            role: "radio".into(),
            name: "Theme colour".into(),
            value: None,
            enabled: true,
            visible: true,
            selected: false,
            bounds: Some([0.0, 0.0, 20.0, 20.0]),
            slot: None,
        };
        let mut after = before.clone();
        after.selected = true;
        assert!(
            selection_changed(
                7,
                std::slice::from_ref(&before),
                std::slice::from_ref(&after),
            )
            .is_ok()
        );
        assert!(
            selection_changed(
                7,
                std::slice::from_ref(&before),
                std::slice::from_ref(&before),
            )
            .is_err()
        );
    }

    #[test]
    fn a_name_check_follows_the_same_node_id() {
        let node = |id, name: &str| SemanticNode {
            id,
            parent: None,
            role: "status".into(),
            name: name.into(),
            value: None,
            enabled: true,
            visible: true,
            selected: false,
            bounds: Some([0.0, 0.0, 100.0, 20.0]),
            slot: None,
        };

        assert!(name_changed(7, &[node(7, "Refreshed 1")], &[node(7, "Refreshed 2")]).is_ok());
        assert!(name_changed(7, &[node(7, "Refreshed 1")], &[node(7, "Refreshed 1")]).is_err());
        assert!(
            name_changed(
                7,
                &[node(7, "Refreshed 1")],
                &[node(7, "Refreshed 1"), node(8, "Refreshed 2")],
            )
            .is_err(),
            "a neighbouring status node cannot satisfy the check"
        );
    }

    #[test]
    fn a_named_paint_failure_reports_a_still_painted_activator() {
        let mut check = parse("");
        check.subject = "textbox:Rename project".into();
        check.expect = Expect::PaintsNamed;
        let node = |id, role: &str, bounds: Option<[f64; 4]>| SemanticNode {
            id,
            parent: None,
            role: role.into(),
            name: "Rename project".into(),
            value: None,
            enabled: true,
            visible: bounds.is_some(),
            selected: false,
            bounds,
            slot: None,
        };
        let error = verdict(
            &check,
            &[],
            &[
                node(7, "textbox", Some([0.0, 0.0, 0.0, 0.0])),
                node(8, "button", Some([10.0, 10.0, 20.0, 20.0])),
            ],
        )
        .expect_err("the textbox does not paint");
        assert!(error.contains("other painted matches: button id=8"));
    }

    #[test]
    fn a_positioned_family_rejects_stacked_controls() {
        let mut check = parse("");
        check.subject = "radio:Theme color".into();
        check.expect = Expect::DistinctPositions;
        let node = |id, x, y| SemanticNode {
            id,
            parent: None,
            role: "radio".into(),
            name: format!("Theme color {id}"),
            value: None,
            enabled: true,
            visible: true,
            selected: false,
            bounds: Some([x, y, 20.0, 20.0]),
            slot: None,
        };

        assert!(verdict(&check, &[], &[node(1, 10.0, 10.0), node(2, 40.0, 10.0)]).is_ok());
        let error = verdict(&check, &[], &[node(1, 10.0, 10.0), node(2, 10.0, 10.0)])
            .expect_err("stacked controls are not a positioned family");
        assert!(error.contains("only 1 distinct position"));
    }

    #[test]
    fn enabled_requires_the_control_to_paint_and_accept_input() {
        let mut check = parse("");
        check.subject = "Save".into();
        check.expect = Expect::Enabled;
        let node = |enabled, bounds| SemanticNode {
            id: 7,
            parent: None,
            role: "button".into(),
            name: "Save".into(),
            value: None,
            enabled,
            visible: true,
            selected: false,
            bounds,
            slot: None,
        };

        assert!(verdict(&check, &[], &[node(true, Some([0.0, 0.0, 20.0, 20.0]))]).is_ok());
        assert!(verdict(&check, &[], &[node(false, Some([0.0, 0.0, 20.0, 20.0]))]).is_err());
        assert!(verdict(&check, &[], &[node(true, Some([0.0, 0.0, 0.0, 0.0]))]).is_err());

        check.expect = Expect::Disabled;
        assert!(verdict(&check, &[], &[node(false, Some([0.0, 0.0, 20.0, 20.0]))]).is_ok());
        assert!(verdict(&check, &[], &[node(true, Some([0.0, 0.0, 20.0, 20.0]))]).is_err());
        assert!(verdict(&check, &[], &[node(false, Some([0.0, 0.0, 0.0, 0.0]))]).is_err());
    }

    #[test]
    fn verdict_subjects_honor_role_qualified_names() {
        let mut check = parse("");
        check.subject = "button:Send".into();
        check.expect = Expect::Disabled;
        let node = |role: &str| SemanticNode {
            id: 7,
            parent: None,
            role: role.into(),
            name: "Send".into(),
            value: None,
            enabled: false,
            visible: true,
            selected: false,
            bounds: Some([0.0, 0.0, 20.0, 20.0]),
            slot: None,
        };

        assert!(verdict(&check, &[], &[node("button")]).is_ok());
        assert!(verdict(&check, &[], &[node("textbox")]).is_err());
    }
}