llm-browser-testkit 0.16.0

//! Scenario types for human-readable browser test case definitions.
//!
//! Scenarios are written in [TOML](https://toml.io) and describe groups of
//! browser interaction tests with reusable assertion definitions and
//! configurable test-level overrides.
//!
//! # Structure
//!
//! ```toml
//! [config]                         # Global defaults
//! start_url = "/dashboard"
//!
//! [[definitions]]                  # Reusable assertion definitions
//! name = "no_errors"
//! preset = "no_error_on_page"
//!
//! [[test]]                         # Test group
//! name = "Dashboard Smoke"
//! start_url = "/dashboard"         # Override global start_url (optional)
//!
//! [[test.steps]]                   # Ordered steps — the `kind` field
//! kind = "navigate"                # determines which other fields apply
//! url = "/dashboard"
//!
//! [[test.steps]]
//! kind = "click"
//! target = "the Login button"      # Natural language — LLM resolves to selector
//!
//! [[test.steps]]
//! kind = "assert"
//! definition = "no_errors"
//! ```
//!
//! ## Step Kinds
//!
//! | `kind`        | Required fields  | Optional fields                          |
//! |---------------|-----------------|------------------------------------------|
//! | `navigate`    | `url`           | `wait_after_ms`                          |
//! | `click`       | `target`        | `selector`, `wait_after_ms`              |
//! | `type`        | `target`, `text`| `selector`, `wait_after_ms`              |
//! | `wait`        | `target`        | `selector`, `timeout_ms`                 |
//! | `assert`      | *one of below*  | —                                        |
//! | `screenshot`  | —               | `path`                                   |
//! | `agent`       | `agent`, `task` | —                                        |
//! | `mcp`         | `server`, `tool`| `args`                                   |
//!
//! Assert steps require one of: `definition` (references a named
//! `[[definitions]]` entry), `preset` (built-in preset name), or `prompt`
//! (custom LLM evaluation prompt).

use std::collections::HashMap;

use serde::Deserialize;
use serde_json::Value;

/// Top-level scenario file, deserialized from TOML.
#[derive(Debug, Deserialize)]
pub struct Scenario {
    /// Global configuration (overridable per test).
    #[serde(default)]
    pub config: ScenarioConfig,

    /// Reusable assertion definitions referenced by name in `assert` steps.
    #[serde(default)]
    pub definitions: Vec<AssertDefinition>,

    /// Ordered test groups to execute.
    #[serde(default)]
    pub test: Vec<TestGroup>,
}

