Tab - Zendriver

Overview

The Tab class is the controlling mechanism for a browser target. For most users, a “target” is a tab, but it can also be an iframe, service worker, or background script. When you open a new window using browser.get(..., new_window=True), your URL opens in a new window, which is represented as a Tab. When you browse to another page, the Tab object remains the same.

Properties

url

The current URL of the tab.

@property
def url(self) -> str

closed

Whether the tab is closed.

@property
def closed(self) -> bool

target_id

The unique target ID.

@property
def target_id(self) -> str

type_

The target type (usually “page”).

@property
def type_(self) -> str

browser

The parent Browser instance.

@property
def browser(self) -> Browser | None

inspector_url

The DevTools inspector URL for this tab.

@property
def inspector_url(self) -> str

get()

Navigate to a URL.

async def get(
    self,
    url: str = "about:blank",
    new_tab: bool = False,
    new_window: bool = False
) -> Tab

url

str

default:"about:blank"

The URL to navigate to.

new_tab

bool

default:"False"

Open in a new tab.

new_window

bool

default:"False"

Open in a new window.

tab

Tab

The tab that navigated (or the new tab if created).

back()

Navigate back in history.

async def back(self) -> None

forward()

Navigate forward in history.

async def forward(self) -> None

reload()

Reload the page.

async def reload(
    self,
    ignore_cache: Optional[bool] = True,
    script_to_evaluate_on_load: Optional[str] = None,
) -> None

ignore_cache

bool

default:"True"

Whether to ignore cache and re-download resources.

script_to_evaluate_on_load

str

JavaScript to execute on page load.

Finding elements

find()

Find a single element by text content.

async def find(
    self,
    text: str,
    best_match: bool = True,
    return_enclosing_element: bool = True,
    timeout: Union[int, float] = 10,
) -> Element

text

str

Text to search for (including script contents).

best_match

bool

default:"True"

When True, returns the element with the most similar text length. When False, returns the first match.

return_enclosing_element

bool

default:"True"

Return the containing element instead of the text node.

timeout

float

default:"10"

Timeout in seconds.

element

Element

The found element.

find_all()

Find multiple elements by text.

async def find_all(
    self,
    text: str,
    timeout: Union[int, float] = 10,
) -> List[Element]

text

str

Text to search for.

timeout

float

default:"10"

Timeout in seconds.

elements

List[Element]

List of matching elements.

select()

Find a single element by CSS selector.

async def select(
    self,
    selector: str,
    timeout: Union[int, float] = 10,
) -> Element

selector

str

CSS selector (e.g., a[href], button[class*=close]).

timeout

float

default:"10"

Timeout in seconds.

element

Element

The found element.

select_all()

Find multiple elements by CSS selector.

async def select_all(
    self,
    selector: str,
    timeout: Union[int, float] = 10,
    include_frames: bool = False,
) -> List[Element]

selector

str

CSS selector.

timeout

float

default:"10"

Timeout in seconds.

include_frames

bool

default:"False"

Include results from iframes.

elements

List[Element]

List of matching elements.

xpath()

Find elements by XPath.

async def xpath(
    self,
    xpath: str,
    timeout: float = 2.5
) -> List[Element]

xpath

str

XPath query string.

timeout

float

default:"2.5"

Timeout in seconds.

elements

List[Element]

List of matching elements (empty list if none found).

query_selector()

Equivalent to JavaScript’s document.querySelector().

async def query_selector(
    self,
    selector: str,
    _node: Optional[Union[cdp.dom.Node, Element]] = None,
) -> Element | None

query_selector_all()

Equivalent to JavaScript’s document.querySelectorAll().

async def query_selector_all(
    self,
    selector: str,
    _node: cdp.dom.Node | Element | None = None,
) -> List[Element]

wait_for()

Wait for an element to appear.

async def wait_for(
    self,
    selector: str | None = None,
    text: str | None = None,
    timeout: int | float = 10,
) -> Element

selector

str

CSS selector to wait for.

text

str

Text content to wait for.

timeout

float

default:"10"

Timeout in seconds.

element

Element

The element once it appears.

JavaScript execution

evaluate()

Execute JavaScript in the page context.

async def evaluate(
    self,
    expression: str,
    await_promise: bool = False,
    return_by_value: bool = True
) -> Any

expression

str

JavaScript code to execute.

await_promise

bool

default:"False"

Wait for promises to resolve.

return_by_value

