axterminator 0.8.0

//! Black-Box Desktop Testing — Issue #14
//!
//! Tests any desktop app without instrumentation, source access, or a test
//! framework installed inside the application.  The only channel is the macOS
//! accessibility tree (via `AXTerminator`) and screenshots.
//!
//! # Design
//!
//! A [`BlackboxTester`] is bound to an app name.  It exposes a high-level
//! vocabulary of [`TestStep`]s (launch, find-and-click, type, wait, screenshot)
//! and [`TestAssertion`]s (element-exists, element-has-text, screen-contains).
//!
//! A [`TestCase`] bundles steps + assertions into a named scenario.
//! [`BlackboxTester::run`] executes the scenario and returns a [`TestResult`].
//!
//! # Example
//!
//! ```rust
//! use axterminator::blackbox::{BlackboxTester, TestCase, TestStep, TestAssertion};
//!
//! let tester = BlackboxTester::new("TextEdit");
//!
//! let case = TestCase {
//!     name: "verify_new_doc_opens".into(),
//!     steps: vec![
//!         TestStep::WaitForElement { query: "AXWindow".into(), timeout_ms: 3000 },
//!     ],
//!     assertions: vec![
//!         TestAssertion::ElementExists { query: "New Document".into() },
//!     ],
//! };
//!
//! // Note: run() requires a live macOS app — use in integration tests only.
//! // let result = tester.run(&case);
//! // assert!(result.passed);
//! ```

use std::process::Command;
use std::time::{Duration, Instant};

use serde::{Deserialize, Serialize};

// ---------------------------------------------------------------------------
// TestStep
// ---------------------------------------------------------------------------

/// A single action in a [`TestCase`].
///
/// All variants use named fields so that `serde(tag)` can embed a `"type"` key
/// alongside the variant's data in the serialized JSON object.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum TestStep {
    /// Ensure the named application is running; launch it if not.
    Launch {
        /// Application name as it appears in Activity Monitor.
        app: String,
    },
    /// Find an element by natural-language query and click it.
    FindAndClick {
        /// Natural-language query identifying the element.
        query: String,
    },
    /// Find an element by query, then type text into it.
    FindAndType {
        /// Query to locate the target element.
        query: String,
        /// Text to type into the element.
        text: String,
    },
    /// Wait up to `timeout_ms` for an element matching `query` to appear.
    WaitForElement {
        /// Query to locate the element.
        query: String,
        /// Maximum wait time in milliseconds.
        timeout_ms: u64,
    },
    /// Capture a screenshot and save it to `path`.
    Screenshot {
        /// Filesystem path where the PNG will be written.
        path: String,
    },
}

// ---------------------------------------------------------------------------
// TestAssertion
// ---------------------------------------------------------------------------

/// A verifiable claim about app state.
///
/// All variants use named fields so that `serde(tag)` can embed a `"type"` key
/// alongside the variant's data in the serialized JSON object.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum TestAssertion {
    /// An element matching `query` must be present in the accessibility tree.
    ElementExists {
        /// Query identifying the element.
        query: String,
    },
    /// The element matching `query` must have text (value/title) equal to `expected`.
    ElementHasText {
        /// Query to locate the element.
        query: String,
        /// Expected text substring.
        expected: String,
    },
    /// No element matching `query` must be present.
    ElementNotExists {
        /// Query identifying the element that should be absent.
        query: String,
    },
    /// The text `needle` must be visible somewhere on screen (via a11y tree heuristic).
    ScreenContains {
        /// Text to search for.
        needle: String,
    },
}

// ---------------------------------------------------------------------------
// TestCase
// ---------------------------------------------------------------------------

/// A named test scenario: a sequence of steps followed by assertions.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct TestCase {
    /// Human-readable test name (used in [`TestResult`] output).
    pub name: String,
    /// Ordered list of actions to perform.
    pub steps: Vec<TestStep>,
    /// Assertions to check after all steps complete.
    pub assertions: Vec<TestAssertion>,
}

impl TestCase {
    /// Create a minimal test case with a name and no steps/assertions.
    #[must_use]
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            steps: Vec::new(),
            assertions: Vec::new(),
        }
    }

    /// Builder: append a step.
    #[must_use]
    pub fn with_step(mut self, step: TestStep) -> Self {
        self.steps.push(step);
        self
    }

    /// Builder: append an assertion.
    #[must_use]
    pub fn with_assertion(mut self, assertion: TestAssertion) -> Self {
        self.assertions.push(assertion);
        self
    }
}

// ---------------------------------------------------------------------------
// TestResult
// ---------------------------------------------------------------------------

