xacli_testing/spec/

xacli.rs

//! XaCLI test file parser and runner
//!
//! Parses `.xacli` HCL test files and executes tests with declarative assertions.
//!
//! # File Format
//!
//! ```hcl
//! suite "suite_name" {
//!     features = {
//!         skip = false
//!         only = false
//!         parallel = true
//!     }
//!
//!     test "test_name" {
//!         commands = ["get", "user"]
//!         args = ["--verbose", "--output=json"]
//!
//!     input_events = [
//!         { text = "hello" },
//!         { key = "Enter" },
//!         { key = "Backspace", repeat = 3 }
//!     ]
//!
//!     assertions = [
//!         { type = "success" },
//!         { type = "exit_code", value = 0 },
//!         { type = "contains", stream = "stdout", value = "expected text" },
//!         { type = "empty", stream = "stderr" },
//!         { type = "snapshot", snapshot = "snapshots/test.snap" },
//!         {
//!             type = "and",
//!             conditions = [
//!                 { type = "success" },
//!                 { type = "contains", stream = "stdout", value = "done" }
//!             ]
//!         },
//!         {
//!             type = "or",
//!             conditions = [
//!                 { type = "exit_code", value = 0 },
//!                 { type = "exit_code", value = 1 }
//!             ]
//!         }
//!     ]
//! }
//! ```

use std::{collections::HashMap, path::Path};

use crossterm::event::{Event, KeyCode, KeyEvent, KeyModifiers};
use serde::Deserialize;

use crate::{assert, Asserter, Result};

/// A parsed .xacli test file
#[derive(Debug, Clone, Deserialize)]
pub struct SpecFile {
    /// Global CLI configuration
    #[serde(default)]
    pub cli: Option<CliConfig>,

    /// Documentation examples, keyed by example name
    #[serde(default)]
    pub example: HashMap<String, ExampleBlock>,

    /// Test suites, keyed by suite name (from block label)
    #[serde(default)]
    pub suite: HashMap<String, Suite>,
}

/// Global CLI configuration
#[derive(Debug, Clone, Deserialize)]
pub struct CliConfig {
    /// CLI application name
    pub name: String,

    /// Path to the CLI executable
    pub path: String,

    /// Optional short alias for display in tape files
    #[serde(default)]
    pub alias: Option<String>,
}

/// Documentation example block
#[derive(Debug, Clone, Deserialize)]
pub struct ExampleBlock {
    /// Example title
    pub title: String,

    /// Optional description (can be multi-line Markdown)
    #[serde(default)]
    pub description: Option<String>,

    /// Multiple command steps to execute
    #[serde(default)]
    pub steps: Vec<CommandStep>,
}

/// A single command step in an example
#[derive(Debug, Clone, Deserialize)]
pub struct CommandStep {
    /// Commands/subcommands (e.g., ["doc", "build"])
    #[serde(default)]
    pub commands: Vec<String>,

    /// Command line arguments
    #[serde(default)]
    pub args: Vec<String>,

    /// Interactive input events (keyboard events)
    #[serde(default)]
    pub input_events: Vec<InputEvent>,

    /// Optional step description
    #[serde(default)]
    pub description: Option<String>,
}

/// A test suite containing multiple test cases
#[derive(Debug, Clone, Deserialize)]
pub struct Suite {
    /// Suite-level features (skip, only, parallel)
    #[serde(default)]
    pub features: TestFeatures,

    /// Test cases within this suite, keyed by test name
    #[serde(default)]
    pub test: HashMap<String, TestCase>,
}

/// A single test case
#[derive(Debug, Clone, Deserialize)]
pub struct TestCase {
    /// Commands/subcommands (e.g., ["get", "user"])
    #[serde(default)]
    pub commands: Vec<String>,

    /// Command line arguments
    #[serde(default)]
    pub args: Vec<String>,

    /// Test features (skip, only, parallel)
    #[serde(default)]
    pub features: TestFeatures,

