playwright-rs 0.20.1

// Playwright driver management
//
// Handles locating and managing the Playwright Node.js driver.
// Follows the same architecture as playwright-python, playwright-java, and playwright-dotnet.

use crate::{Error, Result};
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use tokio::io::{AsyncReadExt, AsyncWriteExt};

/// Get the path to the Playwright driver executable
///
/// The driver directory is located in this order:
/// 1. `PLAYWRIGHT_DRIVER_PATH` (user override: a directory holding `node`, or
///    `node.exe` on Windows, and `package/cli.js`)
/// 2. The driver build.rs assembled, at the path it recorded (by default the
///    user cache; `PLAYWRIGHT_DRIVER_CACHE_DIR` moves it)
/// 3. The user cache at this crate's version and platform, which
///    `playwright-rs install` also populates; the same path as 2 for a
///    default build, and the one that still resolves when 2's record is
///    stale, as after `cargo install` or a build that skipped the download
/// 4. Global npm installation (`npm root -g`) (development fallback)
/// 5. Local npm installation (`npm root`) (development fallback)
///
/// On top of that, `PLAYWRIGHT_NODE_EXE` replaces the runtime and
/// `PLAYWRIGHT_CLI_JS` replaces the CLI script, each independently. Setting
/// only `PLAYWRIGHT_NODE_EXE` runs the resolved driver's `cli.js` under a
/// different runtime, which is how to try the driver under Bun. A bare
/// command name such as `bun` is left for `PATH` lookup at spawn; anything
/// with a directory component must exist. When both are set no driver
/// directory is needed at all.
///
/// An override that is set but does not point at an existing file is an
/// error rather than a fall-through: silently spawning the bundled driver
/// would hide the misconfiguration. An exported-but-empty variable counts as
/// unset.
///
/// Returns a tuple of (node_executable_path, cli_js_path).
///
/// # Errors
///
/// Returns `Error::DriverMisconfigured` if an override environment variable
/// is set but does not point at an existing file, and `Error::ServerNotFound`
/// if no driver can be located in any of the search paths.
///
/// # Example
///
/// ```no_run
/// use playwright_rs::server::driver::get_driver_executable;
///
/// let (node_exe, cli_js) = get_driver_executable()?;
/// println!("Node: {}", node_exe.display());
/// println!("CLI:  {}", cli_js.display());
/// # Ok::<(), playwright_rs::Error>(())
/// ```
pub fn get_driver_executable() -> Result<(PathBuf, PathBuf)> {
    resolve_driver(|name| std::env::var(name).ok())
}

/// Resolution behind `get_driver_executable`, parameterized by the
/// process-environment lookup so it can be tested with a fake environment
/// instead of mutating the real one.
fn resolve_driver(env: impl Fn(&str) -> Option<String>) -> Result<(PathBuf, PathBuf)> {
    // Exported-but-empty counts as unset, the convention build.rs already
    // uses for PLAYWRIGHT_DRIVER_DIR.
    let env = |name: &str| env(name).filter(|value| !value.is_empty());

    let driver = resolve_driver_dir(&env)?;
    let runtime = env("PLAYWRIGHT_NODE_EXE")
        .map(runtime_override)
        .transpose()?;
    let cli = env("PLAYWRIGHT_CLI_JS")
        .map(|value| existing_file("PLAYWRIGHT_CLI_JS", value))
        .transpose()?;

    match (runtime, cli, driver) {
        (Some(runtime), Some(cli), _) => Ok((runtime, cli)),
        (runtime, cli, Some((driver_node, driver_cli))) => {
            Ok((runtime.unwrap_or(driver_node), cli.unwrap_or(driver_cli)))
        }
        (_, _, None) => Err(Error::ServerNotFound),
    }
}

/// The driver directory's `(node, cli.js)` pair: the `PLAYWRIGHT_DRIVER_PATH`
/// override first, then the bundled, user-cache, and npm locations. `None`
/// when nothing is found; an error only when the override is set but wrong.
fn resolve_driver_dir(env: &impl Fn(&str) -> Option<String>) -> Result<Option<(PathBuf, PathBuf)>> {
    if let Some(found) = try_driver_path_env(env)? {
        return Ok(Some(found));
    }
    if let Some(found) = try_bundled_driver()? {
        return Ok(Some(found));
    }
    if let Some(found) = try_user_cache_driver()? {
        return Ok(Some(found));
    }
    if let Some(found) = try_npm_global()? {
        return Ok(Some(found));
    }
    if let Some(found) = try_npm_local()? {
        return Ok(Some(found));
    }
    Ok(None)
}

/// What became of the driver the build script was meant to bundle, read
/// back from its `PLAYWRIGHT_DRIVER_DIR_SOURCE` and `PLAYWRIGHT_DRIVER_DIR`
/// markers when a launch finds no driver at all.
///
/// A consumer never sees the build script's warning: cargo shows
/// `cargo:warning` lines for workspace members only, so a dependency whose
/// driver download failed compiles clean and the first launch is the first
/// sign. [`Error::ServerNotFound`] renders this, which makes it the one
/// channel that reaches them.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum BundledDriver {
    /// The download or assembly failed at build time.
    DownloadFailed,
    /// `PLAYWRIGHT_SKIP_DRIVER_DOWNLOAD` (or docs.rs) turned the download off.
    Skipped,
    /// Assembled into this directory, which no longer holds a driver.
    Missing(String),
    /// The build left no usable record.
    NoRecord,
}

impl BundledDriver {
    /// The record for the build that compiled this crate.
    pub(crate) fn for_this_build() -> Self {
        Self::from_build_record(
            option_env!("PLAYWRIGHT_DRIVER_DIR_SOURCE"),
            option_env!("PLAYWRIGHT_DRIVER_DIR"),
        )
    }