bool

default:"True"

Return the value directly instead of a RemoteObject.

result

Any

The result of the JavaScript execution.

js_dumps()

Dump a JavaScript object with its properties and values.

async def js_dumps(
    self,
    obj_name: str,
    return_by_value: Optional[bool] = True
) -> Any

obj_name

str

Name of the JavaScript object to dump (e.g., "window").

return_by_value

bool

default:"True"

Return as a dict or CDP objects.

result

Any

The serialized object.

Page interaction

scroll_down()

Scroll down the page.

async def scroll_down(
    self,
    amount: int = 25,
    speed: int = 800
) -> None

amount

int

default:"25"

Percentage to scroll (25 = quarter page, 100 = full page).

speed

int

default:"800"

Scroll speed in pixels per second.

scroll_up()

Scroll up the page.

async def scroll_up(
    self,
    amount: int = 25,
    speed: int = 800
) -> None

amount

int

default:"25"

Percentage to scroll.

speed

int

default:"800"

Scroll speed in pixels per second.

get_content()

Get the page HTML source.

async def get_content(self) -> str

html

str

The page HTML.

Window management

maximize()

Maximize the window.

async def maximize(self) -> None

minimize()

Minimize the window.

async def minimize(self) -> None

fullscreen()

Set window to fullscreen.

async def fullscreen(self) -> None

set_window_size()

Set window size and position.

async def set_window_size(
    self,
    left: int = 0,
    top: int = 0,
    width: int = 1280,
    height: int = 1024
) -> None

left

int

default:"0"

Pixels from left edge.

top

int

default:"0"

Pixels from top edge.

width

int

default:"1280"

Window width in pixels.

height

int

default:"1024"

Window height in pixels.

get_window()

Get window ID and bounds.

async def get_window(self) -> Tuple[cdp.browser.WindowID, cdp.browser.Bounds]

result

Tuple

Tuple of (WindowID, Bounds).

activate()

Activate (focus) this tab.

async def activate(self) -> None

bring_to_front()

Alias for activate().

async def bring_to_front(self) -> None

close()

Close the tab.

async def close(self) -> None

Screenshots and downloads

screenshot_b64()

Capture a screenshot as base64.

async def screenshot_b64(
    self,
    format: str = "jpeg",
    full_page: bool = False,
) -> str

format

str

default:"jpeg"

Image format: "jpeg" or "png".

full_page

bool

default:"False"

Capture entire page instead of viewport.

data

str

Base64-encoded image data.

save_screenshot()

Save a screenshot to file.

async def save_screenshot(
    self,
    filename: Optional[PathLike] = "auto",
    format: str = "jpeg",
    full_page: bool = False,
) -> str

filename

PathLike

default:"auto"

File path. If “auto”, generates filename from URL.

format

str

default:"jpeg"

Image format: "jpeg" or "png".

full_page

bool

default:"False"

Capture entire page.

path

str

Path to saved screenshot.

download_file()

Download a file from a URL.

async def download_file(
    self,
    url: str,
    filename: Optional[PathLike] = None
) -> None

url

str

URL of the file to download.

filename

PathLike

Filename for the downloaded file. If None, uses URL filename.

save_snapshot()

Save a page snapshot in MHTML format.

async def save_snapshot(
    self,
    filename: str = "snapshot.mhtml"
) -> None

filename

str

default:"snapshot.mhtml"

Path to save the snapshot.

Network expectations

expect_request()

Create a request expectation for a URL pattern.

def expect_request(
    self,
    url_pattern: Union[str, re.Pattern[str]]
) -> RequestExpectation

url_pattern

str | Pattern

URL pattern to match.

expectation

RequestExpectation

RequestExpectation instance.

expect_response()

Create a response expectation for a URL pattern.

def expect_response(
    self,
    url_pattern: Union[str, re.Pattern[str]]
) -> ResponseExpectation

url_pattern

str | Pattern

URL pattern to match.

expectation

ResponseExpectation

ResponseExpectation instance.

expect_download()

Create a download expectation.

def expect_download(self) -> DownloadExpectation

expectation

DownloadExpectation

DownloadExpectation instance.

intercept()

Intercept network requests.

def intercept(
    self,
    url_pattern: str,
    request_stage: RequestStage,
    resource_type: ResourceType,
) -> BaseFetchInterception

url_pattern

str

URL pattern to match.

request_stage

RequestStage

Stage to intercept (e.g., request, response).