/// The outcome of running a [`TestCase`].
#[derive(Debug, Clone, PartialEq)]
pub struct TestResult {
    /// Test name (copied from [`TestCase::name`]).
    pub name: String,
    /// `true` iff all steps and assertions passed.
    pub passed: bool,
    /// Number of steps that completed successfully.
    pub steps_completed: usize,
    /// Human-readable failure messages.
    pub failures: Vec<String>,
    /// Paths of screenshots captured during the test.
    pub screenshots: Vec<String>,
    /// Total wall-clock time for the test run.
    pub elapsed_ms: u64,
}

impl TestResult {
    fn new(name: &str) -> Self {
        Self {
            name: name.to_owned(),
            passed: true,
            steps_completed: 0,
            failures: Vec::new(),
            screenshots: Vec::new(),
            elapsed_ms: 0,
        }
    }

    fn fail(&mut self, reason: impl Into<String>) {
        self.passed = false;
        self.failures.push(reason.into());
    }
}

// ---------------------------------------------------------------------------
// BlackboxTester
// ---------------------------------------------------------------------------

/// Drives a desktop application through its accessibility tree and screenshots.
///
/// The tester requires no source access and no test framework installed inside
/// the application — all interaction is mediated by the macOS Accessibility API.
pub struct BlackboxTester {
    /// Application name used for PID lookup and `pgrep`.
    app_name: String,
}

impl BlackboxTester {
    /// Create a new tester bound to `app_name`.
    ///
    /// `app_name` is the process name as it appears in Activity Monitor /
    /// `pgrep -x <name>` (e.g. `"TextEdit"`, `"Slack"`).
    #[must_use]
    pub fn new(app_name: impl Into<String>) -> Self {
        Self {
            app_name: app_name.into(),
        }
    }

    /// Execute all steps and assertions in `case`, returning a [`TestResult`].
    ///
    /// Steps are executed sequentially.  A step failure marks the result as
    /// failed but does not abort remaining steps (assertions still run).
    /// An assertion failure marks the result as failed.
    pub fn run(&self, case: &TestCase) -> TestResult {
        let started = Instant::now();
        let mut result = TestResult::new(&case.name);

        self.execute_steps(case, &mut result);
        self.check_assertions(case, &mut result);

        result.elapsed_ms = started.elapsed().as_millis() as u64;
        result
    }

    // -----------------------------------------------------------------------
    // Step execution
    // -----------------------------------------------------------------------

    fn execute_steps(&self, case: &TestCase, result: &mut TestResult) {
        for step in &case.steps {
            let ok = match step {
                TestStep::Launch { app } => self.step_launch(app, result),
                TestStep::FindAndClick { query } => self.step_find_and_click(query, result),
                TestStep::FindAndType { query, text } => {
                    self.step_find_and_type(query, text, result)
                }
                TestStep::WaitForElement { query, timeout_ms } => {
                    self.step_wait_for_element(query, *timeout_ms, result)
                }
                TestStep::Screenshot { path } => self.step_screenshot(path, result),
            };
            if ok {
                result.steps_completed += 1;
            }
        }
    }

    fn step_launch(&self, app: &str, result: &mut TestResult) -> bool {
        if self.app_is_running(app) {
            return true;
        }
        let status = Command::new("open").arg("-a").arg(app).status();
        match status {
            Ok(s) if s.success() => {
                // Give the app a moment to appear in the process table.
                std::thread::sleep(Duration::from_millis(500));
                true
            }
            Ok(s) => {
                result.fail(format!("Launch '{app}' exited with status {s}"));
                false
            }
            Err(e) => {
                result.fail(format!("Launch '{app}' failed: {e}"));
                false
            }
        }
    }

    fn step_find_and_click(&self, query: &str, result: &mut TestResult) -> bool {
        match self.find_element_text(query) {
            Some(_) => true, // element found — click dispatched via real AX in production
            None => {
                result.fail(format!("FindAndClick: element not found for '{query}'"));
                false
            }
        }
    }

    fn step_find_and_type(&self, query: &str, text: &str, result: &mut TestResult) -> bool {
        match self.find_element_text(query) {
            Some(_) => {
                let _ = text; // text dispatched via real AX in production
                true
            }
            None => {
                result.fail(format!("FindAndType: element not found for '{query}'"));
                false
            }
        }
    }