    /// `source` is `user_cache`, `cache_dir`, or `out_dir` when the build
    /// script assembled a driver, `skipped` when asked not to, `failed` when
    /// the download broke;
    /// `dir` is where it put the driver, and is empty in the last two cases.
    /// An exported-but-empty directory counts as unset, as it does everywhere
    /// else in this module.
    pub(crate) fn from_build_record(source: Option<&str>, dir: Option<&str>) -> Self {
        match (source, dir.filter(|dir| !dir.is_empty())) {
            (Some("failed"), _) => Self::DownloadFailed,
            (Some("skipped"), _) => Self::Skipped,
            (Some(_), Some(dir)) => Self::Missing(dir.to_string()),
            _ => Self::NoRecord,
        }
    }

    /// The build-time part of the message: what happened and what undoes it.
    fn explain(&self) -> String {
        match self {
            Self::DownloadFailed => "The build script could not assemble the driver when \
                playwright-rs was compiled: the download from registry.npmjs.org or nodejs.org \
                failed, and cargo does not show a dependency's build warnings, so nothing reported \
                it until now. Rebuild with network access: `cargo clean -p playwright-rs` forces \
                the build script to run again, and it assembles into the user cache, so the \
                download happens once per machine."
                .to_string(),
            Self::Skipped => "The driver download was skipped when playwright-rs was compiled \
                (PLAYWRIGHT_SKIP_DRIVER_DOWNLOAD was set, or this is a docs.rs build). That knob \
                is for compile-only jobs; unset it for a build that launches a browser."
                .to_string(),
            Self::Missing(dir) => format!(
                "The driver assembled at build time is no longer at {dir}: the cache was cleaned, \
                or the directory was moved. Rebuild (the build script reassembles it), or use one \
                of the options below."
            ),
            Self::NoRecord => {
                "This build of playwright-rs has no record of a bundled driver.".to_string()
            }
        }
    }

    /// The full text of [`Error::ServerNotFound`] for this record.
    pub(crate) fn server_not_found_message(&self) -> String {
        format!(
            "Playwright server not found: no Playwright driver could be located.\n\n\
            {}\n\n\
            Other ways to provide one:\n  \
            playwright-rs install   (cargo install playwright-rs --features cli) puts a driver in \
            the user cache, which every build finds\n  \
            PLAYWRIGHT_DRIVER_PATH=<dir>   a directory holding node (node.exe on Windows) and \
            package/cli.js",
            self.explain()
        )
    }
}

/// The two files every driver directory holds for a Playwright platform:
/// the runtime binary (`node`, or `node.exe` on Windows targets) and the CLI
/// script at `package/cli.js`.
fn driver_layout(driver_dir: &Path, platform: &str) -> (PathBuf, PathBuf) {
    let node_exe = driver_dir.join(crate::driver_urls::node_exe_name(platform));
    let cli_js = driver_dir.join("package").join("cli.js");
    (node_exe, cli_js)
}

/// The Playwright platform identifier of the machine this code runs on,
/// for driver directories a user points at rather than ones a build
/// recorded. Unsupported hosts fall back to `linux`, as build.rs does.
fn host_platform() -> &'static str {
    crate::driver_urls::playwright_platform(std::env::consts::OS, std::env::consts::ARCH)
        .unwrap_or("linux")
}

/// `PLAYWRIGHT_NODE_EXE`: a bare command name (no directory component) is
/// left for `PATH` lookup at spawn; anything else must exist.
fn runtime_override(value: String) -> Result<PathBuf> {
    let is_bare_name = Path::new(&value).components().count() == 1;
    if is_bare_name {
        Ok(PathBuf::from(value))
    } else {
        existing_file("PLAYWRIGHT_NODE_EXE", value)
    }
}

fn existing_file(variable: &str, value: String) -> Result<PathBuf> {
    let path = PathBuf::from(value);
    if path.exists() {
        Ok(path)
    } else {
        Err(Error::DriverMisconfigured(format!(
            "{variable} is set to {} but that file does not exist",
            path.display()
        )))
    }
}

/// Try to find the bundled driver assembled by build.rs
///
/// This is the default path and matches how playwright-python, playwright-java,
/// and playwright-dotnet distribute their drivers. build.rs emits an empty
/// `PLAYWRIGHT_DRIVER_DIR` when the download was skipped or failed.
fn try_bundled_driver() -> Result<Option<(PathBuf, PathBuf)>> {
    let Some(driver_dir) = option_env!("PLAYWRIGHT_DRIVER_DIR").filter(|dir| !dir.is_empty())
    else {
        return Ok(None);
    };
    let platform = option_env!("PLAYWRIGHT_DRIVER_PLATFORM").unwrap_or(host_platform());
    let (node_exe, cli_js) = driver_layout(Path::new(driver_dir), platform);
    if node_exe.exists() && cli_js.exists() {
        Ok(Some((node_exe, cli_js)))
    } else {
        Ok(None)
    }
}

/// Try to find the driver in the user cache.
///
/// `build.rs` assembles there by default and `playwright-rs install` writes
/// the same path, `<cache>/playwright-rust/<version>/playwright-<version>-
/// <platform>-node<node>/`, so this finds a driver from either. It matters on its own
/// when the bundled lookup fails: a build that skipped or relocated the
/// download, or a `cargo install`ed binary whose recorded path is gone. The
/// version and platform come from compile-time env vars emitted by build.rs.
fn try_user_cache_driver() -> Result<Option<(PathBuf, PathBuf)>> {
    let Some(cache_dir) = dirs::cache_dir() else {
        return Ok(None);
    };
    let (Some(version), Some(platform)) = (
        option_env!("PLAYWRIGHT_DRIVER_VERSION"),
        option_env!("PLAYWRIGHT_DRIVER_PLATFORM"),
    ) else {
        return Ok(None);
    };
    try_user_cache_driver_in(&cache_dir, version, platform)
}