/// Global scenario configuration with per-test overridable fields.
#[derive(Debug, Deserialize, Default, Clone)]
pub struct ScenarioConfig {
    /// Base URL for relative navigation.
    #[serde(default)]
    pub base_url: Option<String>,
    /// LLM server base URL (deprecated; prefer `[config.endpoints]`).
    #[serde(default)]
    pub llm_url: Option<String>,
    /// LLM model name (deprecated; prefer `[config.endpoints]`).
    #[serde(default)]
    pub llm_model: Option<String>,
    /// LLM API key (Bearer token).
    #[serde(default)]
    pub llm_api_key: Option<String>,
    /// Custom HTTP headers as JSON key-value pairs.
    #[serde(default, deserialize_with = "deserialize_headers")]
    pub llm_headers: HashMap<String, String>,
    /// Run browser in headless mode.
    #[serde(default)]
    pub browser_headless: Option<bool>,
    /// HTTP / browser action timeout in seconds.
    #[serde(default)]
    pub timeout_secs: Option<u64>,
    /// Browser viewport width.
    #[serde(default)]
    pub viewport_width: Option<u32>,
    /// Browser viewport height.
    #[serde(default)]
    pub viewport_height: Option<u32>,
    /// Default URL every test auto-navigates to before running its steps.
    #[serde(default)]
    pub start_url: Option<String>,
    /// Whether to auto-navigate to `start_url` before test steps.
    ///
    /// Disable when a test starts with click-based navigation.
    #[serde(default = "default_auto_navigate")]
    pub auto_navigate: bool,
    /// LLM temperature (0.0–1.0). Lower = more deterministic.
    #[serde(default = "default_temperature")]
    pub temperature: f64,
    /// Enable thinking/reasoning tokens. `None` means the provider default
    /// is used (no `thinking` key is sent). Set to `true`/`false` to
    /// explicitly enable or disable.
    #[serde(default)]
    pub thinking: Option<bool>,
    /// Provider-specific model parameters merged into the chat completion
    /// request body (e.g. `effort = "high"` for Anthropic).
    #[serde(default, deserialize_with = "deserialize_model_params")]
    pub model_params: HashMap<String, Value>,
    /// Named endpoints (LLM, MCP, A2A agents) with pricing.
    #[serde(default)]
    pub endpoints: HashMap<String, EndpointConfig>,
    /// Global and per-test budgets for cost/token/call limits.
    #[serde(default)]
    pub budgets: BudgetsConfig,
    /// MCP server exposure configuration.
    #[serde(default)]
    pub mcp_server: Option<McpServerConfig>,
    /// A2A agent server exposure configuration.
    #[serde(default)]
    pub a2a_server: Option<A2aServerConfig>,
    /// Whether to continue running the remaining steps of a test after a
    /// step fails. Default `false` = fail fast: the first failed step ends
    /// the test and the rest are reported as skipped. Set to `true` to run
    /// every step (more diagnostics, more LLM cost on broken apps).
    #[serde(default)]
    pub continue_on_failure: bool,
    /// Longest edge (px) of screenshots attached to `screenshot = true`
    /// assert steps, before they are JPEG-encoded and sent to the vision
    /// endpoint. Downscaling keeps vision token cost/quality sane.
    /// Default: 1400.
    #[serde(default)]
    pub screenshot_max_dimension: Option<u32>,
    /// Height cap (px) of page coverage for screenshots attached to
    /// `screenshot = true` assert steps. The full scrollable page is
    /// captured, then split into viewport-tall tiles (each sent as its own
    /// image part, ordered from the top) covering at most this many pixels
    /// — below-the-fold content stays visible to the vision model at 1:1
    /// detail while token cost stays bounded. Accepts an absolute pixel
    /// count (`2880`) or a viewport multiple (`"20x"` = twenty times the
    /// currently applied viewport height, which follows viewport-matrix
    /// and per-test overrides). A value below the viewport height is
    /// raised to it, so the visible viewport is always fully included
    /// (`0` / `"0x"` therefore means "viewport only", the pre-full-page
    /// behavior). Default: `"20x"`.
    #[serde(default, deserialize_with = "deserialize_screenshot_max_height")]
    pub screenshot_max_height: Option<ScreenshotHeight>,
    /// Directory for failure artifacts (screenshots, page snapshots).
    /// Defaults to `artifacts`.
    #[serde(default)]
    pub artifacts_dir: Option<String>,
    /// Optional viewport matrix: when set, every test in the scenario is
    /// expanded into one variant per viewport (e.g. mobile/tablet/desktop).
    /// Each variant overrides the test's viewport and gets a ` — <name>`
    /// suffix on the test name. Per-test budgets apply per variant.
    #[serde(default)]
    pub viewport_matrix: Option<ViewportMatrix>,
    /// Class-name prefixes the `layout_no_issues` scan skips: elements
    /// whose class matches any prefix are ignored by the fixed-element,
    /// text-clipped, and overlap checks. Defaults cover the Angular CDK
    /// screen-reader helpers (`cdk-visually-hidden`,
    /// `cdk-describedby-message-container`, `cdk-overlay-container`),
    /// which are intentionally 1x1 / off-screen.
    #[serde(default = "default_layout_ignore_classes")]
    pub layout_ignore_classes: Vec<String>,
    /// Concurrency group for parallel runs across scenario files.
    /// When several scenario files are run together (`--parallel > 1`),
    /// files that declare the **same** `concurrency_group` are never
    /// executed at the same time — use this for files that touch the same
    /// shared backend state and would interfere if run concurrently. A file
    /// with no group gets its own implicit group, so distinct files run in
    /// parallel by default. Only honored when files are passed to the
    /// runner as a batch; has no effect on the steps within a single file,
    /// which always run sequentially.
    #[serde(default)]
    pub concurrency_group: Option<String>,
    /// Default for per-endpoint `cache` across all endpoints (default
    /// `true`). Set to `false` to disable provider-side prompt-cache
    /// markers globally.
    #[serde(default)]
    pub cache: Option<bool>,
    /// Default for per-endpoint `pricing.cache_pricing` across all
    /// endpoints (default `true`). Set to `false` to bill all prompt
    /// tokens at the flat input price instead of cache rates.
    #[serde(default)]
    pub cache_pricing: Option<bool>,
}