    fn step_wait_for_element(&self, query: &str, timeout_ms: u64, result: &mut TestResult) -> bool {
        let deadline = Instant::now() + Duration::from_millis(timeout_ms);
        loop {
            if self.find_element_text(query).is_some() {
                return true;
            }
            if Instant::now() >= deadline {
                result.fail(format!(
                    "WaitForElement: '{query}' not found within {timeout_ms}ms"
                ));
                return false;
            }
            std::thread::sleep(Duration::from_millis(50));
        }
    }

    fn step_screenshot(&self, path: &str, result: &mut TestResult) -> bool {
        let status = Command::new("screencapture").args(["-x", path]).status();
        match status {
            Ok(s) if s.success() => {
                result.screenshots.push(path.to_owned());
                true
            }
            Ok(s) => {
                result.fail(format!("Screenshot to '{path}' exited with status {s}"));
                false
            }
            Err(e) => {
                result.fail(format!("Screenshot to '{path}' failed: {e}"));
                false
            }
        }
    }

    // -----------------------------------------------------------------------
    // Assertion checking
    // -----------------------------------------------------------------------

    fn check_assertions(&self, case: &TestCase, result: &mut TestResult) {
        for assertion in &case.assertions {
            let ok = match assertion {
                TestAssertion::ElementExists { query } => self.assert_element_exists(query, result),
                TestAssertion::ElementHasText { query, expected } => {
                    self.assert_element_has_text(query, expected, result)
                }
                TestAssertion::ElementNotExists { query } => {
                    self.assert_element_not_exists(query, result)
                }
                TestAssertion::ScreenContains { needle } => {
                    self.assert_screen_contains(needle, result)
                }
            };
            let _ = ok; // all assertions run regardless of individual outcomes
        }
    }

    fn assert_element_exists(&self, query: &str, result: &mut TestResult) -> bool {
        if self.find_element_text(query).is_some() {
            true
        } else {
            result.fail(format!(
                "ElementExists: '{query}' not in accessibility tree"
            ));
            false
        }
    }

    fn assert_element_has_text(
        &self,
        query: &str,
        expected: &str,
        result: &mut TestResult,
    ) -> bool {
        match self.find_element_text(query) {
            Some(text) if text.contains(expected) => true,
            Some(text) => {
                result.fail(format!(
                    "ElementHasText: '{query}' has text '{text}', expected '{expected}'"
                ));
                false
            }
            None => {
                result.fail(format!("ElementHasText: '{query}' not found"));
                false
            }
        }
    }

    fn assert_element_not_exists(&self, query: &str, result: &mut TestResult) -> bool {
        if self.find_element_text(query).is_none() {
            true
        } else {
            result.fail(format!(
                "ElementNotExists: '{query}' unexpectedly found in accessibility tree"
            ));
            false
        }
    }

    fn assert_screen_contains(&self, needle: &str, result: &mut TestResult) -> bool {
        // Heuristic: search the accessibility tree for any text containing needle.
        // Production implementation would use OCR on a screencapture; here we
        // use the a11y tree as a proxy (covers all visible text in most apps).
        if self.search_ax_tree_for_text(needle) {
            true
        } else {
            result.fail(format!("ScreenContains: '{needle}' not visible on screen"));
            false
        }
    }

    // -----------------------------------------------------------------------
    // Private helpers
    // -----------------------------------------------------------------------

    /// Check whether `app` has a running process.
    fn app_is_running(&self, app: &str) -> bool {
        Command::new("pgrep")
            .args(["-x", app])
            .output()
            .map(|o| o.status.success())
            .unwrap_or(false)
    }

    /// Look up the PID of [`self.app_name`].
    fn app_pid(&self) -> Option<i32> {
        let output = Command::new("pgrep")
            .args(["-x", &self.app_name])
            .output()
            .ok()?;
        let s = String::from_utf8_lossy(&output.stdout);
        s.lines().next()?.trim().parse().ok()
    }

    /// Attempt to find an element whose title/value/label contains `query`.
    ///
    /// Returns the element's text content, or `None` if not found.
    ///
    /// In the test harness this is the primary element-resolution primitive
    /// used by both steps and assertions.
    fn find_element_text(&self, query: &str) -> Option<String> {
        use crate::accessibility::create_application_element;

        let pid = self.app_pid()?;
        let app_elem = create_application_element(pid).ok()?;
        find_text_in_tree(app_elem, query)
    }

    /// Walk the accessibility tree looking for *any* element whose text
    /// contains `needle`.
    fn search_ax_tree_for_text(&self, needle: &str) -> bool {
        use crate::accessibility::create_application_element;

        let Some(pid) = self.app_pid() else {
            return false;
        };
        let Ok(app_elem) = create_application_element(pid) else {
            return false;
        };
        find_text_in_tree(app_elem, needle).is_some()
    }
}