/// Resolution helper for `try_user_cache_driver` parameterized by cache root,
/// version, and platform, exposed at module scope so tests can drive it
/// with a `tempfile::tempdir()`.
fn try_user_cache_driver_in(
    cache_root: &Path,
    version: &str,
    platform: &str,
) -> Result<Option<(PathBuf, PathBuf)>> {
    let driver_dir = crate::driver_urls::cached_driver_dir(cache_root, version, platform);
    let (node_exe, cli_js) = driver_layout(&driver_dir, platform);

    if node_exe.exists() && cli_js.exists() {
        Ok(Some((node_exe, cli_js)))
    } else {
        Ok(None)
    }
}

/// Try to find driver from the `PLAYWRIGHT_DRIVER_PATH` override: a directory
/// holding `node` (or `node.exe` on Windows) and `package/cli.js`.
///
/// Returns `None` when the variable is unset and an error when it is set but
/// the directory does not hold both files.
fn try_driver_path_env(
    env: &impl Fn(&str) -> Option<String>,
) -> Result<Option<(PathBuf, PathBuf)>> {
    let Some(driver_path) = env("PLAYWRIGHT_DRIVER_PATH") else {
        return Ok(None);
    };
    let driver_dir = PathBuf::from(driver_path);
    let (node_exe, cli_js) = driver_layout(&driver_dir, host_platform());

    if node_exe.exists() && cli_js.exists() {
        Ok(Some((node_exe, cli_js)))
    } else {
        Err(Error::DriverMisconfigured(format!(
            "PLAYWRIGHT_DRIVER_PATH is set to {} but it does not contain both {} and package/cli.js",
            driver_dir.display(),
            crate::driver_urls::node_exe_name(host_platform())
        )))
    }
}

/// Try to find driver in npm global installation (development fallback)
fn try_npm_global() -> Result<Option<(PathBuf, PathBuf)>> {
    let output = Command::new("npm").args(["root", "-g"]).output();

    if let Ok(output) = output
        && output.status.success()
    {
        let npm_root = String::from_utf8_lossy(&output.stdout).trim().to_string();
        let node_modules = PathBuf::from(npm_root);
        if node_modules.exists()
            && let Ok(paths) = find_playwright_in_node_modules(&node_modules)
        {
            return Ok(Some(paths));
        }
    }

    Ok(None)
}

/// Try to find driver in npm local installation (development fallback)
fn try_npm_local() -> Result<Option<(PathBuf, PathBuf)>> {
    let output = Command::new("npm").args(["root"]).output();

    if let Ok(output) = output
        && output.status.success()
    {
        let npm_root = String::from_utf8_lossy(&output.stdout).trim().to_string();
        let node_modules = PathBuf::from(npm_root);
        if node_modules.exists()
            && let Ok(paths) = find_playwright_in_node_modules(&node_modules)
        {
            return Ok(Some(paths));
        }
    }

    Ok(None)
}

/// Find Playwright CLI in node_modules directory
///
/// Returns (node_executable, cli_js_path)
fn find_playwright_in_node_modules(node_modules: &Path) -> Result<(PathBuf, PathBuf)> {
    // Look for playwright or @playwright/test package
    let playwright_dirs = [
        node_modules.join("playwright"),
        node_modules.join("@playwright").join("test"),
    ];

    for playwright_dir in &playwright_dirs {
        if !playwright_dir.exists() {
            continue;
        }

        // Find cli.js in the package
        let cli_js = playwright_dir.join("cli.js");
        if !cli_js.exists() {
            continue;
        }

        // Find node executable from PATH
        if let Ok(node_exe) = find_node_executable() {
            return Ok((node_exe, cli_js));
        }
    }

    Err(Error::ServerNotFound)
}

/// Find the node executable in PATH or common locations
fn find_node_executable() -> Result<PathBuf> {
    // Try which/where command first
    #[cfg(not(windows))]
    let which_cmd = "which";
    #[cfg(windows)]
    let which_cmd = "where";

    if let Ok(output) = Command::new(which_cmd).arg("node").output()
        && output.status.success()
    {
        let node_path = String::from_utf8_lossy(&output.stdout).trim().to_string();
        if !node_path.is_empty() {
            let path = PathBuf::from(node_path.lines().next().unwrap_or(&node_path));
            if path.exists() {
                return Ok(path);
            }
        }
    }

    // Try common locations
    #[cfg(not(windows))]
    let common_locations = [
        "/usr/local/bin/node",
        "/usr/bin/node",
        "/opt/homebrew/bin/node",
        "/opt/local/bin/node",
    ];

    #[cfg(windows)]
    let common_locations = [
        "C:\\Program Files\\nodejs\\node.exe",
        "C:\\Program Files (x86)\\nodejs\\node.exe",
    ];

    for location in &common_locations {
        let path = PathBuf::from(location);
        if path.exists() {
            return Ok(path);
        }
    }

    Err(Error::LaunchFailed(
        "Node.js executable not found. Please install Node.js or set PLAYWRIGHT_NODE_EXE."
            .to_string(),
    ))
}

