viewpoint_test/harness/

mod.rs

//! Test harness for browser automation tests.
//!
//! The [`TestHarness`] manages browser lifecycle (launch and cleanup) automatically,
//! providing a clean fixture for each test case.
//!
//! # Automatic Browser Lifecycle Management
//!
//! The harness handles all setup and teardown automatically:
//!
//! ```ignore
//! use viewpoint_test::TestHarness;
//!
//! #[tokio::test]
//! async fn test_example() -> Result<(), Box<dyn std::error::Error>> {
//!     // Setup: launches browser, creates context and page
//!     let harness = TestHarness::new().await?;
//!     let page = harness.page();
//!
//!     page.goto("https://example.com").goto().await?;
//!     // ... test logic ...
//!
//!     Ok(())  // Cleanup: browser is automatically closed when harness is dropped
//! }
//! ```
//!
//! # Sharing Browser Across Multiple Tests (Module-Scoped Fixtures)
//!
//! For faster test execution, share a browser across multiple tests:
//!
//! ```ignore
//! use viewpoint_test::TestHarness;
//! use viewpoint_core::Browser;
//! use std::sync::OnceLock;
//!
//! // Shared browser for all tests in this module
//! static SHARED_BROWSER: OnceLock<Browser> = OnceLock::new();
//!
//! async fn get_shared_browser() -> &'static Browser {
//!     if let Some(browser) = SHARED_BROWSER.get() {
//!         return browser;
//!     }
//!     let browser = Browser::launch().headless(true).launch().await.unwrap();
//!     SHARED_BROWSER.set(browser).unwrap();
//!     SHARED_BROWSER.get().unwrap()
//! }
//!
//! #[tokio::test]
//! async fn test_one() -> Result<(), Box<dyn std::error::Error>> {
//!     let browser = get_shared_browser().await;
//!     // Fresh context and page, reuses browser
//!     let harness = TestHarness::from_browser(browser).await?;
//!     let page = harness.page();
//!     
//!     page.goto("https://example.com").goto().await?;
//!     Ok(())  // Context and page cleaned up, browser stays alive
//! }
//!
//! #[tokio::test]
//! async fn test_two() -> Result<(), Box<dyn std::error::Error>> {
//!     let browser = get_shared_browser().await;
//!     let harness = TestHarness::from_browser(browser).await?;
//!     let page = harness.page();
//!     
//!     page.goto("https://example.org").goto().await?;
//!     Ok(())
//! }
//! ```
//!
//! # Fixture Scoping Levels
//!
//! | Method | Browser | Context | Page | Use Case |
//! |--------|---------|---------|------|----------|
//! | `TestHarness::new()` | New | New | New | Full isolation (default) |
//! | `TestHarness::from_browser(&browser)` | Shared | New | New | Faster tests, context isolation |
//! | `TestHarness::from_context(&context)` | Shared | Shared | New | Share cookies/state across tests |
//!
//! # Custom Configuration
//!
//! ```ignore
//! use viewpoint_test::{TestHarness, TestConfig};
//! use std::time::Duration;
//!
//! #[tokio::test]
//! async fn test_with_config() -> Result<(), Box<dyn std::error::Error>> {
//!     let harness = TestHarness::builder()
//!         .headless(false)  // Show browser for debugging
//!         .timeout(Duration::from_secs(60))
//!         .build()
//!         .await?;
//!     
//!     // Or use TestConfig directly
//!     let config = TestConfig::builder()
//!         .headless(true)
//!         .timeout(Duration::from_secs(30))
//!         .build();
//!     let harness = TestHarness::with_config(config).await?;
//!     
//!     Ok(())
//! }
//! ```

use tracing::{debug, info, instrument, warn};

use crate::config::TestConfig;
use crate::error::TestError;
use viewpoint_core::{Browser, BrowserContext, Page};

