viewpoint_core/page/

mod.rs

//! Page management and navigation.

mod aria_snapshot;
pub mod binding;
mod ref_resolution;
pub mod clock;
mod clock_script;
pub mod console;
mod constructors;
mod content;
pub mod dialog;
pub mod download;
pub mod emulation;
mod evaluate;
pub mod events;
pub mod file_chooser;
pub mod frame;
pub mod frame_locator;
mod frame_locator_actions;
mod frame_page_methods;
mod input_devices;
pub mod keyboard;
pub mod locator;
mod locator_factory;
pub mod locator_handler;
mod mouse;
mod mouse_drag;
mod navigation;
pub mod page_error;
mod pdf;
pub mod popup;
mod routing_impl;
mod screenshot;
mod screenshot_element;
mod scripts;
mod touchscreen;
pub mod video;
mod video_io;

use std::sync::Arc;
use std::time::Duration;

use tracing::{debug, info, instrument, trace, warn};
use viewpoint_cdp::CdpConnection;
use viewpoint_cdp::protocol::page::{NavigateParams, NavigateResult};
use viewpoint_cdp::protocol::target_domain::CloseTargetParams;
use viewpoint_js::js;

use crate::error::{NavigationError, PageError};
use crate::network::{RouteHandlerRegistry, WebSocketManager};
use crate::wait::{DocumentLoadState, LoadStateWaiter};

pub use clock::{Clock, TimeValue};
pub use console::{ConsoleMessage, ConsoleMessageLocation, ConsoleMessageType, JsArg};
pub use content::{ScriptTagBuilder, ScriptType, SetContentBuilder, StyleTagBuilder};
pub use dialog::Dialog;
pub use download::{Download, DownloadState};
pub use emulation::{EmulateMediaBuilder, MediaType, VisionDeficiency};
pub use evaluate::{JsHandle, Polling, WaitForFunctionBuilder};
pub use events::PageEventManager;
pub use file_chooser::{FileChooser, FilePayload};
pub use frame::Frame;
pub use frame_locator::{FrameElementLocator, FrameLocator, FrameRoleLocatorBuilder};
pub use keyboard::Keyboard;
pub use locator::{
    AriaCheckedState, AriaRole, AriaSnapshot, BoundingBox, BoxModel, ElementHandle, FilterBuilder,
    Locator, LocatorOptions, RoleLocatorBuilder, Selector, TapBuilder, TextOptions,
};
pub use locator_handler::{LocatorHandlerHandle, LocatorHandlerManager, LocatorHandlerOptions};
pub use mouse::Mouse;
pub use mouse_drag::DragAndDropBuilder;
pub use navigation::{GotoBuilder, NavigationResponse};
pub use page_error::{PageError as PageErrorInfo, WebError};
pub use pdf::{Margins, PaperFormat, PdfBuilder};
pub use screenshot::{Animations, ClipRegion, ScreenshotBuilder, ScreenshotFormat};
pub use touchscreen::Touchscreen;
pub use video::{Video, VideoOptions};
pub use viewpoint_cdp::protocol::DialogType;
pub use viewpoint_cdp::protocol::emulation::ViewportSize;
pub use viewpoint_cdp::protocol::input::MouseButton;

/// Default navigation timeout.
const DEFAULT_NAVIGATION_TIMEOUT: Duration = Duration::from_secs(30);

/// Default test ID attribute name.
pub const DEFAULT_TEST_ID_ATTRIBUTE: &str = "data-testid";

/// A browser page (tab).
pub struct Page {
    /// CDP connection.
    connection: Arc<CdpConnection>,
    /// Target ID.
    target_id: String,
    /// Session ID for this page.
    session_id: String,
    /// Main frame ID.
    frame_id: String,
    /// Whether the page has been closed.
    closed: bool,
    /// Route handler registry.
    route_registry: Arc<RouteHandlerRegistry>,
    /// Keyboard controller.
    keyboard: Keyboard,
    /// Mouse controller.
    mouse: Mouse,
    /// Touchscreen controller.
    touchscreen: Touchscreen,
    /// Event manager for dialogs, downloads, and file choosers.
    event_manager: Arc<PageEventManager>,
    /// Locator handler manager.
    locator_handler_manager: Arc<LocatorHandlerManager>,
    /// Video recording controller (if recording is enabled).
    video_controller: Option<Arc<Video>>,
    /// Opener target ID (for popup pages).
    opener_target_id: Option<String>,
    /// Popup event manager.
    popup_manager: Arc<popup::PopupManager>,
    /// WebSocket event manager.
    websocket_manager: Arc<WebSocketManager>,
    /// Exposed function binding manager.
    binding_manager: Arc<binding::BindingManager>,
    /// Custom test ID attribute (defaults to "data-testid").
    test_id_attribute: String,
}