/// Install Playwright browsers programmatically.
///
/// Finds the bundled Playwright driver and runs:
/// `<driver>/node <driver>/package/cli.js install [browsers...]`
///
/// # Parameters
///
/// - `browsers` — optional slice of browser names (e.g. `&["chromium", "firefox"]`).
///   Pass `None` to install all browsers (equivalent to `npx playwright install`).
///   `Some(&[])` sends the same bare `install`, so it also installs the default
///   browsers; it is not a no-op probe.
///
/// Installs browsers only, on every platform — matching `npx playwright
/// install`. On Linux the browsers also need system libraries (libgtk,
/// libnss, etc.); use [`install_browsers_with_deps`] to install those
/// alongside, which runs the system package manager under `sudo`.
///
/// When those libraries are absent the driver says so and still exits 0, as
/// `npx playwright install` does, so this call succeeds and the browsers
/// fail to launch later. That case is logged at `warn` naming
/// [`install_browsers_with_deps`]; it is not an error, because installing
/// the libraries separately (a Docker layer, a base image) is legitimate.
///
/// # Output
///
/// The installer's stdout and stderr are streamed to this process's stdout and
/// stderr as it runs, so download progress is visible and a stall is
/// distinguishable from progress. Callers that must not emit to the terminal
/// (a TUI, a captured test harness) should redirect the process's own streams.
/// The output is also retained and included in the error on failure.
///
/// # Errors
///
/// - [`Error::ServerNotFound`] if the Playwright driver cannot be located.
/// - [`Error::DriverMisconfigured`] if a driver override environment variable
///   is set but does not point at an existing file.
/// - [`Error::LaunchFailed`] if the installation process exits with a non-zero
///   status or fails to spawn.
///
/// # Example
///
/// ```no_run
/// use playwright_rs::install_browsers;
///
/// #[tokio::main]
/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
///     // Install only Chromium
///     install_browsers(Some(&["chromium"])).await?;
///
///     // Install all browsers
///     install_browsers(None).await?;
///     Ok(())
/// }
/// ```
///
/// See: <https://playwright.dev/docs/browsers#installing-browsers>
pub async fn install_browsers(browsers: Option<&[&str]>) -> Result<()> {
    install_browsers_impl(browsers, /* with_deps_forced */ false).await
}

/// Install Playwright browsers and their system dependencies.
///
/// Identical to [`install_browsers`] but always passes `--with-deps` to the
/// Playwright CLI, regardless of the current operating system. This is the
/// recommended call for CI environments where system libraries may be missing.
/// Installing those libraries invokes the system package manager under `sudo`.
///
/// # Parameters
///
/// - `browsers` — optional slice of browser names. `None` installs all browsers.
///
/// # Output
///
/// Streams the installer's output live, like [`install_browsers`].
///
/// # Errors
///
/// - [`Error::ServerNotFound`] if the Playwright driver cannot be located.
/// - [`Error::DriverMisconfigured`] if a driver override environment variable
///   is set but does not point at an existing file.
/// - [`Error::LaunchFailed`] if the installation process exits with a non-zero
///   status or fails to spawn.
///
/// # Example
///
/// ```no_run
/// use playwright_rs::install_browsers_with_deps;
///
/// #[tokio::main]
/// async fn main() -> Result<(), Box<dyn std::error::Error>> {
///     install_browsers_with_deps(Some(&["chromium", "firefox"])).await?;
///     Ok(())
/// }
/// ```
///
/// See: <https://playwright.dev/docs/browsers#installing-browsers>
pub async fn install_browsers_with_deps(browsers: Option<&[&str]>) -> Result<()> {
    install_browsers_impl(browsers, /* with_deps_forced */ true).await
}

/// The driver CLI arguments for an install, in the order they are passed.
///
/// Split out as a pure function so the argument contract is unit-testable
/// without spawning a process: `--with-deps` appears only when asked for.
fn install_args(browsers: Option<&[&str]>, with_deps: bool) -> Vec<String> {
    let mut args = vec!["install".to_string()];
    if let Some(browser_list) = browsers {
        args.extend(browser_list.iter().map(|b| (*b).to_string()));
    }
    if with_deps {
        args.push("--with-deps".to_string());
    }
    args
}

/// Stream one of the child's pipes to `out`, keeping a copy for the error path.
///
/// Copies bytes rather than lines: the installer draws `\r`-updated progress
/// bars, which line buffering would hold back until the download finished.
async fn tee<R, W>(mut reader: R, mut out: W) -> Vec<u8>
where
    R: tokio::io::AsyncRead + Unpin,
    W: tokio::io::AsyncWrite + Unpin,
{
    let mut captured = Vec::new();
    let mut buf = [0u8; 4096];
    loop {
        match reader.read(&mut buf).await {
            Ok(0) => break,
            Ok(n) => {
                // A closed/redirected stdout must not fail the install itself.
                let _ = out.write_all(&buf[..n]).await;
                let _ = out.flush().await;
                captured.extend_from_slice(&buf[..n]);
            }
            // No retry arm here on purpose: any `continue` on a reader that
            // keeps failing is an unbounded loop, and tokio's io driver
            // already absorbs EINTR for the pipes we hand it.
            Err(e) => {
                // Mark it rather than break quietly: the capture feeds the
                // failure message, and silently truncated diagnostics are the
                // exact problem this function exists to fix.
                captured.extend_from_slice(
                    format!("\n[playwright-rs: output truncated, read error: {e}]\n").as_bytes(),
                );
                break;
            }
        }
    }
    captured
}

