Crate viewpoint_core 

Viewpoint Core - Browser Automation Library

Core domain types for Viewpoint browser automation, providing a Playwright-inspired API for controlling Chromium-based browsers via the Chrome DevTools Protocol (CDP).

This crate provides the high-level API for browser automation, including Browser, BrowserContext, Page, and navigation types.

Features

• Browser Control: Launch or connect to Chromium browsers
• Page Navigation: Navigate pages and wait for load states
• Element Interaction: Click, type, and interact with page elements via Locator
• Network Interception: Route, modify, and mock network requests
• Device Emulation: Emulate mobile devices, geolocation, and media features
• Input Devices: Keyboard, mouse, and touchscreen control
• Screenshots & PDF: Capture screenshots and generate PDFs
• Clock Mocking: Control time in tests with Clock
• Event Handling: Dialogs, downloads, file choosers, console messages
• Tracing: Record traces for debugging
• Video Recording: Record page interactions as video

Quick Start

use viewpoint_core::{Browser, DocumentLoadState};

// Launch a browser and create a new context and page
let browser = Browser::launch()
    .headless(true)
    .launch()
    .await?;

let context = browser.new_context().await?;
let page = context.new_page().await?;

// Navigate to a page
page.goto("https://example.com").goto().await?;

// Interact with elements
page.locator("button#submit").click().await?;

// Fill a form
page.locator("input[name='email']").fill("user@example.com").await?;

// Get text content
let text = page.locator("h1").text_content().await?;
println!("Page title: {:?}", text);

Browser Connection Methods

There are three ways to get a Browser instance:

use viewpoint_core::Browser;
use std::time::Duration;

// 1. Launch a new browser process
let browser = Browser::launch()
    .headless(true)
    .launch()
    .await?;

// 2. Connect via WebSocket URL (for pre-configured connections)
let browser = Browser::connect("ws://localhost:9222/devtools/browser/...").await?;

// 3. Connect via HTTP endpoint (auto-discovers WebSocket URL)
let browser = Browser::connect_over_cdp("http://localhost:9222")
    .timeout(Duration::from_secs(10))
    .connect()
    .await?;

Element Locators

The Locator API provides auto-waiting and retry logic for robust element interaction:

use viewpoint_core::{Browser, AriaRole};

// CSS selector
page.locator("button.primary").click().await?;

// Text selector
page.get_by_text("Submit").click().await?;

// Role selector (accessibility)
page.get_by_role(AriaRole::Button)
    .with_name("Submit")
    .build()
    .click()
    .await?;

// Test ID selector (recommended for stable tests)
page.get_by_test_id("submit-button").click().await?;

// Label selector (for form fields)
page.get_by_label("Email address").fill("test@example.com").await?;

// Placeholder selector
page.get_by_placeholder("Enter your name").fill("John Doe").await?;

// Chained locators
page.locator(".form")
    .locator("input")
    .first()
    .fill("value")
    .await?;

Network Interception

Intercept and modify network requests using Route:

use viewpoint_core::{Browser, Route};

// Block images
page.route("**/*.{png,jpg,jpeg,gif}", |route| {
    async move { route.abort().await }
}).await?;