/// A list of named viewports a scenario is expanded across.
#[derive(Debug, Deserialize, Clone, Default)]
pub struct ViewportMatrix {
    /// The viewport variants (`{name, width, height}`).
    #[serde(default)]
    pub viewports: Vec<ViewportDef>,
}

/// Height cap for screenshots attached to `screenshot = true` assert
/// steps: either an absolute pixel count or a multiple of the currently
/// applied viewport height.
#[derive(Debug, Clone, PartialEq)]
pub enum ScreenshotHeight {
    /// Absolute height in pixels.
    Pixels(u32),
    /// Multiple of the active viewport height (e.g. `2x` = twice the
    /// current viewport's pixel height).
    ViewportTimes(f64),
}

/// Ceiling (px) applied when resolving screenshot height specs, so an
/// absurdly large multiplier can never overflow or produce an unusable
/// capture.
const MAX_SCREENSHOT_HEIGHT: u32 = 4_000_000;

impl ScreenshotHeight {
    /// Resolves this height spec to a pixel value for the given viewport
    /// height. Multipliers are rounded and clamped to
    /// [`MAX_SCREENSHOT_HEIGHT`].
    #[must_use]
    pub fn to_px(&self, viewport_height: u32) -> u32 {
        match self {
            Self::Pixels(px) => *px,
            Self::ViewportTimes(mult) => {
                let scaled = f64::from(viewport_height) * mult;
                #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
                let px = scaled
                    .round()
                    .max(1.0)
                    .min(f64::from(MAX_SCREENSHOT_HEIGHT)) as u32;
                px
            }
        }
    }
}

/// One named viewport size in a matrix.
#[derive(Debug, Deserialize, Clone)]
pub struct ViewportDef {
    /// Human-readable variant name (appended to test names, e.g.
    /// `— mobile`).
    pub name: String,
    /// Browser viewport width in pixels.
    pub width: u32,
    /// Browser viewport height in pixels.
    pub height: u32,
}

/// A named endpoint definition with pricing.
#[derive(Debug, Deserialize, Clone, Default)]
pub struct EndpointConfig {
    /// Endpoint type: `llm`, `mcp`, or `a2a`.
    #[serde(rename = "type")]
    pub endpoint_type: EndpointType,
    /// Base URL for the endpoint.
    #[serde(default)]
    pub url: Option<String>,
    /// Model name (LLM endpoints only).
    #[serde(default)]
    pub model: Option<String>,
    /// API key / bearer token.
    #[serde(default)]
    pub api_key: Option<String>,
    /// Custom HTTP headers as JSON key-value pairs.
    #[serde(default, deserialize_with = "deserialize_headers")]
    pub headers: HashMap<String, String>,
    /// Pricing configuration.
    #[serde(default)]
    pub pricing: Option<PricingConfig>,
    /// Automatically fetch exact per-token pricing for this endpoint from a
    /// provider's public pricing API, filling in any pricing fields left
    /// unset. `"openrouter"` always uses the `OpenRouter` models API;
    /// `"auto"` does so only when the endpoint URL host is `openrouter.ai`.
    /// Explicit `pricing` values win over fetched ones.
    #[serde(default)]
    pub pricing_source: Option<String>,
    /// Task types this endpoint serves by default
    /// (e.g. `["targeting", "assertion"]`).
    #[serde(default)]
    pub default_for: Vec<String>,
    /// Command to launch an MCP server subprocess (stdio transport).
    #[serde(default)]
    pub command: Option<String>,
    /// Arguments for the MCP server command.
    #[serde(default)]
    pub args: Vec<String>,
    /// Whether this LLM endpoint accepts image parts (vision) in addition
    /// to text. `assert` steps with `screenshot = true` require a vision
    /// endpoint.
    #[serde(default)]
    pub vision: bool,
    /// How often a single chat completion against this endpoint is retried
    /// on transient failures (HTTP 429/5xx, empty 200 bodies, network
    /// errors) before the fallback chain is tried. Default: 3 (override
    /// globally with `HARNESS_LLM_CALL_ATTEMPTS`).
    #[serde(default)]
    pub max_attempts: Option<u32>,
    /// Ordered names of other endpoints to try when this endpoint exhausts
    /// its attempts. Only LLM endpoints are eligible. Useful for pairing a
    /// cheap primary model with a more powerful/expensive fallback.
    #[serde(default)]
    pub fallbacks: Vec<String>,
    /// LLM provider protocol: `openai` (default, OpenAI-compatible chat
    /// completions), `azure` (`Azure` `OpenAI`), or `bedrock` (AWS Bedrock
    /// Converse API; requires the `aws` cargo feature).
    #[serde(default)]
    pub provider: Provider,
    /// `Azure` `OpenAI` deployment name (`provider = "azure"`). Defaults to
    /// `model` when unset.
    #[serde(default)]
    pub deployment: Option<String>,
    /// `Azure` `OpenAI` API version (`provider = "azure"`). Defaults to
    /// `2024-10-21`.
    #[serde(default)]
    pub api_version: Option<String>,
    /// Authentication configuration for LLM endpoints (API key, token
    /// command, Entra ID client credentials / managed identity).
    #[serde(default)]
    pub auth: AuthConfig,
    /// Extra HTTP headers produced by running a command per call, keyed by
    /// header name. The command's stdout (first line) becomes the header
    /// value. Provider-agnostic — applies to every LLM provider.
    #[serde(default, deserialize_with = "deserialize_headers")]
    pub header_commands: HashMap<String, String>,
    /// AWS credential settings (`provider = "bedrock"`).
    #[serde(default)]
    pub aws: AwsConfig,
    /// Send provider-side prompt-cache markers from this endpoint
    /// (default `true`). Only providers that require explicit markers are
    /// affected: AWS Bedrock gets a `cachePoint` block, and Anthropic-style
    /// OpenAI-compatible models (model name contains `claude`/`anthropic`,
    /// e.g. via `OpenRouter`) get a `cache_control: ephemeral` block on the
    /// system message. `OpenAI`, `Azure`, Groq, xAI and `DeepSeek` cache
    /// automatically and need no markers. Set to `false` to disable.
    #[serde(default)]
    pub cache: Option<bool>,
}