/// Internal implementation shared by [`install_browsers`] and [`install_browsers_with_deps`].
async fn install_browsers_impl(browsers: Option<&[&str]>, with_deps_forced: bool) -> Result<()> {
    let (node_exe, cli_js) = get_driver_executable()?;

    let mut cmd = tokio::process::Command::new(&node_exe);
    cmd.arg(&cli_js);
    // --with-deps is opt-in on every platform, matching upstream. Linux used
    // to get it implicitly, which ran sudo apt-get for a call that only asked
    // for browsers and made the CLI's own --with-deps flag a no-op there.
    cmd.args(install_args(browsers, with_deps_forced));
    cmd.stdout(Stdio::piped()).stderr(Stdio::piped());

    let mut child = cmd.spawn().map_err(|e| {
        Error::LaunchFailed(format!("Failed to spawn browser install process: {}", e))
    })?;

    let (Some(stdout), Some(stderr)) = (child.stdout.take(), child.stderr.take()) else {
        return Err(Error::LaunchFailed(
            "browser install process is missing the stdio pipes it was configured with".to_string(),
        ));
    };

    // Stream both pipes while the child runs. Installing browsers takes minutes
    // and can stall on a slow mirror or a contended package manager; buffering
    // until exit makes a stall indistinguishable from progress.
    let (out_bytes, err_bytes, status) = tokio::join!(
        tee(stdout, tokio::io::stdout()),
        tee(stderr, tokio::io::stderr()),
        child.wait(),
    );

    let status = status.map_err(|e| {
        Error::LaunchFailed(format!("Browser install process was not reaped: {}", e))
    })?;

    if !status.success() {
        let stdout = String::from_utf8_lossy(&out_bytes);
        let stderr = String::from_utf8_lossy(&err_bytes);
        return Err(Error::LaunchFailed(format!(
            "Browser installation failed (exit code {:?}).\nstdout: {}\nstderr: {}",
            status.code(),
            stdout.trim(),
            stderr.trim(),
        )));
    }

    // The driver reports missing system libraries and still exits 0 (it only
    // throws on Windows), so an install that leaves the browsers unable to
    // launch looks like a success. Upstream's own box says to run
    // `install-deps`; name the call that does it from here, since that is the
    // step a caller of this function is missing.
    if !with_deps_forced && missing_system_libraries(&out_bytes, &err_bytes) {
        tracing::warn!(
            "the driver reported missing system libraries and still exited 0, so the browsers \
             will not launch until they are installed: call install_browsers_with_deps (or pass \
             --with-deps) instead of install_browsers. Installing them separately, as a Docker \
             layer does, is also fine."
        );
    }

    Ok(())
}