resource_type

ResourceType

Resource type (e.g., Document, Script, Image).

interception

BaseFetchInterception

Interception instance.

Utilities

wait_for_ready_state()

Wait for the page to reach a ready state.

async def wait_for_ready_state(
    self,
    until: Literal["loading", "interactive", "complete"] = "interactive",
    timeout: int = 10,
) -> bool

until

str

default:"interactive"

Ready state to wait for: "loading", "interactive", or "complete".

timeout

int

default:"10"

Timeout in seconds.

success

bool

True if ready state reached.

open_external_inspector()

Open the DevTools inspector in your system browser.

async def open_external_inspector(self) -> None

inspector_open()

Open the inspector in a new browser window.

def inspector_open(self) -> None

send()

Send a CDP command.

async def send(self, command) -> Any

command

CDP Command

Chrome DevTools Protocol command.

result

Any

Command result.

Examples

import zendriver as zd

browser = await zd.start()
tab = await browser.get("https://example.com")

# Find and click a button
button = await tab.find("Click me")
await button.click()

# Select element by CSS
link = await tab.select("a.important-link")
await link.click()

Execute JavaScript

tab = await browser.get("https://example.com")

# Simple evaluation
title = await tab.evaluate("document.title")
print(f"Page title: {title}")

# Dump window object
window_props = await tab.js_dumps("window")
print(window_props)

Screenshots

tab = await browser.get("https://example.com")

# Save viewport screenshot
await tab.save_screenshot("page.png", format="png")

# Save full page screenshot
await tab.save_screenshot("fullpage.jpg", full_page=True)

# Get base64 screenshot
data = await tab.screenshot_b64()

Wait for elements

tab = await browser.get("https://example.com")

# Wait for selector
element = await tab.wait_for(selector=".dynamic-content")

# Wait for text
element = await tab.wait_for(text="Loading complete")

Window management

tab = await browser.get("https://example.com")

# Maximize window
await tab.maximize()

# Set custom size
await tab.set_window_size(left=100, top=100, width=1920, height=1080)

# Scroll page
await tab.scroll_down(amount=50, speed=1000)

Notes

Tab objects persist across page navigations
Always use await when calling Tab methods
Use await tab to update references and let the script “breathe”
For text searches, use find() with best_match=True for better results
Screenshots work best after ensuring the page is fully loaded

Browser - Parent Browser class
Element - Element class for DOM manipulation
start() - Start a browser session

Core API

Input & Interaction

Advanced

​Overview

​Properties

​url

​closed

​target_id

​type_

​browser

​inspector_url

​Navigation methods

​get()

​back()

​forward()

​reload()

​Finding elements

​find()

​find_all()

​select()

​select_all()

​xpath()

​query_selector()

​query_selector_all()

​wait_for()

​JavaScript execution

​evaluate()

​js_dumps()

​Page interaction

​scroll_down()

​scroll_up()

​get_content()

​Window management

​maximize()

​minimize()

​fullscreen()

​set_window_size()

​get_window()

​activate()

​bring_to_front()

​close()

​Screenshots and downloads

​screenshot_b64()

​save_screenshot()

​download_file()

​save_snapshot()

​Network expectations

​expect_request()

​expect_response()

​expect_download()

​intercept()

​Utilities

​wait_for_ready_state()

​open_external_inspector()

​inspector_open()

​send()

​Examples

​Basic navigation and element interaction

​Execute JavaScript

​Screenshots

​Wait for elements

​Window management

​Notes

​Related

Build docs developers (and LLMs) love

Overview

Properties

url

closed

target_id

type_

browser

inspector_url

Navigation methods

get()

back()

forward()

reload()

Finding elements

find()

find_all()

select()

select_all()

xpath()

query_selector()

query_selector_all()

wait_for()

JavaScript execution

evaluate()

js_dumps()

Page interaction

scroll_down()

scroll_up()

get_content()

Window management

maximize()

minimize()

fullscreen()

set_window_size()

get_window()

activate()

bring_to_front()

close()

Screenshots and downloads

screenshot_b64()

save_screenshot()

download_file()

save_snapshot()

Network expectations

expect_request()

expect_response()

expect_download()

intercept()

Utilities

wait_for_ready_state()

open_external_inspector()

inspector_open()

send()

Examples

Basic navigation and element interaction

Execute JavaScript

Screenshots

Wait for elements

Window management

Notes

Related