/// Type discriminator for endpoint configuration.
#[derive(Debug, Deserialize, Clone, PartialEq, Eq, Default)]
#[serde(rename_all = "lowercase")]
pub enum EndpointType {
    /// OpenAI-compatible LLM API.
    #[default]
    Llm,
    /// Model Context Protocol server.
    Mcp,
    /// Agent-to-Agent protocol agent.
    A2a,
}

/// LLM provider protocol used by an LLM endpoint.
#[derive(Debug, Deserialize, Clone, Copy, PartialEq, Eq, Default)]
#[serde(rename_all = "lowercase")]
pub enum Provider {
    /// OpenAI-compatible Chat Completions API
    /// (`POST <url>/v1/chat/completions`).
    #[default]
    Openai,
    /// `Azure` `OpenAI`
    /// (`POST <url>/openai/deployments/<deployment>/chat/completions`).
    Azure,
    /// AWS Bedrock Converse API (`POST https://bedrock-runtime.<region>
    /// .amazonaws.com/model/<model>/converse`). Requires the `aws` cargo
    /// feature; uses the standard AWS credential chain unless overridden.
    Bedrock,
}

/// Authentication mode for an LLM endpoint.
#[derive(Debug, Deserialize, Clone, Copy, PartialEq, Eq, Default)]
#[serde(rename_all = "kebab-case")]
pub enum AuthMode {
    /// Static API key. Sent as `Authorization: Bearer <key>` by default;
    /// set [`AuthConfig::api_key_header`] (or use the `azure` provider)
    /// to send it in a different header.
    #[default]
    ApiKey,
    /// Execute a command and use its stdout (first line) as the bearer
    /// token. Uses the `token_command` field. Provider-agnostic escape
    /// hatch — e.g. `az account get-access-token …`.
    TokenCommand,
    /// Entra ID (`Azure` AD) OAuth 2.0 client-credentials grant: exchanges
    /// `client_id` + `client_secret` in `tenant_id` for a bearer token.
    EntraClientCredentials,
    /// Entra ID managed identity: fetches a bearer token from the IMDS
    /// endpoint (works on `Azure` VMs / App Service / ACI with a
    /// system-assigned identity; zero credentials in the config).
    EntraManagedIdentity,
}