/// Whether the installer's output carries the driver's missing-libraries
/// report.
///
/// Matched on the driver's own headline rather than the library list, which
/// is per-distribution. If upstream rewords it the check goes quiet, which is
/// the safe direction: the warning disappears, nothing starts failing.
fn missing_system_libraries(stdout: &[u8], stderr: &[u8]) -> bool {
    const MARKER: &str = "Host system is missing dependencies";
    String::from_utf8_lossy(stdout).contains(MARKER)
        || String::from_utf8_lossy(stderr).contains(MARKER)
}

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

    #[test]
    fn install_args_request_system_deps_only_when_asked() {
        assert_eq!(
            install_args(Some(&["chromium"]), false),
            vec!["install", "chromium"],
            "--with-deps is opt-in upstream; it must never be added unasked"
        );
        assert_eq!(
            install_args(Some(&["chromium"]), true),
            vec!["install", "chromium", "--with-deps"]
        );
    }

    #[test]
    fn install_args_pass_browsers_through_in_order() {
        assert_eq!(
            install_args(Some(&["chromium", "firefox", "webkit"]), false),
            vec!["install", "chromium", "firefox", "webkit"]
        );
    }

    #[tokio::test]
    async fn tee_marks_a_read_error_instead_of_truncating_silently() {
        struct FailAfterFirstChunk(bool);
        impl tokio::io::AsyncRead for FailAfterFirstChunk {
            fn poll_read(
                mut self: std::pin::Pin<&mut Self>,
                _: &mut std::task::Context<'_>,
                buf: &mut tokio::io::ReadBuf<'_>,
            ) -> std::task::Poll<std::io::Result<()>> {
                if self.0 {
                    return std::task::Poll::Ready(Err(std::io::Error::other("pipe died")));
                }
                self.0 = true;
                buf.put_slice(b"downloading...");
                std::task::Poll::Ready(Ok(()))
            }
        }

        let captured = tee(FailAfterFirstChunk(false), tokio::io::sink()).await;
        let text = String::from_utf8_lossy(&captured);
        assert!(text.starts_with("downloading..."), "keeps what it did read");
        assert!(
            text.contains("output truncated") && text.contains("pipe died"),
            "a lost pipe must be visible in the capture, not silent: {text}"
        );
    }

    #[tokio::test]
    async fn tee_streams_and_captures_the_same_bytes() {
        let input: &[u8] = b"downloading 12%\rdownloading 100%\ndone\n";
        let mut streamed = Vec::new();
        let captured = tee(input, &mut streamed).await;
        assert_eq!(captured, input, "capture feeds the failure message");
        assert_eq!(streamed, input, "streaming is what makes progress visible");
    }

    #[test]
    fn install_args_without_a_browser_list_install_the_defaults() {
        // Both spellings produce a bare `install`, which the driver reads as
        // "install the default browsers". Notably `Some(&[])` is *not* a no-op,
        // though an integration test long described it as one.
        assert_eq!(install_args(None, false), vec!["install"]);
        assert_eq!(install_args(Some(&[]), false), vec!["install"]);
        assert_eq!(install_args(None, true), vec!["install", "--with-deps"]);
    }

    #[test]
    fn missing_libraries_is_detected_on_either_stream() {
        // The driver's headline, as it writes it; the library list below it
        // is per-distribution and deliberately not matched.
        let report = b"Host system is missing dependencies!\n\nInstall them with...";
        assert!(missing_system_libraries(report, b""));
        assert!(missing_system_libraries(b"", report));
        assert!(!missing_system_libraries(
            b"Downloading Chromium 153...",
            b""
        ));
        assert!(!missing_system_libraries(b"", b""));
    }

    #[test]
    fn test_find_node_executable() {
        // This should succeed on any system with Node.js installed
        let result = find_node_executable();
        match result {
            Ok(node_path) => {
                tracing::info!("Found node at: {:?}", node_path);
                assert!(node_path.exists());
            }
            Err(e) => {
                tracing::warn!(
                    "Node.js not found (expected if Node.js not installed): {:?}",
                    e
                );
                // Don't fail the test if Node.js is not installed
            }
        }
    }

    #[test]
    fn test_get_driver_executable() {
        // Passes if any driver source is available; ignores the real process
        // environment so a stale override in a developer's shell cannot fail it
        let result = resolve_driver(|_| None);
        match result {
            Ok((node, cli)) => {
                tracing::info!("Found Playwright driver:");
                tracing::info!("  Node: {:?}", node);
                tracing::info!("  CLI:  {:?}", cli);
                assert!(node.exists());
                assert!(cli.exists());
            }
            Err(Error::ServerNotFound) => {
                tracing::warn!("Playwright driver not found (expected in some environments)");
                tracing::warn!(
                    "This is OK - driver will be bundled at build time or can be installed via npm"
                );
            }
            Err(e) => panic!("Unexpected error: {:?}", e),
        }
    }

    #[test]
    fn test_bundled_driver_detection() {
        // Test that we can detect bundled driver if build.rs set env vars
        let result = try_bundled_driver();
        match result {
            Ok(Some((node, cli))) => {
                tracing::info!("Found bundled driver:");
                tracing::info!("  Node: {:?}", node);
                tracing::info!("  CLI:  {:?}", cli);
                assert!(node.exists());
                assert!(cli.exists());
            }
            Ok(None) => {
                tracing::info!("No bundled driver (expected during development)");
            }
            Err(e) => panic!("Unexpected error: {:?}", e),
        }
    }

    #[test]
    fn try_user_cache_driver_in_resolves_when_files_present() {
        let temp = tempfile::tempdir().unwrap();
        let driver_subdir = crate::driver_urls::cached_driver_dir(temp.path(), "1.60.0", "linux");
        std::fs::create_dir_all(driver_subdir.join("package")).unwrap();
        std::fs::write(driver_subdir.join("node"), b"").unwrap();
        std::fs::write(driver_subdir.join("package").join("cli.js"), b"").unwrap();

        let (node, cli) = try_user_cache_driver_in(temp.path(), "1.60.0", "linux")
            .unwrap()
            .unwrap();
        assert!(node.exists());
        assert!(cli.exists());
    }

    #[test]
    fn try_user_cache_driver_in_returns_none_when_absent() {
        let temp = tempfile::tempdir().unwrap();
        let result = try_user_cache_driver_in(temp.path(), "1.60.0", "linux").unwrap();
        assert!(result.is_none());
    }

    #[test]
    fn a_user_cache_build_records_the_path_the_runtime_lookup_probes() {
        // Meaningful only where build.rs assembled into the user cache, which
        // is the default; a relocated, skipped, or homeless build records a
        // different source. This is the agreement the whole scheme rests on:
        // the bundled lookup and the user-cache lookup must name one path.
        if env!("PLAYWRIGHT_DRIVER_DIR_SOURCE") != "user_cache" {
            return;
        }
        let expected = crate::driver_urls::cached_driver_dir(
            &dirs::cache_dir().unwrap(),
            env!("PLAYWRIGHT_DRIVER_VERSION"),
            env!("PLAYWRIGHT_DRIVER_PLATFORM"),
        );
        assert_eq!(Path::new(env!("PLAYWRIGHT_DRIVER_DIR")), expected);
        assert_eq!(
            try_user_cache_driver().unwrap(),
            try_bundled_driver().unwrap()
        );
    }

    #[test]
    fn bundled_driver_dir_lives_under_out_dir() {
        // Meaningful only for the fallback a build takes when no cache root
        // resolves; the default records user_cache, CI's explicit location
        // records cache_dir, and compile-only jobs skip the download.
        if env!("PLAYWRIGHT_DRIVER_DIR_SOURCE") != "out_dir" {
            return;
        }
        let dir = env!("PLAYWRIGHT_DRIVER_DIR");
        let sep = std::path::MAIN_SEPARATOR;
        let build_marker = format!("{sep}build{sep}playwright-rs");
        let out_marker = format!("{sep}out{sep}");
        assert!(
            dir.contains(&build_marker) && dir.contains(&out_marker),
            "PLAYWRIGHT_DRIVER_DIR should sit under target/<profile>/build/playwright-rs-<hash>/out, got: {dir}"
        );
    }

    #[test]
    fn try_user_cache_driver_in_uses_node_exe_for_windows_platforms() {
        let temp = tempfile::tempdir().unwrap();
        let driver_subdir =
            crate::driver_urls::cached_driver_dir(temp.path(), "1.60.0", "win32_x64");
        std::fs::create_dir_all(driver_subdir.join("package")).unwrap();
        std::fs::write(driver_subdir.join("node.exe"), b"").unwrap();
        std::fs::write(driver_subdir.join("package").join("cli.js"), b"").unwrap();

        let (node, _cli) = try_user_cache_driver_in(temp.path(), "1.60.0", "win32_x64")
            .unwrap()
            .unwrap();
        assert!(
            node.file_name()
                .unwrap()
                .to_str()
                .unwrap()
                .ends_with(".exe")
        );
    }

    fn fake_driver_dir(temp: &Path) -> (PathBuf, PathBuf) {
        let (node, cli) = driver_layout(temp, host_platform());
        std::fs::create_dir_all(cli.parent().unwrap()).unwrap();
        std::fs::write(&node, b"").unwrap();
        std::fs::write(&cli, b"").unwrap();
        (node, cli)
    }

    fn env_of(vars: &[(&str, &str)]) -> impl Fn(&str) -> Option<String> + use<> {
        let vars: Vec<(String, String)> = vars
            .iter()
            .map(|(k, v)| (k.to_string(), v.to_string()))
            .collect();
        move |name| vars.iter().find(|(k, _)| k == name).map(|(_, v)| v.clone())
    }

    fn s(path: &Path) -> String {
        path.to_string_lossy().into_owned()
    }

    #[test]
    fn the_host_platform_is_a_known_target_of_this_os_family() {
        // A wrong answer here is invisible on a non-Windows host, where any
        // unknown string still maps to `node`; pin it to the target table
        // and to the OS family the binary was compiled for instead.
        let host = host_platform();
        assert!(crate::driver_urls::node_triple(host).is_some(), "{host}");
        assert_eq!(host.starts_with("mac"), cfg!(target_os = "macos"));
        assert_eq!(host.starts_with("linux"), cfg!(target_os = "linux"));
        assert_eq!(crate::driver_urls::is_windows_platform(host), cfg!(windows));
    }

    #[test]
    fn driver_path_override_wins_over_the_bundled_driver() {
        let temp = tempfile::tempdir().unwrap();
        let (node, cli) = fake_driver_dir(temp.path());
        let env = env_of(&[("PLAYWRIGHT_DRIVER_PATH", &s(temp.path()))]);

        assert_eq!(resolve_driver(env).unwrap(), (node, cli));
    }

    #[test]
    fn node_exe_override_swaps_the_runtime_and_keeps_the_resolved_cli() {
        let temp = tempfile::tempdir().unwrap();
        let (_node, cli) = fake_driver_dir(temp.path());
        let other_runtime = temp.path().join("other-runtime");
        std::fs::write(&other_runtime, b"").unwrap();
        let env = env_of(&[
            ("PLAYWRIGHT_DRIVER_PATH", &s(temp.path())),
            ("PLAYWRIGHT_NODE_EXE", &s(&other_runtime)),
        ]);

        assert_eq!(resolve_driver(env).unwrap(), (other_runtime, cli));
    }

    #[test]
    fn cli_js_override_swaps_the_cli_and_keeps_the_resolved_runtime() {
        let temp = tempfile::tempdir().unwrap();
        let (node, _cli) = fake_driver_dir(temp.path());
        let other_cli = temp.path().join("other-cli.js");
        std::fs::write(&other_cli, b"").unwrap();
        let env = env_of(&[
            ("PLAYWRIGHT_DRIVER_PATH", &s(temp.path())),
            ("PLAYWRIGHT_CLI_JS", &s(&other_cli)),
        ]);

        assert_eq!(resolve_driver(env).unwrap(), (node, other_cli));
    }

    #[test]
    fn node_exe_and_cli_js_together_win_over_the_bundled_driver() {
        let temp = tempfile::tempdir().unwrap();
        let (node, cli) = fake_driver_dir(temp.path());
        let env = env_of(&[
            ("PLAYWRIGHT_NODE_EXE", &s(&node)),
            ("PLAYWRIGHT_CLI_JS", &s(&cli)),
        ]);

        assert_eq!(resolve_driver(env).unwrap(), (node, cli));
    }

    #[test]
    fn a_bare_command_name_runtime_is_left_to_path_lookup() {
        let temp = tempfile::tempdir().unwrap();
        let (_node, cli) = fake_driver_dir(temp.path());
        let env = env_of(&[
            ("PLAYWRIGHT_DRIVER_PATH", &s(temp.path())),
            ("PLAYWRIGHT_NODE_EXE", "bun"),
        ]);

        assert_eq!(resolve_driver(env).unwrap(), (PathBuf::from("bun"), cli));
    }

    #[test]
    fn an_empty_override_counts_as_unset() {
        let temp = tempfile::tempdir().unwrap();
        let (node, cli) = fake_driver_dir(temp.path());
        let env = env_of(&[
            ("PLAYWRIGHT_DRIVER_PATH", ""),
            ("PLAYWRIGHT_NODE_EXE", &s(&node)),
            ("PLAYWRIGHT_CLI_JS", &s(&cli)),
        ]);

        assert_eq!(resolve_driver(env).unwrap(), (node, cli));
    }

    #[test]
    fn a_runtime_override_pointing_at_a_missing_file_is_an_error() {
        let temp = tempfile::tempdir().unwrap();
        fake_driver_dir(temp.path());
        let missing = temp.path().join("no-such-runtime");
        let env = env_of(&[
            ("PLAYWRIGHT_DRIVER_PATH", &s(temp.path())),
            ("PLAYWRIGHT_NODE_EXE", &s(&missing)),
        ]);

        let err = resolve_driver(env).unwrap_err();

        assert!(
            matches!(&err, Error::DriverMisconfigured(msg) if msg.contains("PLAYWRIGHT_NODE_EXE")),
            "expected DriverMisconfigured naming the variable, got {err:?}"
        );
    }

    #[test]
    fn a_cli_override_pointing_at_a_missing_file_is_an_error() {
        let temp = tempfile::tempdir().unwrap();
        fake_driver_dir(temp.path());
        let missing = temp.path().join("no-such-cli.js");
        let env = env_of(&[
            ("PLAYWRIGHT_DRIVER_PATH", &s(temp.path())),
            ("PLAYWRIGHT_CLI_JS", &s(&missing)),
        ]);

        let err = resolve_driver(env).unwrap_err();

        assert!(
            matches!(&err, Error::DriverMisconfigured(msg) if msg.contains("PLAYWRIGHT_CLI_JS")),
            "expected DriverMisconfigured naming the variable, got {err:?}"
        );
    }

    #[test]
    fn a_driver_path_override_with_only_the_runtime_in_it_is_an_error() {
        let temp = tempfile::tempdir().unwrap();
        let (_node, cli) = fake_driver_dir(temp.path());
        std::fs::remove_file(&cli).unwrap();
        let env = env_of(&[("PLAYWRIGHT_DRIVER_PATH", &s(temp.path()))]);

        let err = resolve_driver(env).unwrap_err();

        assert!(
            matches!(&err, Error::DriverMisconfigured(msg) if msg.contains("package/cli.js")),
            "expected DriverMisconfigured naming the missing file, got {err:?}"
        );
    }

    #[test]
    fn a_driver_path_override_without_a_driver_in_it_is_an_error() {
        let temp = tempfile::tempdir().unwrap();
        let env = env_of(&[("PLAYWRIGHT_DRIVER_PATH", &s(temp.path()))]);

        let err = resolve_driver(env).unwrap_err();

        assert!(
            matches!(&err, Error::DriverMisconfigured(msg) if msg.contains("PLAYWRIGHT_DRIVER_PATH")),
            "expected DriverMisconfigured naming the variable, got {err:?}"
        );
    }

    #[test]
    fn without_overrides_resolution_still_reaches_the_bundled_driver() {
        // Read the build record the way a failed launch does: `Missing` is
        // the arm where the build assembled a driver somewhere. A skipped or
        // failed download leaves nothing to reach, and the build-record tests
        // cover those.
        let BundledDriver::Missing(_) = BundledDriver::for_this_build() else {
            return;
        };
        let bundled = try_bundled_driver()
            .unwrap()
            .expect("the build recorded a driver dir, so the bundled driver must resolve");

        assert_eq!(resolve_driver(|_| None).unwrap(), bundled);
    }

    #[test]
    fn the_build_record_classifies_what_became_of_the_driver() {
        use BundledDriver::*;
        for (source, dir, expected) in [
            (Some("failed"), Some(""), DownloadFailed),
            (Some("skipped"), Some(""), Skipped),
            (
                Some("out_dir"),
                Some("/t/out/pw"),
                Missing("/t/out/pw".into()),
            ),
            (
                Some("cache_dir"),
                Some("/t/cache/pw"),
                Missing("/t/cache/pw".into()),
            ),
            (None, None, NoRecord),
            (None, Some("/t/out/pw"), NoRecord),
            // A failure is a failure whatever directory the record names.
            (Some("failed"), Some("/t/out/pw"), DownloadFailed),
        ] {
            assert_eq!(
                BundledDriver::from_build_record(source, dir),
                expected,
                "source {source:?}, dir {dir:?}"
            );
        }
    }

    #[test]
    fn an_empty_recorded_directory_counts_as_unset() {
        assert_eq!(
            BundledDriver::from_build_record(Some("out_dir"), Some("")),
            BundledDriver::NoRecord
        );
    }

    #[test]
    fn each_outcome_names_what_the_user_can_act_on() {
        use BundledDriver::*;
        for (record, tokens) in [
            (DownloadFailed, vec!["cargo clean -p playwright-rs"]),
            (Skipped, vec!["PLAYWRIGHT_SKIP_DRIVER_DOWNLOAD"]),
            (Missing("/t/out/pw".into()), vec!["/t/out/pw"]),
        ] {
            let msg = record.server_not_found_message();
            for token in tokens {
                assert!(msg.contains(token), "{record:?} must name {token}:\n{msg}");
            }
        }
    }

    #[test]
    fn every_outcome_keeps_the_headline_and_the_two_fallbacks() {
        use BundledDriver::*;
        for record in [
            DownloadFailed,
            Skipped,
            Missing("/t/out/pw".into()),
            NoRecord,
        ] {
            let msg = record.server_not_found_message();
            // The headline is what an integration test and a consumer's log
            // search key on; the fallbacks are the two remedies that work
            // whatever the build did.
            assert!(
                msg.starts_with("Playwright server not found"),
                "{record:?}:\n{msg}"
            );
            for token in [
                "playwright-rs install",
                "--features cli",
                "PLAYWRIGHT_DRIVER_PATH",
            ] {
                assert!(msg.contains(token), "{record:?} must name {token}:\n{msg}");
            }
        }
    }

    #[test]
    fn the_error_renders_the_record_for_this_build() {
        // Guards the #[error] wiring in error.rs, which is the only place the
        // record reaches a consumer.
        assert_eq!(
            Error::ServerNotFound.to_string(),
            BundledDriver::for_this_build().server_not_found_message()
        );
    }

    #[test]
    fn a_build_that_skipped_the_download_says_so_at_launch() {
        // Meaningful only where build.rs recorded a skip; the mutation and
        // MSRV jobs build that way, so CI exercises the real markers.
        if env!("PLAYWRIGHT_DRIVER_DIR_SOURCE") != "skipped" {
            return;
        }
        assert_eq!(BundledDriver::for_this_build(), BundledDriver::Skipped);
        assert!(
            Error::ServerNotFound
                .to_string()
                .contains("PLAYWRIGHT_SKIP_DRIVER_DOWNLOAD")
        );
    }
}