/// Test harness that manages browser, context, and page lifecycle.
///
/// The harness provides access to browser automation fixtures and handles
/// cleanup automatically via `Drop`. It supports different scoping levels
/// to balance test isolation against performance.
///
/// # Scoping Levels
///
/// - `TestHarness::new()` - Test-scoped: new browser per test (default)
/// - `TestHarness::from_browser()` - Module-scoped: reuse browser, fresh context/page
/// - `TestHarness::from_context()` - Shared context: reuse context, fresh page only
///
/// # Example
///
/// ```no_run
/// use viewpoint_test::TestHarness;
///
/// #[tokio::test]
/// async fn my_test() -> Result<(), Box<dyn std::error::Error>> {
///     let harness = TestHarness::new().await?;
///     let page = harness.page();
///
///     page.goto("https://example.com").goto().await?;
///
///     Ok(()) // harness drops and cleans up
/// }
/// ```
#[derive(Debug)]
pub struct TestHarness {
    /// The browser instance.
    browser: Option<Browser>,
    /// The browser context.
    context: Option<BrowserContext>,
    /// The page.
    page: Page,
    /// Whether we own the browser (should close on drop).
    owns_browser: bool,
    /// Whether we own the context (should close on drop).
    owns_context: bool,
    /// Test configuration.
    config: TestConfig,
}

impl TestHarness {
    /// Create a new test harness with default configuration.
    ///
    /// This creates a new browser, context, and page for the test.
    /// All resources are owned and will be cleaned up on drop.
    ///
    /// # Errors
    ///
    /// Returns an error if browser launch or page creation fails.
    #[instrument(level = "info", name = "TestHarness::new")]
    pub async fn new() -> Result<Self, TestError> {
        Self::with_config(TestConfig::default()).await
    }

    /// Create a new test harness with custom configuration.
    ///
    /// # Errors
    ///
    /// Returns an error if browser launch or page creation fails.
    #[instrument(level = "info", name = "TestHarness::with_config", skip(config))]
    pub async fn with_config(config: TestConfig) -> Result<Self, TestError> {
        info!(headless = config.headless, "Creating test harness");

        let browser = Browser::launch()
            .headless(config.headless)
            .launch()
            .await
            .map_err(|e| TestError::Setup(format!("Failed to launch browser: {e}")))?;

        debug!("Browser launched");

        let context = browser
            .new_context()
            .await
            .map_err(|e| TestError::Setup(format!("Failed to create context: {e}")))?;

        debug!("Context created");

        let page = context
            .new_page()
            .await
            .map_err(|e| TestError::Setup(format!("Failed to create page: {e}")))?;

        debug!("Page created");

        info!("Test harness ready");

        Ok(Self {
            browser: Some(browser),
            context: Some(context),
            page,
            owns_browser: true,
            owns_context: true,
            config,
        })
    }

    /// Create a test harness builder for custom configuration.
    pub fn builder() -> TestHarnessBuilder {
        TestHarnessBuilder::default()
    }

    /// Create a test harness using an existing browser.
    ///
    /// This creates a new context and page in the provided browser.
    /// The browser will NOT be closed when the harness is dropped.
    ///
    /// # Errors
    ///
    /// Returns an error if context or page creation fails.
    #[instrument(level = "info", name = "TestHarness::from_browser", skip(browser))]
    pub async fn from_browser(browser: &Browser) -> Result<Self, TestError> {
        info!("Creating test harness from existing browser");

        let context = browser
            .new_context()
            .await
            .map_err(|e| TestError::Setup(format!("Failed to create context: {e}")))?;

        debug!("Context created");

        let page = context
            .new_page()
            .await
            .map_err(|e| TestError::Setup(format!("Failed to create page: {e}")))?;

        debug!("Page created");

        info!("Test harness ready (browser shared)");

        Ok(Self {
            browser: None, // We don't own the browser
            context: Some(context),
            page,
            owns_browser: false,
            owns_context: true,
            config: TestConfig::default(),
        })
    }