/// Authentication settings for an LLM endpoint.
#[derive(Debug, Deserialize, Clone, Default)]
pub struct AuthConfig {
    /// Which authentication mode to use. Default: `api-key`.
    #[serde(default)]
    pub mode: AuthMode,
    /// Header name that receives the API key instead of
    /// `Authorization: Bearer` (`mode = "api-key"`). For example the `Azure`
    /// `OpenAI` `api-key` header.
    #[serde(default)]
    pub api_key_header: Option<String>,
    /// Command whose stdout (first line) is used as the bearer token
    /// (`mode = "token-command"`).
    #[serde(default)]
    pub token_command: Option<String>,
    /// Entra tenant id (`mode = "entra-client-credentials"`,
    /// `"entra-managed-identity"`).
    #[serde(default)]
    pub tenant_id: Option<String>,
    /// Entra client id (`mode = "entra-client-credentials"`).
    #[serde(default)]
    pub client_id: Option<String>,
    /// Entra client secret (`mode = "entra-client-credentials"`).
    #[serde(default)]
    pub client_secret: Option<String>,
    /// Entra token scope. Defaults to
    /// `https://cognitiveservices.azure.com/.default`.
    #[serde(default)]
    pub scope: Option<String>,
    /// Override for the Entra token endpoint
    /// (`mode = "entra-client-credentials"`), default
    /// `https://login.microsoftonline.com`. Also used as the IMDS identity
    /// endpoint base for `"entra-managed-identity"` (default
    /// `http://169.254.169.254`). Mainly useful for tests and proxies.
    #[serde(default)]
    pub token_url: Option<String>,
    /// Seconds to reuse a fetched (non-API-key) token before refetching.
    /// For Entra modes the server-issued expiry is used when available;
    /// this caps the reuse window. Default 300.
    #[serde(default)]
    pub cache_ttl_secs: Option<u64>,
}

/// AWS credential and region settings for a `bedrock` provider endpoint.
///
/// When no explicit access key is given, the standard AWS credential chain
/// is used (env vars, shared config `~/.aws/config` + `~/.aws/credentials`,
/// SSO, ECS/IMDS) — the same behavior as the AWS CLI. `profile` selects a
/// named profile from the shared config, and `region` overrides the chain
/// default.
#[derive(Debug, Deserialize, Clone, Default)]
pub struct AwsConfig {
    /// Named profile from `~/.aws/config` / `~/.aws/credentials` to use
    /// (default: the AWS CLI default selection via `AWS_PROFILE` or
    /// `default`).
    #[serde(default)]
    pub profile: Option<String>,
    /// AWS region (default: `AWS_REGION` env or the profile's region;
    /// required if neither is set).
    #[serde(default)]
    pub region: Option<String>,
    /// Explicit access key id (bypasses the credential chain).
    #[serde(default)]
    pub access_key_id: Option<String>,
    /// Explicit secret access key (with `access_key_id`).
    #[serde(default)]
    pub secret_access_key: Option<String>,
    /// Optional session token for explicit temporary credentials.
    #[serde(default)]
    pub session_token: Option<String>,
}

/// Pricing configuration for an endpoint.
#[derive(Debug, Deserialize, Clone, Default)]
pub struct PricingConfig {
    /// Cost per 1M input tokens (USD).
    #[serde(default)]
    pub input_per_1m_tokens: f64,
    /// Cost per 1M output tokens (USD).
    #[serde(default)]
    pub output_per_1m_tokens: f64,
    /// Flat cost per call (USD), used for MCP/agent endpoints.
    #[serde(default)]
    pub per_call: f64,
    /// Cost per 1M cached-input (prompt cache read) tokens (USD). When
    /// unset, `input_per_1m_tokens * cache_read_multiplier` is used.
    #[serde(default)]
    pub cached_input_per_1m_tokens: Option<f64>,
    /// Cost per 1M cache-write (cache creation) input tokens (USD). When
    /// unset, `input_per_1m_tokens * cache_write_multiplier` is used.
    #[serde(default)]
    pub cache_write_per_1m_tokens: Option<f64>,
    /// Multiplier applied to `input_per_1m_tokens` for cache reads when
    /// `cached_input_per_1m_tokens` is unset. Default: 0.1.
    #[serde(default)]
    pub cache_read_multiplier: Option<f64>,
    /// Multiplier applied to `input_per_1m_tokens` for cache writes when
    /// `cache_write_per_1m_tokens` is unset. Default: 1.25.
    #[serde(default)]
    pub cache_write_multiplier: Option<f64>,
    /// Bill cache reads/writes at their cache rates (default `true`). Set
    /// to `false` to bill every prompt token at the flat input price.
    #[serde(default)]
    pub cache_pricing: Option<bool>,
}