    /// Interactive input events (keyboard events)
    #[serde(default)]
    pub input_events: Vec<InputEvent>,

    /// Assertions to perform after execution
    #[serde(default)]
    pub assertions: Vec<AssertionConfig>,
}

/// Test features controlling execution
#[derive(Debug, Clone, Default, Deserialize)]
pub struct TestFeatures {
    /// Skip this test
    #[serde(default)]
    pub skip: bool,

    /// Only run this test (and other "only" tests)
    #[serde(default)]
    pub only: bool,

    /// Run in parallel with other tests (default: true)
    #[serde(default = "default_true")]
    pub parallel: bool,
}

fn default_true() -> bool {
    true
}

/// Output stream selector
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum Stream {
    /// Standard output
    Stdout,
    /// Standard error
    Stderr,
}

/// Assertion configuration for declarative tests
#[derive(Debug, Clone, Deserialize)]
#[serde(tag = "type", rename_all = "snake_case")]
pub enum AssertionConfig {
    /// Assert command executed successfully (exit code 0)
    Success,

    /// Assert command failed (exit code non-zero)
    Failure,

    /// Assert exit code equals expected value
    ExitCode { value: i32 },

    /// Assert output stream contains text
    Contains { stream: Stream, value: String },

    /// Assert output stream is empty
    Empty { stream: Stream },

    /// Snapshot assertion (snapshot file contains code and stream info)
    Snapshot {
        /// Snapshot file path (relative to .xacli file)
        snapshot: String,
    },

    /// Logical AND - all conditions must pass
    And { conditions: Vec<AssertionConfig> },

    /// Logical OR - at least one condition must pass
    Or { conditions: Vec<AssertionConfig> },
}

impl AssertionConfig {
    /// Convert assertion config to an Asserter implementation
    pub fn to_asserter(&self) -> Result<Box<dyn Asserter>> {
        match self {
            AssertionConfig::Success => Ok(assert::success()),
            AssertionConfig::Failure => Ok(assert::failure()),
            AssertionConfig::ExitCode { value } => Ok(assert::code(*value as i64)),
            AssertionConfig::Contains { stream, value } => Ok(match stream {
                Stream::Stdout => assert::stdout().contains(value),
                Stream::Stderr => assert::stderr().contains(value),
            }),
            AssertionConfig::Empty { stream } => Ok(match stream {
                Stream::Stdout => assert::stdout().empty(),
                Stream::Stderr => assert::stderr().empty(),
            }),
            AssertionConfig::Snapshot { .. } => {
                // TODO: Implement snapshot assertion support
                Err(crate::TestingError::Custom(
                    "Snapshot assertions are not yet supported".to_string(),
                ))
            }
            AssertionConfig::And { conditions } => {
                let asserters: Result<Vec<_>> =
                    conditions.iter().map(|c| c.to_asserter()).collect();
                Ok(assert::and(asserters?))
            }
            AssertionConfig::Or { conditions } => {
                let asserters: Result<Vec<_>> =
                    conditions.iter().map(|c| c.to_asserter()).collect();
                Ok(assert::or(asserters?))
            }
        }
    }
}

/// An input event (keyboard input)
#[derive(Debug, Clone, Deserialize)]
#[serde(untagged)]
pub enum InputEvent {
    /// Key press: { key = "Enter" } or { key = "Backspace", repeat = 5 }
    Key {
        key: String,
        #[serde(default = "default_one")]
        repeat: usize,
    },
    /// Text input: { text = "hello" }
    Text { text: String },
}

fn default_one() -> usize {
    1
}