    /// Create a test harness using an existing context.
    ///
    /// This creates a new page in the provided context.
    /// Neither the browser nor context will be closed when the harness is dropped.
    ///
    /// # Errors
    ///
    /// Returns an error if page creation fails.
    #[instrument(level = "info", name = "TestHarness::from_context", skip(context))]
    pub async fn from_context(context: &BrowserContext) -> Result<Self, TestError> {
        info!("Creating test harness from existing context");

        let page = context
            .new_page()
            .await
            .map_err(|e| TestError::Setup(format!("Failed to create page: {e}")))?;

        debug!("Page created");

        info!("Test harness ready (context shared)");

        Ok(Self {
            browser: None,
            context: None, // We don't own the context
            page,
            owns_browser: false,
            owns_context: false,
            config: TestConfig::default(),
        })
    }

    /// Get a reference to the page.
    pub fn page(&self) -> &Page {
        &self.page
    }

    /// Get a mutable reference to the page.
    pub fn page_mut(&mut self) -> &mut Page {
        &mut self.page
    }

    /// Get a reference to the browser context.
    ///
    /// Returns `None` if this harness was created with `from_context()`.
    pub fn context(&self) -> Option<&BrowserContext> {
        self.context.as_ref()
    }

    /// Get a reference to the browser.
    ///
    /// Returns `None` if this harness was created with `from_browser()` or `from_context()`.
    pub fn browser(&self) -> Option<&Browser> {
        self.browser.as_ref()
    }

    /// Get the test configuration.
    pub fn config(&self) -> &TestConfig {
        &self.config
    }

    /// Create a new page in the same context.
    ///
    /// # Errors
    ///
    /// Returns an error if page creation fails or if no context is available.
    pub async fn new_page(&self) -> Result<Page, TestError> {
        let context = self.context.as_ref().ok_or_else(|| {
            TestError::Setup("No context available (harness created with from_context)".to_string())
        })?;

        context
            .new_page()
            .await
            .map_err(|e| TestError::Setup(format!("Failed to create page: {e}")))
    }

    /// Explicitly close all owned resources.
    ///
    /// This is called automatically on drop, but can be called explicitly
    /// to handle cleanup errors.
    ///
    /// # Errors
    ///
    /// Returns an error if cleanup fails.
    #[instrument(level = "info", name = "TestHarness::close", skip(self))]
    pub async fn close(mut self) -> Result<(), TestError> {
        info!(
            owns_browser = self.owns_browser,
            owns_context = self.owns_context,
            "Closing test harness"
        );

        // Close page
        if let Err(e) = self.page.close().await {
            warn!("Failed to close page: {}", e);
        }

        // Close context if we own it
        if self.owns_context {
            if let Some(ref mut context) = self.context {
                if let Err(e) = context.close().await {
                    warn!("Failed to close context: {}", e);
                }
            }
        }

        // Close browser if we own it
        if self.owns_browser {
            if let Some(ref browser) = self.browser {
                if let Err(e) = browser.close().await {
                    warn!("Failed to close browser: {}", e);
                }
            }
        }

        info!("Test harness closed");
        Ok(())
    }
}

impl Drop for TestHarness {
    fn drop(&mut self) {
        // We can't do async cleanup in Drop, so we rely on the underlying
        // types' Drop implementations. Browser::drop will kill the process
        // if we own it.
        debug!(
            owns_browser = self.owns_browser,
            owns_context = self.owns_context,
            "TestHarness dropped"
        );
    }
}

/// Builder for `TestHarness`.
#[derive(Debug, Default)]
pub struct TestHarnessBuilder {
    config: TestConfig,
}

impl TestHarnessBuilder {
    /// Set whether to run in headless mode.
    pub fn headless(mut self, headless: bool) -> Self {
        self.config.headless = headless;
        self
    }

    /// Set the default timeout.
    pub fn timeout(mut self, timeout: std::time::Duration) -> Self {
        self.config.timeout = timeout;
        self
    }

    /// Build and initialize the test harness.
    ///
    /// # Errors
    ///
    /// Returns an error if browser launch or page creation fails.
    pub async fn build(self) -> Result<TestHarness, TestError> {
        TestHarness::with_config(self.config).await
    }
}