// Mock an API response
page.route("**/api/users", |route| {
    async move {
        route.fulfill()
            .status(200)
            .content_type("application/json")
            .body(r#"{"users": []}"#)
            .fulfill()
            .await
    }
}).await?;

// Modify requests
page.route("**/api/**", |route| {
    async move {
        route.continue_route()
            .header("X-Custom-Header", "value")
            .continue_route()
            .await
    }
}).await?;

Device Emulation

Emulate mobile devices and other capabilities:

use viewpoint_core::{Browser, Permission, ViewportSize};

// Create a context with mobile viewport and geolocation
let context = browser.new_context_builder()
    .viewport(390, 844)  // iPhone 14 size
    .device_scale_factor(3.0)
    .is_mobile(true)
    .has_touch(true)
    .geolocation(37.7749, -122.4194)  // San Francisco
    .permissions(vec![Permission::Geolocation])
    .build()
    .await?;

let page = context.new_page().await?;

Screenshots and PDF

Capture screenshots and generate PDFs:

use viewpoint_core::Browser;
use viewpoint_core::page::PaperFormat;

// Screenshot the viewport
page.screenshot()
    .path("screenshot.png")
    .capture()
    .await?;

// Full page screenshot
page.screenshot()
    .full_page(true)
    .path("full-page.png")
    .capture()
    .await?;

// Generate PDF (headless only)
page.pdf()
    .format(PaperFormat::A4)
    .path("document.pdf")
    .generate()
    .await?;

Event Handling

Handle browser events like dialogs and downloads:

use viewpoint_core::Browser;

// Handle dialogs (alerts, confirms, prompts)
page.on_dialog(|dialog| async move {
    println!("Dialog message: {}", dialog.message());
    dialog.accept(None).await
}).await;

// Handle downloads
page.on_download(|download| async move {
    download.save_as("downloads/file.zip").await
}).await;

// Handle console messages
page.on_console(|msg| async move {
    println!("[{}] {}", msg.message_type(), msg.text());
    Ok(())
}).await;

Module Organization

• browser - Browser launching and connection management
• context - Browser context (similar to incognito window) management
• page - Page navigation, content, and interaction
• network - Network interception, routing, and HAR recording
• wait - Wait system and load states
• devices - Predefined device descriptors
• error - Error types
• api - API request context for HTTP requests

Re-exports

pub use browser::Browser;

pub use browser::BrowserBuilder;

pub use browser::ConnectOverCdpBuilder;

pub use browser::NewContextBuilder;

pub use browser::UserDataDir;

pub use context::BrowserContext;

pub use context::ClearCookiesBuilder;

pub use context::ColorScheme;

pub use context::ContextEventManager;

pub use context::ContextOptions;

pub use context::ContextOptionsBuilder;

pub use context::Cookie;

pub use context::ForcedColors;

pub use context::Geolocation;

pub use context::HandlerId;

pub use context::HttpCredentials;

pub use context::IndexedDbDatabase;

pub use context::IndexedDbEntry;

pub use context::IndexedDbIndex;

pub use context::IndexedDbObjectStore;

pub use context::LocalStorageEntry;

pub use context::Permission;

pub use context::ProxyConfig;

pub use context::ReducedMotion;

pub use context::SameSite;

pub use context::SetGeolocationBuilder;

pub use context::StorageOrigin;

pub use context::StorageState;

pub use context::StorageStateBuilder;

pub use context::StorageStateOptions;

pub use context::StorageStateSource;

pub use context::Tracing;

pub use context::TracingOptions;

pub use context::ViewportSize as ContextViewportSize;

pub use error::CoreError;

pub use network::AbortError;

pub use network::ContinueBuilder;

pub use network::FetchedResponse;

pub use network::FulfillBuilder;

pub use network::NetworkEvent;

pub use network::NetworkEventListener;

pub use network::RemoteAddress;

pub use network::Request;

pub use network::RequestEvent;

pub use network::RequestFailedEvent;

pub use network::RequestFinishedEvent;

pub use network::RequestSizes;

pub use network::RequestTiming;

pub use network::ResourceType;

pub use network::Response;

pub use network::ResponseEvent;

pub use network::Route;

pub use network::RouteHandler;

pub use network::RouteHandlerRegistry;

pub use network::SecurityDetails;

pub use network::UrlMatcher;

pub use network::UrlPattern;

pub use network::WaitForRequestBuilder;

pub use network::WaitForResponseBuilder;

pub use network::WebSocket;

pub use network::WebSocketFrame;

pub use network::WebSocketManager;

pub use page::Animations;

pub use page::AriaCheckedState;

pub use page::AriaRole;

pub use page::AriaSnapshot;

pub use page::BoundingBox;

pub use page::BoxModel;

pub use page::ClipRegion;

pub use page::Clock;

pub use page::ConsoleMessage;

pub use page::ConsoleMessageLocation;

pub use page::ConsoleMessageType;

pub use page::Dialog;

pub use page::Download;

pub use page::DownloadState;

pub use page::DragAndDropBuilder;

pub use page::ElementHandle;

pub use page::EmulateMediaBuilder;

pub use page::FileChooser;

pub use page::FilePayload;

pub use page::FilterBuilder;

pub use page::Frame;

pub use page::FrameElementLocator;

pub use page::FrameLocator;

pub use page::FrameRoleLocatorBuilder;

pub use page::GotoBuilder;

pub use page::JsArg;

pub use page::JsHandle;

pub use page::Keyboard;

pub use page::Locator;

pub use page::LocatorHandlerHandle;

pub use page::LocatorHandlerOptions;

pub use page::LocatorOptions;

pub use page::Margins;

pub use page::MediaType;

pub use page::Mouse;

pub use page::NavigationResponse;

pub use page::Page;

pub use page::PageErrorInfo;

pub use page::PaperFormat;

pub use page::PdfBuilder;

pub use page::Polling;

pub use page::RoleLocatorBuilder;

pub use page::ScreenshotBuilder;

pub use page::ScreenshotFormat;

pub use page::ScriptTagBuilder;

pub use page::ScriptType;

pub use page::Selector;

pub use page::SetContentBuilder;

pub use page::SnapshotOptions;

pub use page::StyleTagBuilder;

pub use page::TextOptions;

pub use page::TimeValue;

pub use page::Touchscreen;

pub use page::Video;

pub use page::VideoOptions;

pub use page::VisionDeficiency;

pub use page::WaitForFunctionBuilder;

pub use page::WebError;

pub use wait::DocumentLoadState;

Modules

api

API testing support for making HTTP requests outside of browser context.

browser

Browser launching and management.

context

Browser Context Management

devices

Device descriptors for device emulation.

error

Core error types.

network

Network Interception and Monitoring

page

Page Management and Interaction

wait

Wait System

Structs

HeaderEntry

Response HTTP header entry.

ViewportSize

Viewport size.

Enums

DialogType

Type of JavaScript dialog.

MouseButton

Mouse button type.