impl InputEvent {
    /// Convert spec InputEvent to xacli_core InputEvents
    /// Returns a Vec because repeat generates multiple events
    pub fn to_core_events(&self) -> Result<Vec<xacli_core::InputEvent>> {
        match self {
            InputEvent::Key { key, repeat } => {
                let key_code = match key.as_str() {
                    "Enter" => KeyCode::Enter,
                    "Backspace" => KeyCode::Backspace,
                    "Delete" => KeyCode::Delete,
                    "Left" => KeyCode::Left,
                    "Right" => KeyCode::Right,
                    "Up" => KeyCode::Up,
                    "Down" => KeyCode::Down,
                    "Home" => KeyCode::Home,
                    "End" => KeyCode::End,
                    "PageUp" => KeyCode::PageUp,
                    "PageDown" => KeyCode::PageDown,
                    "Tab" => KeyCode::Tab,
                    "Esc" => KeyCode::Esc,
                    "Space" => KeyCode::Char(' '),
                    s if s.len() == 1 => KeyCode::Char(s.chars().next().unwrap()),
                    // TODO: Support function keys (F1-F12), modifiers, etc.
                    _ => {
                        return Err(crate::TestingError::Custom(format!(
                            "Unsupported key: {}",
                            key
                        )))
                    }
                };
                Ok(vec![
                    Event::Key(KeyEvent::new(
                        key_code,
                        KeyModifiers::empty()
                    ));
                    *repeat
                ])
            }
            InputEvent::Text { text } => {
                // TODO: Text input events are not directly supported in crossterm
                // For now, we convert each character to a KeyCode::Char event
                Ok(text
                    .chars()
                    .map(|c| Event::Key(KeyEvent::new(KeyCode::Char(c), KeyModifiers::empty())))
                    .collect())
            }
        }
    }
}

impl SpecFile {
    /// Parse a .xacli test file
    pub fn parse_file(path: impl AsRef<Path>) -> Result<Self> {
        let content = std::fs::read_to_string(path)?;
        Self::parse_str(&content)
    }

    /// Parse from string content
    pub fn parse_str(content: &str) -> Result<Self> {
        hcl::from_str(content)
            .map_err(|e| crate::TestingError::TapeParse(format!("HCL parse error: {}", e)))
    }

    /// Get all suite names
    pub fn suite_names(&self) -> Vec<&str> {
        self.suite.keys().map(|s| s.as_str()).collect()
    }

    /// Scan a directory recursively for .xacli.hcl spec files and merge into one SpecFile
    ///
    /// All suites and examples from multiple files are merged into a single SpecFile.
    /// The cli config is taken from the first file that has one.
    /// Files that fail to parse are skipped with a warning printed to stderr.
    pub fn scan_dir(dir: impl AsRef<Path>) -> Result<Self> {
        let dir = dir.as_ref();
        if !dir.exists() {
            return Err(crate::TestingError::Custom(format!(
                "Directory does not exist: {}",
                dir.display()
            )));
        }

        let mut merged = Self {
            cli: None,
            example: HashMap::new(),
            suite: HashMap::new(),
        };
        Self::scan_dir_recursive(dir, &mut merged)?;
        Ok(merged)
    }

    fn scan_dir_recursive(dir: &Path, merged: &mut Self) -> Result<()> {
        let entries = std::fs::read_dir(dir)?;

        for entry in entries.flatten() {
            let path = entry.path();
            if path.is_dir() {
                Self::scan_dir_recursive(&path, merged)?;
            } else if path.extension().is_some_and(|ext| ext == "hcl") {
                // Check if it's a .xacli.hcl file
                if let Some(stem) = path.file_stem() {
                    let stem_str = stem.to_string_lossy();
                    if stem_str.ends_with(".xacli") {
                        match Self::parse_file(&path) {
                            Ok(spec) => {
                                if merged.cli.is_none() {
                                    merged.cli = spec.cli;
                                }
                                merged.example.extend(spec.example);
                                merged.suite.extend(spec.suite);
                            }
                            Err(e) => {
                                eprintln!("Warning: Failed to parse {}: {}", path.display(), e);
                            }
                        }
                    }
                }
            }
        }

        Ok(())
    }
}