/// Budget limits for test execution.
#[derive(Debug, Deserialize, Clone, Default)]
pub struct BudgetsConfig {
    /// Global budget across all tests in the scenario.
    #[serde(default)]
    pub global: Option<BudgetDef>,
    /// Default per-test budget. Individual tests can override.
    #[serde(default)]
    pub per_test_default: Option<BudgetDef>,
}

/// A budget definition with limits and enforcement mode.
#[derive(Debug, Deserialize, Clone)]
pub struct BudgetDef {
    /// Maximum cost in USD.
    #[serde(default)]
    pub max_cost: Option<f64>,
    /// Maximum total tokens (input + output).
    #[serde(default)]
    pub max_tokens: Option<u64>,
    /// Maximum number of calls (LLM, MCP, agent combined).
    #[serde(default)]
    pub max_calls: Option<u64>,
    /// Enforcement mode: `hard` (abort) or `soft` (warn and continue).
    #[serde(default)]
    pub enforcement: Option<BudgetEnforcement>,
}

/// Budget enforcement strategy.
#[derive(Debug, Deserialize, Clone, PartialEq, Eq)]
#[serde(rename_all = "lowercase")]
pub enum BudgetEnforcement {
    /// Abort the test or run when budget is exceeded.
    Hard,
    /// Log a warning but continue execution.
    Soft,
}

/// MCP server exposure configuration.
#[derive(Debug, Deserialize, Clone)]
pub struct McpServerConfig {
    /// Whether to enable the embedded MCP server.
    #[serde(default)]
    pub enabled: bool,
    /// Port to listen on.
    #[serde(default = "default_mcp_port")]
    pub port: u16,
}

const fn default_mcp_port() -> u16 {
    3000
}

/// A2A agent server exposure configuration.
#[derive(Debug, Deserialize, Clone)]
pub struct A2aServerConfig {
    /// Whether to enable the embedded A2A agent server.
    #[serde(default)]
    pub enabled: bool,
    /// Port to listen on.
    #[serde(default = "default_a2a_port")]
    pub port: u16,
}

const fn default_a2a_port() -> u16 {
    3100
}

fn deserialize_headers<'de, D>(deserializer: D) -> Result<HashMap<String, String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let raw: Option<serde_json::Value> = Option::deserialize(deserializer)?;
    let Some(json) = raw else {
        return Ok(HashMap::new());
    };
    let serde_json::Value::Object(obj) = json else {
        return Ok(HashMap::new());
    };
    Ok(obj
        .into_iter()
        .filter_map(|(k, v)| v.as_str().map(|s| (k, s.to_owned())))
        .collect())
}

const fn default_auto_navigate() -> bool {
    true
}

fn default_layout_ignore_classes() -> Vec<String> {
    vec![
        "cdk-visually-hidden".to_owned(),
        "cdk-describedby-message-container".to_owned(),
        "cdk-overlay-container".to_owned(),
    ]
}

const fn default_temperature() -> f64 {
    0.0
}

fn deserialize_model_params<'de, D>(deserializer: D) -> Result<HashMap<String, Value>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum Raw {
        Map(HashMap<String, Value>),
        Table(HashMap<String, Value>),
    }
    let raw: Option<Raw> = Option::deserialize(deserializer)?;
    Ok(match raw {
        Some(Raw::Map(m) | Raw::Table(m)) => m,
        None => HashMap::new(),
    })
}