// Manual Debug implementation since some fields don't implement Debug
impl std::fmt::Debug for Page {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("Page")
            .field("target_id", &self.target_id)
            .field("session_id", &self.session_id)
            .field("frame_id", &self.frame_id)
            .field("closed", &self.closed)
            .finish_non_exhaustive()
    }
}

impl Page {
    /// Navigate to a URL.
    ///
    /// Returns a builder for configuring navigation options.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use viewpoint_core::Page;
    /// use viewpoint_core::DocumentLoadState;
    /// use std::time::Duration;
    ///
    /// # async fn example(page: Page) -> Result<(), viewpoint_core::CoreError> {
    /// // Simple navigation
    /// page.goto("https://example.com").goto().await?;
    ///
    /// // Navigation with options
    /// page.goto("https://example.com")
    ///     .wait_until(DocumentLoadState::DomContentLoaded)
    ///     .timeout(Duration::from_secs(10))
    ///     .goto()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn goto(&self, url: impl Into<String>) -> GotoBuilder<'_> {
        GotoBuilder::new(self, url.into())
    }

    /// Navigate to a URL and wait for the specified load state.
    ///
    /// This is a convenience method that calls `goto(url).goto().await`.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - The page is closed
    /// - Navigation fails
    /// - The wait times out
    pub async fn goto_url(&self, url: &str) -> Result<NavigationResponse, NavigationError> {
        self.goto(url).goto().await
    }

    /// Navigate to a URL with the given options.
    #[instrument(level = "info", skip(self), fields(target_id = %self.target_id, url = %url, wait_until = ?wait_until, timeout_ms = timeout.as_millis()))]
    pub(crate) async fn navigate_internal(
        &self,
        url: &str,
        wait_until: DocumentLoadState,
        timeout: Duration,
        referer: Option<&str>,
    ) -> Result<NavigationResponse, NavigationError> {
        if self.closed {
            warn!("Attempted navigation on closed page");
            return Err(NavigationError::Cancelled);
        }

        info!("Starting navigation");

        // Create a load state waiter
        let event_rx = self.connection.subscribe_events();
        let mut waiter =
            LoadStateWaiter::new(event_rx, self.session_id.clone(), self.frame_id.clone());
        trace!("Created load state waiter");

        // Send the navigation command
        debug!("Sending Page.navigate command");
        let result: NavigateResult = self
            .connection
            .send_command(
                "Page.navigate",
                Some(NavigateParams {
                    url: url.to_string(),
                    referrer: referer.map(ToString::to_string),
                    transition_type: None,
                    frame_id: None,
                }),
                Some(&self.session_id),
            )
            .await?;

        debug!(frame_id = %result.frame_id, loader_id = ?result.loader_id, "Page.navigate completed");

        // Check for navigation errors
        // Note: Chrome reports HTTP error status codes (4xx, 5xx) as errors with
        // "net::ERR_HTTP_RESPONSE_CODE_FAILURE" or "net::ERR_INVALID_AUTH_CREDENTIALS".
        // Following Playwright's behavior, we treat these as successful navigations
        // that return a response with the appropriate status code.
        if let Some(ref error_text) = result.error_text {
            let is_http_error = error_text == "net::ERR_HTTP_RESPONSE_CODE_FAILURE"
                || error_text == "net::ERR_INVALID_AUTH_CREDENTIALS";

            if !is_http_error {
                warn!(error = %error_text, "Navigation failed with error");
                return Err(NavigationError::NetworkError(error_text.clone()));
            }
            debug!(error = %error_text, "HTTP error response - continuing to capture status");
        }

        // Mark commit as received
        trace!("Setting commit received");
        waiter.set_commit_received().await;

        // Wait for the target load state
        debug!(wait_until = ?wait_until, "Waiting for load state");
        waiter
            .wait_for_load_state_with_timeout(wait_until, timeout)
            .await?;

        // Get response data captured during navigation
        let response_data = waiter.response_data().await;

        info!(frame_id = %result.frame_id, "Navigation completed successfully");

        // Use the final URL from response data if available (handles redirects)
        let final_url = response_data.url.unwrap_or_else(|| url.to_string());

        // Build the response with captured data
        if let Some(status) = response_data.status {
            Ok(NavigationResponse::with_response(
                final_url,
                result.frame_id,
                status,
                response_data.headers,
            ))
        } else {
            Ok(NavigationResponse::new(final_url, result.frame_id))
        }
    }

    /// Close this page.
    ///
    /// # Errors
    ///
    /// Returns an error if closing fails.
    #[instrument(level = "info", skip(self), fields(target_id = %self.target_id))]
    pub async fn close(&mut self) -> Result<(), PageError> {
        if self.closed {
            debug!("Page already closed");
            return Ok(());
        }

        info!("Closing page");

        // Clean up route handlers
        self.route_registry.unroute_all().await;
        debug!("Route handlers cleaned up");

        self.connection
            .send_command::<_, serde_json::Value>(
                "Target.closeTarget",
                Some(CloseTargetParams {
                    target_id: self.target_id.clone(),
                }),
                None,
            )
            .await?;

        self.closed = true;
        info!("Page closed");
        Ok(())
    }

    /// Get the target ID.
    pub fn target_id(&self) -> &str {
        &self.target_id
    }

    /// Get the session ID.
    pub fn session_id(&self) -> &str {
        &self.session_id
    }

    /// Get the main frame ID.
    pub fn frame_id(&self) -> &str {
        &self.frame_id
    }

    /// Check if this page has been closed.
    pub fn is_closed(&self) -> bool {
        self.closed
    }

    /// Get a reference to the CDP connection.
    pub fn connection(&self) -> &Arc<CdpConnection> {
        &self.connection
    }

    // =========================================================================
    // Screenshot & PDF Methods
    // =========================================================================

    /// Create a screenshot builder for capturing page screenshots.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # async fn example(page: viewpoint_core::Page) -> Result<(), viewpoint_core::CoreError> {
    /// // Capture viewport screenshot
    /// let bytes = page.screenshot().capture().await?;
    ///
    /// // Capture full page screenshot
    /// page.screenshot()
    ///     .full_page(true)
    ///     .path("screenshot.png")
    ///     .capture()
    ///     .await?;
    ///
    /// // Capture JPEG with quality
    /// page.screenshot()
    ///     .jpeg(Some(80))
    ///     .path("screenshot.jpg")
    ///     .capture()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn screenshot(&self) -> screenshot::ScreenshotBuilder<'_> {
        screenshot::ScreenshotBuilder::new(self)
    }

    /// Create a PDF builder for generating PDFs from the page.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use viewpoint_core::page::PaperFormat;
    ///
    /// # async fn example(page: viewpoint_core::Page) -> Result<(), viewpoint_core::CoreError> {
    /// // Generate PDF with default settings
    /// let bytes = page.pdf().generate().await?;
    ///
    /// // Generate A4 landscape PDF
    /// page.pdf()
    ///     .format(PaperFormat::A4)
    ///     .landscape(true)
    ///     .path("document.pdf")
    ///     .generate()
    ///     .await?;
    ///
    /// // Generate PDF with custom margins
    /// page.pdf()
    ///     .margin(1.0) // 1 inch margins
    ///     .print_background(true)
    ///     .generate()
    ///     .await?;
    /// # Ok(())
    /// # }
    /// ```
    pub fn pdf(&self) -> pdf::PdfBuilder<'_> {
        pdf::PdfBuilder::new(self)
    }

    /// Get the current page URL.
    ///
    /// # Errors
    ///
    /// Returns an error if the page is closed or the evaluation fails.
    pub async fn url(&self) -> Result<String, PageError> {
        if self.closed {
            return Err(PageError::Closed);
        }

        let result: viewpoint_cdp::protocol::runtime::EvaluateResult = self
            .connection
            .send_command(
                "Runtime.evaluate",
                Some(viewpoint_cdp::protocol::runtime::EvaluateParams {
                    expression: js! { window.location.href }.to_string(),
                    object_group: None,
                    include_command_line_api: None,
                    silent: Some(true),
                    context_id: None,
                    return_by_value: Some(true),
                    await_promise: Some(false),
                }),
                Some(&self.session_id),
            )
            .await?;

        result
            .result
            .value
            .and_then(|v| v.as_str().map(std::string::ToString::to_string))
            .ok_or_else(|| PageError::EvaluationFailed("Failed to get URL".to_string()))
    }

    /// Get the current page title.
    ///
    /// # Errors
    ///
    /// Returns an error if the page is closed or the evaluation fails.
    pub async fn title(&self) -> Result<String, PageError> {
        if self.closed {
            return Err(PageError::Closed);
        }

        let result: viewpoint_cdp::protocol::runtime::EvaluateResult = self
            .connection
            .send_command(
                "Runtime.evaluate",
                Some(viewpoint_cdp::protocol::runtime::EvaluateParams {
                    expression: "document.title".to_string(),
                    object_group: None,
                    include_command_line_api: None,
                    silent: Some(true),
                    context_id: None,
                    return_by_value: Some(true),
                    await_promise: Some(false),
                }),
                Some(&self.session_id),
            )
            .await?;

        result
            .result
            .value
            .and_then(|v| v.as_str().map(std::string::ToString::to_string))
            .ok_or_else(|| PageError::EvaluationFailed("Failed to get title".to_string()))
    }
}

// Additional Page methods are defined in:
// - scripts.rs: add_init_script, add_init_script_path
// - locator_handler.rs: add_locator_handler, add_locator_handler_with_options, remove_locator_handler
// - video.rs: video, start_video_recording, stop_video_recording
// - binding.rs: expose_function, remove_exposed_function
// - input_devices.rs: keyboard, mouse, touchscreen, clock, drag_and_drop
// - locator_factory.rs: locator, get_by_*, set_test_id_attribute
// - DragAndDropBuilder is defined in mouse.rs
// - RoleLocatorBuilder is defined in locator/mod.rs