Struct PageHandle 

pub struct PageHandle { /* private fields */ }

A handle to an open browser tab.

On drop the underlying page is closed automatically.

Example

use stygian_browser::{BrowserPool, BrowserConfig};
use stygian_browser::page::WaitUntil;
use std::time::Duration;

let pool = BrowserPool::new(BrowserConfig::default()).await?;
let handle = pool.acquire().await?;
let mut page = handle.browser().expect("valid browser").new_page().await?;
page.navigate("https://example.com", WaitUntil::DomContentLoaded, Duration::from_secs(30)).await?;
let html = page.content().await?;
drop(page); // closes the tab
handle.release().await;

Implementations

impl PageHandle

pub async fn navigate( &mut self, url: &str, condition: WaitUntil, nav_timeout: Duration, ) -> Result<()>

Navigate to url and wait for condition within nav_timeout.

Errors

Returns BrowserError::NavigationFailed if the navigation times out or the CDP call fails.

pub async fn wait_for_selector( &self, selector: &str, wait_timeout: Duration, ) -> Result<()>

Wait until document.querySelector(selector) is non-null (timeout).

Errors

Returns BrowserError::NavigationFailed if the selector is not found within the given timeout.

pub async fn set_resource_filter( &mut self, filter: ResourceFilter, ) -> Result<()>

Set a resource filter to block specific network request types.

Enables Fetch interception and spawns a background task that continues allowed requests and fails blocked ones with BlockedByClient. Any previously set filter task is cancelled first.

Errors

Returns a BrowserError::CdpError if the CDP call fails.

pub async fn url(&self) -> Result<String>

Return the current page URL (post-navigation, post-redirect).

Delegates to the CDP Target.getTargetInfo binding already used internally by save_cookies; no extra network request is made. Returns an empty string if the URL is not yet set (e.g. on a blank tab before the first navigation).

Errors

Returns BrowserError::CdpError if the underlying CDP call fails, or BrowserError::Timeout if it exceeds cdp_timeout.

Example

use stygian_browser::{BrowserPool, BrowserConfig};
use stygian_browser::page::WaitUntil;
use std::time::Duration;

let pool = BrowserPool::new(BrowserConfig::default()).await?;
let handle = pool.acquire().await?;
let mut page = handle.browser().expect("valid browser").new_page().await?;
page.navigate("https://example.com", WaitUntil::DomContentLoaded, Duration::from_secs(30)).await?;
let url = page.url().await?;
println!("Final URL after redirects: {url}");

pub fn status_code(&self) -> Result<Option<u16>>

Return the HTTP status code of the most recent main-frame navigation.

The status is captured from the Network.responseReceived CDP event wired up inside navigate, so it reflects the final response after any server-side redirects.

Returns None if the status was not captured — for example on file:// navigations, when navigate has not yet been called, or if the network event subscription failed.

Errors

This method is infallible; the Result wrapper is kept for API consistency with other PageHandle methods.

Example

use stygian_browser::{BrowserPool, BrowserConfig};
use stygian_browser::page::WaitUntil;
use std::time::Duration;

let pool = BrowserPool::new(BrowserConfig::default()).await?;
let handle = pool.acquire().await?;
let mut page = handle.browser().expect("valid browser").new_page().await?;
page.navigate("https://example.com", WaitUntil::DomContentLoaded, Duration::from_secs(30)).await?;
if let Some(code) = page.status_code()? {
    println!("HTTP {code}");
}

pub async fn title(&self) -> Result<String>

Return the page’s <title> text.

Errors

Returns BrowserError::ScriptExecutionFailed if the evaluation fails.

pub async fn content(&self) -> Result<String>

Return the page’s full outer HTML.

Errors

Returns BrowserError::ScriptExecutionFailed if the evaluation fails.

pub async fn eval<T: DeserializeOwned>(&self, script: &str) -> Result<T>

Evaluate arbitrary JavaScript and return the result as T.

Errors

Returns BrowserError::ScriptExecutionFailed on eval failure or deserialization error.

pub async fn save_cookies(&self) -> Result<Vec<Cookie>>

Save all cookies for the current page’s origin.

Errors

Returns BrowserError::CdpError if the CDP call fails.

pub async fn inject_cookies(&self, cookies: &[SessionCookie]) -> Result<()>

Inject cookies into the current page.

Seeds session tokens or other state without needing a full SessionSnapshot and without requiring a direct chromiumoxide dependency in calling code.

Individual cookie failures are logged as warnings and do not abort the remaining cookies.

Errors

Returns BrowserError::Timeout if a single Network.setCookie CDP call exceeds cdp_timeout.

Example

use stygian_browser::{BrowserPool, BrowserConfig};
use stygian_browser::session::SessionCookie;
use std::time::Duration;

let pool = BrowserPool::new(BrowserConfig::default()).await?;
let handle = pool.acquire().await?;
let page = handle.browser().expect("valid browser").new_page().await?;
let cookies = vec![SessionCookie {
    name: "session".to_string(),
    value: "abc123".to_string(),
    domain: ".example.com".to_string(),
    path: "/".to_string(),
    expires: -1.0,
    http_only: true,
    secure: true,
    same_site: "Lax".to_string(),
}];
page.inject_cookies(&cookies).await?;

pub async fn screenshot(&self) -> Result<Vec<u8>>

Capture a screenshot of the current page as PNG bytes.

The screenshot is full-page by default (viewport clipped to the rendered layout area). Save the returned bytes to a .png file or process them in-memory.

Errors

Returns BrowserError::CdpError if the CDP Page.captureScreenshot command fails, or BrowserError::Timeout if it exceeds cdp_timeout.

Example

use stygian_browser::{BrowserPool, BrowserConfig, WaitUntil};
use std::{time::Duration, fs};

let pool = BrowserPool::new(BrowserConfig::default()).await?;
let handle = pool.acquire().await?;
let mut page = handle.browser().expect("valid browser").new_page().await?;
page.navigate("https://example.com", WaitUntil::Selector("body".to_string()), Duration::from_secs(30)).await?;
let png = page.screenshot().await?;
fs::write("screenshot.png", &png).unwrap();

pub const fn inner(&self) -> &Page

Borrow the underlying chromiumoxide Page.

pub async fn close(self) -> Result<()>

Close this page (tab).

Called automatically on drop; explicit call avoids suppressing the error.

impl PageHandle

pub async fn verify_stealth(&self) -> Result<DiagnosticReport>

Run all built-in stealth detection checks against the current page.

Iterates crate::diagnostic::all_checks, evaluates each check’s JavaScript via CDP Runtime.evaluate, and returns an aggregate crate::diagnostic::DiagnosticReport.

Failed scripts (due to JS exceptions or deserialization errors) are recorded as failing checks and do not abort the whole run.

Errors

Returns an error only if the underlying CDP transport fails entirely. Individual check failures are captured in the report.

Example

use stygian_browser::{BrowserPool, BrowserConfig};
use stygian_browser::page::WaitUntil;
use std::time::Duration;

let pool = BrowserPool::new(BrowserConfig::default()).await?;
let handle = pool.acquire().await?;
let browser = handle.browser().expect("valid browser");
let mut page = browser.new_page().await?;
page.navigate("https://example.com", WaitUntil::DomContentLoaded, Duration::from_secs(10)).await?;

let report = page.verify_stealth().await?;
println!("Stealth: {}/{} checks passed", report.passed_count, report.checks.len());
for failure in report.failures() {
    eprintln!("  FAIL  {}: {}", failure.description, failure.details);
}

Trait Implementations

impl Drop for PageHandle

fn drop(&mut self)

Executes the destructor for this type.