fn deserialize_screenshot_max_height<'de, D>(
    deserializer: D,
) -> Result<Option<ScreenshotHeight>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let raw: Option<serde_json::Value> = Option::deserialize(deserializer)?;
    match raw {
        None => Ok(None),
        Some(value) => match value.as_u64() {
            // Integer: absolute pixel count.
            Some(px) if px <= u64::from(MAX_SCREENSHOT_HEIGHT) => {
                #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
                Ok(Some(ScreenshotHeight::Pixels(px as u32)))
            }
            // String: viewport multiple like "2x" or "1.5x".
            None => match value.as_str() {
                Some(s) => {
                    let lower = s.trim().to_lowercase();
                    if lower.ends_with('x') {
                        let num = lower.strip_suffix("x");
                        if let Some(num) = num {
                            if let Ok(m) = num.parse::<f64>() {
                                if m > 0.0 {
                                    return Ok(Some(ScreenshotHeight::ViewportTimes(m)));
                                }
                            }
                        }
                    }
                    Err(serde::de::Error::custom(format_args!(
                        "screenshot_max_height must be a pixel count (e.g. 2880) or a viewport multiple like \"2x\", found {s:?}"
                    )))
                }
                None => Err(serde::de::Error::custom(format_args!(
                    "screenshot_max_height must be a pixel count (e.g. 2880) or a viewport multiple like \"2x\", found {value:?}"
                ))),
            },
            Some(_) => Err(serde::de::Error::custom(format_args!(
                "screenshot_max_height value too large (max {MAX_SCREENSHOT_HEIGHT} px)"
            ))),
        },
    }
}

/// Reusable assertion definition referenced by name from `assert` steps.
///
/// Definitions can either reference a built-in preset via `preset`, supply a
/// custom LLM `prompt`, or define a **custom preset** by providing both
/// `system` and `user_template`. Custom presets support the same template
/// variables as built-in presets: `{url}`, `{title}`, `{content}`,
/// `{expected_text}`, `{description}`.
#[derive(Debug, Deserialize, Clone)]
pub struct AssertDefinition {
    /// Unique name used to reference this definition from steps.
    pub name: String,
    /// Predefined assertion preset name
    /// (e.g. `no_error_on_page`, `text_visible`).
    #[serde(default)]
    pub preset: Option<String>,
    /// Custom LLM prompt for assertion evaluation.
    #[serde(default)]
    pub prompt: Option<String>,
    /// System prompt for a custom preset.
    #[serde(default)]
    pub system: Option<String>,
    /// User template (with `{placeholders}`) for a custom preset.
    #[serde(default)]
    pub user_template: Option<String>,
    /// Text that the `text_visible` preset checks for, or the
    /// `{expected_text}` placeholder value for custom presets.
    #[serde(default)]
    pub assert_text: Option<String>,
    /// Agent endpoint to call for this assertion.
    #[serde(default)]
    pub agent: Option<String>,
    /// Agent task template for this assertion.
    #[serde(default)]
    pub task_template: Option<String>,
}

/// A group of steps that form a single test scenario.
#[derive(Debug, Deserialize, Clone)]
pub struct TestGroup {
    /// Human-readable test name.
    pub name: String,
    /// Override the global `start_url` for this test.
    #[serde(default)]
    pub start_url: Option<String>,
    /// Override the global `auto_navigate` for this test.
    #[serde(default)]
    pub auto_navigate: Option<bool>,
    /// Override the global `base_url` for this test.
    #[serde(default)]
    pub base_url: Option<String>,
    /// Override the global `timeout_secs` for this test.
    #[serde(default)]
    pub timeout_secs: Option<u64>,
    /// Override the global `browser_headless` for this test.
    #[serde(default)]
    pub browser_headless: Option<bool>,
    /// Override the global viewport width for this test (applied via CDP
    /// `Emulation.setDeviceMetricsOverride` before the test runs).
    #[serde(default)]
    pub viewport_width: Option<u32>,
    /// Override the global viewport height for this test.
    #[serde(default)]
    pub viewport_height: Option<u32>,
    /// Per-test budget override.
    #[serde(default)]
    pub budget: Option<BudgetDef>,
    /// Endpoint to use for all steps in this test (can be overridden
    /// per-step).
    #[serde(default)]
    pub endpoint: Option<String>,
    /// Ordered steps to execute.
    #[serde(default)]
    pub steps: Vec<TestStep>,
}

/// A single step in a test. The `kind` field determines which variant is
/// deserialized and which field constraints apply.
#[derive(Debug, Deserialize, Clone)]
#[serde(tag = "kind")]
pub enum TestStep {
    /// Navigate the browser to a URL.
    #[serde(rename = "navigate")]
    Navigate {
        /// URL to navigate to (absolute, or relative to the test's
        /// base URL).
        url: String,
        /// Milliseconds to wait after navigation completes.
        #[serde(default)]
        wait_after_ms: Option<u64>,
    },