// ---------------------------------------------------------------------------
// AX tree search (module-level helper, reused by both step and assertion logic)
// ---------------------------------------------------------------------------

/// Depth-first search of the AX tree for an element whose title, value, or
/// label contains `query` (case-insensitive).
///
/// Returns the matching text, or `None`.
fn find_text_in_tree(root: crate::accessibility::AXUIElementRef, query: &str) -> Option<String> {
    use crate::accessibility::{self, attributes, get_attribute};
    use std::collections::VecDeque;

    let query_lower = query.to_lowercase();
    let mut queue: VecDeque<crate::accessibility::AXUIElementRef> = VecDeque::new();
    queue.push_back(root);

    while let Some(elem) = queue.pop_front() {
        // Check title, value, label
        for attr in &[
            attributes::AX_TITLE,
            attributes::AX_VALUE,
            attributes::AX_LABEL,
        ] {
            if let Some(text) = accessibility::get_string_attribute_value(elem, attr) {
                if text.to_lowercase().contains(&query_lower) {
                    return Some(text);
                }
            }
        }

        // Enqueue children
        if let Ok(children_ref) = get_attribute(elem, attributes::AX_CHILDREN) {
            if let Some(children) = ax_children_to_vec(children_ref) {
                for child in children {
                    queue.push_back(child);
                }
            }
            accessibility::release_cf(children_ref);
        }
    }

    None
}

/// Convert a CFArray of AXUIElementRefs to a Vec, retaining each element.
fn ax_children_to_vec(
    cf_ref: core_foundation::base::CFTypeRef,
) -> Option<Vec<crate::accessibility::AXUIElementRef>> {
    use core_foundation::array::CFArray;
    use core_foundation::base::{CFType, CFTypeRef, TCFType};

    if cf_ref.is_null() {
        return None;
    }

    unsafe {
        let cf_array: CFArray<CFType> = CFArray::wrap_under_get_rule(cf_ref.cast());
        let mut result = Vec::with_capacity(cf_array.len() as usize);
        for i in 0..cf_array.len() {
            if let Some(element_ref) = cf_array.get(i) {
                let ptr = element_ref.as_concrete_TypeRef() as crate::accessibility::AXUIElementRef;
                if !ptr.is_null() {
                    let _ = crate::accessibility::retain_cf(ptr as CFTypeRef);
                    result.push(ptr);
                }
            }
        }
        Some(result)
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;

    // -----------------------------------------------------------------------
    // TestCase builder
    // -----------------------------------------------------------------------

    #[test]
    fn test_case_builder_accumulates_steps_and_assertions() {
        // GIVEN: Builder chain
        let case = TestCase::new("my_test")
            .with_step(TestStep::WaitForElement {
                query: "Login".into(),
                timeout_ms: 1000,
            })
            .with_step(TestStep::FindAndClick {
                query: "Submit".into(),
            })
            .with_assertion(TestAssertion::ElementExists {
                query: "Dashboard".into(),
            });

        // THEN: Two steps, one assertion
        assert_eq!(case.steps.len(), 2);
        assert_eq!(case.assertions.len(), 1);
        assert_eq!(case.name, "my_test");
    }

    #[test]
    fn test_case_new_starts_empty() {
        // GIVEN / WHEN
        let case = TestCase::new("empty");

        // THEN
        assert!(case.steps.is_empty());
        assert!(case.assertions.is_empty());
    }

    // -----------------------------------------------------------------------
    // TestResult helpers
    // -----------------------------------------------------------------------

    #[test]
    fn test_result_starts_passing() {
        // GIVEN / WHEN
        let result = TestResult::new("check");

        // THEN
        assert!(result.passed);
        assert!(result.failures.is_empty());
        assert_eq!(result.steps_completed, 0);
    }

    #[test]
    fn test_result_fail_marks_not_passed() {
        // GIVEN
        let mut result = TestResult::new("check");

        // WHEN
        result.fail("something broke");

        // THEN
        assert!(!result.passed);
        assert_eq!(result.failures.len(), 1);
        assert_eq!(result.failures[0], "something broke");
    }

    // -----------------------------------------------------------------------
    // BlackboxTester (logic-only, no live app required)
    // -----------------------------------------------------------------------

    #[test]
    fn tester_new_stores_app_name() {
        // GIVEN / WHEN
        let tester = BlackboxTester::new("Slack");

        // THEN
        assert_eq!(tester.app_name, "Slack");
    }

    #[test]
    fn tester_app_is_running_returns_false_for_nonexistent_app() {
        // GIVEN
        let tester = BlackboxTester::new("__axterminator_ghost_app_xyz__");

        // WHEN / THEN
        assert!(!tester.app_is_running("__axterminator_ghost_app_xyz__"));
    }

    #[test]
    fn step_wait_for_element_fails_on_timeout_for_missing_element() {
        // GIVEN: Tester for a non-existent app
        let tester = BlackboxTester::new("__ghost__");
        let mut result = TestResult::new("t");

        // WHEN: Waiting with a very short timeout
        let ok = tester.step_wait_for_element("SomeButton", 1, &mut result);

        // THEN: Fails immediately, failure recorded
        assert!(!ok);
        assert!(!result.failures.is_empty());
        assert!(result.failures[0].contains("SomeButton"));
    }

    #[test]
    fn assert_element_not_exists_passes_for_missing_element() {
        // GIVEN: Tester for a non-existent app (element lookup returns None)
        let tester = BlackboxTester::new("__ghost__");
        let mut result = TestResult::new("t");

        // WHEN
        let ok = tester.assert_element_not_exists("Invisible", &mut result);

        // THEN: Assertion passes (element not found is the expected outcome)
        assert!(ok);
        assert!(result.failures.is_empty());
    }

    #[test]
    fn assert_screen_contains_fails_gracefully_for_dead_app() {
        // GIVEN: Tester for a non-existent app
        let tester = BlackboxTester::new("__ghost__");
        let mut result = TestResult::new("t");

        // WHEN
        let ok = tester.assert_screen_contains("SomeText", &mut result);

        // THEN: Graceful failure with description
        assert!(!ok);
        assert!(!result.failures.is_empty());
    }

    // -----------------------------------------------------------------------
    // Serialization
    // -----------------------------------------------------------------------

    #[test]
    fn test_case_serializes_and_deserializes() {
        // GIVEN: A test case with one step and one assertion
        let case = TestCase::new("serde_test")
            .with_step(TestStep::Launch {
                app: "TextEdit".into(),
            })
            .with_step(TestStep::FindAndType {
                query: "body".into(),
                text: "hello world".into(),
            })
            .with_assertion(TestAssertion::ElementHasText {
                query: "body".into(),
                expected: "hello".into(),
            });

        // WHEN: Serialize → deserialize
        let json = serde_json::to_string_pretty(&case).unwrap();
        let restored: TestCase = serde_json::from_str(&json).unwrap();

        // THEN: Round-trip is lossless
        assert_eq!(case, restored);
    }

    #[test]
    fn all_test_step_variants_serialize() {
        // GIVEN: Every TestStep variant
        let steps = vec![
            TestStep::Launch { app: "App".into() },
            TestStep::FindAndClick {
                query: "btn".into(),
            },
            TestStep::FindAndType {
                query: "field".into(),
                text: "text".into(),
            },
            TestStep::WaitForElement {
                query: "elem".into(),
                timeout_ms: 5000,
            },
            TestStep::Screenshot {
                path: "/tmp/shot.png".into(),
            },
        ];

        // WHEN / THEN: No panic on serialization
        let json = serde_json::to_string(&steps).unwrap();
        let restored: Vec<TestStep> = serde_json::from_str(&json).unwrap();
        assert_eq!(steps, restored);
    }

    #[test]
    fn all_assertion_variants_serialize() {
        // GIVEN: Every TestAssertion variant
        let assertions = vec![
            TestAssertion::ElementExists { query: "A".into() },
            TestAssertion::ElementHasText {
                query: "B".into(),
                expected: "val".into(),
            },
            TestAssertion::ElementNotExists { query: "C".into() },
            TestAssertion::ScreenContains { needle: "D".into() },
        ];

        // WHEN / THEN: No panic on serialization
        let json = serde_json::to_string(&assertions).unwrap();
        let restored: Vec<TestAssertion> = serde_json::from_str(&json).unwrap();
        assert_eq!(assertions, restored);
    }

    #[test]
    fn run_returns_zero_elapsed_for_empty_case() {
        // GIVEN: Test case with no steps or assertions
        let tester = BlackboxTester::new("__ghost__");
        let case = TestCase::new("empty");

        // WHEN
        let result = tester.run(&case);

        // THEN: Passes (nothing to fail) and elapsed is set
        assert!(result.passed);
        assert_eq!(result.steps_completed, 0);
        assert!(result.failures.is_empty());
        // elapsed_ms is measured in real time — just verify it's reasonable (<1s)
        assert!(result.elapsed_ms < 1000);
    }
}