    /// Click an element described in natural language.
    #[serde(rename = "click")]
    Click {
        /// Natural language description of the element. The LLM resolves
        /// this to a CSS selector at runtime.
        target: String,
        /// Explicit CSS selector override (bypasses LLM resolution).
        #[serde(default)]
        selector: Option<String>,
        /// Milliseconds to wait after the click.
        #[serde(default)]
        wait_after_ms: Option<u64>,
        /// Endpoint to use for LLM element targeting.
        #[serde(default)]
        endpoint: Option<String>,
        /// Idempotent: when the target element is absent the step is
        /// reported skipped instead of failed (the action was already
        /// done / not applicable).
        #[serde(default)]
        idempotent: bool,
    },

    /// Type text into an input element.
    #[serde(rename = "type")]
    Type {
        /// Natural language description of the target input element.
        target: String,
        /// Text to type into the element.
        text: String,
        /// Explicit CSS selector override (bypasses LLM resolution).
        #[serde(default)]
        selector: Option<String>,
        /// Milliseconds to wait after typing.
        #[serde(default)]
        wait_after_ms: Option<u64>,
        /// Endpoint to use for LLM element targeting.
        #[serde(default)]
        endpoint: Option<String>,
        /// Idempotent: when the target element is absent the step is
        /// reported skipped instead of failed (the action was already
        /// done / not applicable).
        #[serde(default)]
        idempotent: bool,
    },

    /// Wait for an element to appear on the page.
    #[serde(rename = "wait")]
    Wait {
        /// Natural language description of the element to wait for.
        target: String,
        /// Explicit CSS selector override (bypasses LLM resolution).
        #[serde(default)]
        selector: Option<String>,
        /// Wait until the page's visible text contains this substring
        /// (alternative to `selector`; either or both may be set — both are
        /// required to hold when both are set).
        #[serde(default)]
        text: Option<String>,
        /// Maximum milliseconds to wait (default: 10000).
        #[serde(default)]
        timeout_ms: Option<u64>,
        /// Endpoint to use for LLM element targeting.
        #[serde(default)]
        endpoint: Option<String>,
        /// Idempotent: when the condition never becomes true within the
        /// timeout the step is reported skipped instead of failed (the
        /// condition was not applicable, e.g. already-authenticated
        /// pages in a viewport matrix).
        #[serde(default)]
        idempotent: bool,
    },

    /// Evaluate an assertion against the current page content.
    #[serde(rename = "assert")]
    Assert {
        /// Reference to a named `[[definitions]]` entry.
        #[serde(default)]
        definition: Option<String>,
        /// Inline predefined assertion preset (e.g. `no_error_on_page`).
        #[serde(default)]
        preset: Option<String>,
        /// Inline custom LLM prompt for assertion evaluation.
        #[serde(default)]
        prompt: Option<String>,
        /// Text that the `text_visible` preset checks for.
        #[serde(default)]
        assert_text: Option<String>,
        /// Endpoint to use for this assertion's LLM call.
        #[serde(default)]
        endpoint: Option<String>,
        /// Attach a screenshot of the current viewport to the assertion so
        /// the LLM can evaluate visuals (overlaps, clipping, layout).
        /// Requires the resolved endpoint to declare `vision = true`.
        #[serde(default)]
        screenshot: bool,
    },

    /// Take a screenshot of the current page.
    #[serde(rename = "screenshot")]
    Screenshot {
        /// File path to save the screenshot (default: `screenshot.png`).
        #[serde(default)]
        path: Option<String>,
    },

    /// Call an A2A agent with a task.
    #[serde(rename = "agent")]
    Agent {
        /// Name of the agent endpoint to call.
        agent: String,
        /// Task description / prompt for the agent.
        task: String,
        /// Optional definition name with a task template.
        #[serde(default)]
        definition: Option<String>,
    },

    /// Call an MCP server tool.
    #[serde(rename = "mcp")]
    Mcp {
        /// Name of the MCP server endpoint.
        server: String,
        /// Tool name to invoke on the server.
        tool: String,
        /// Tool arguments as JSON.
        #[serde(default)]
        args: Option<serde_json::Value>,
    },
}