Skip to main content

​
Overview

The Browser object is the root of the hierarchy and contains a reference to the browser parent process. There is usually only one instance of this class. All opened tabs, extra browser windows, and resources do not cause a new Browser process but rather create additional Tab objects. Besides starting your instance and managing tabs, you don’t actively use the Browser object frequently under normal conditions.

​
Creating a Browser instance

The Browser object is not instantiated directly using __init__. Instead, use one of these asynchronous methods: 
import zendriver as zd

# Recommended: use the start() helper function
browser = await zd.start()

# Alternative: use Browser.create()
from zendriver import Browser

browser = await Browser.create()

​
Class methods

​
create()

Create a new Browser instance. 
@classmethod
async def create(
    cls,
    config: Config | None = None,
    *,
    user_data_dir: PathLike | None = None,
    headless: bool = False,
    user_agent: str | None = None,
    browser_executable_path: PathLike | None = None,
    browser: BrowserType = "auto",
    browser_args: List[str] | None = None,
    sandbox: bool = True,
    lang: str | None = None,
    host: str | None = None,
    port: int | None = None,
    **kwargs: Any,
) -> Browser
​
config
Config
Configuration object. If provided, other parameters are ignored.
​
user_data_dir
PathLike
Directory for browser user data.
​
headless
bool
default:"False"
Launch in headless mode.
​
user_agent
str
Custom user agent string.
​
browser_executable_path
PathLike
Path to browser executable.
​
browser
BrowserType
default:"auto"
Browser type: "chrome", "brave", or "auto".
​
browser_args
List[str]
Additional browser command-line arguments.
​
sandbox
bool
default:"True"
Enable browser sandboxing.
​
lang
str
Browser language.
​
host
str
Host for connecting to existing browser.
​
port
int
Port for connecting to existing browser.

​
Properties

​
main_tab

Returns the target that was launched with the browser. 
@property
def main_tab(self) -> Tab | None
​
main_tab
Tab | None
The main tab, or None if no tabs exist.

​
tabs

Returns all current tabs (targets of type “page”). 
@property
def tabs(self) -> List[Tab]
​
tabs
List[Tab]
List of all open tabs.

​
cookies

Access the browser’s cookie jar. 
@property
def cookies(self) -> CookieJar
​
cookies
CookieJar
CookieJar instance for managing cookies.

​
stopped

Check if the browser process has stopped. 
@property
def stopped(self) -> bool
​
stopped
bool
True if the browser process is not running.

​
websocket_url

Get the WebSocket debugger URL. 
@property
def websocket_url(self) -> str
​
websocket_url
str
WebSocket URL for debugging.

​
Methods

​
get()

Navigate to a URL using the first available tab. 
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 URL in a new tab.
​
new_window
bool
default:"False"
Open URL in a new window.
​
tab
Tab
The tab that navigated to the URL.

​
start()

Start the browser process. 
async def start(self) -> Browser
​
browser
Browser
The Browser instance.

​
stop()

Stop the browser process and clean up resources. 
async def stop(self) -> None

​
wait()

Wait for a specified amount of time. 
async def wait(self, time: Union[float, int] = 1) -> Browser
​
time
float | int
default:"1"
Time to wait in seconds.
​
browser
Browser
The Browser instance.

​
sleep()

Alias for wait(). 
async def sleep(self, time: Union[float, int] = 1) -> Browser

​
grant_all_permissions()

Grant all browser permissions. 
async def grant_all_permissions(self) -> None
Grants permissions for:
  • accessibilityEvents
  • audioCapture
  • backgroundSync
  • clipboardReadWrite
  • geolocation
  • notifications
  • videoCapture
  • And many more…

​
tile_windows()

Tile browser windows across the screen. 
async def tile_windows(
    self,
    windows: List[Tab] | None = None,
    max_columns: int = 0
) -> List[List[int]]
​
windows
List[Tab]
Specific tabs to tile. If None, tiles all tabs.
​
max_columns
int
default:"0"
Maximum number of columns. If 0, calculated automatically.
​
grid
List[List[int]]
List of window positions [x, y, width, height].

​
update_targets()

Update the list of targets (tabs). 
async def update_targets(self) -> None

​
Examples

​
Basic navigation

import zendriver as zd

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

​
Open new tab

browser = await zd.start()
tab1 = await browser.get("https://example.com")
tab2 = await browser.get("https://github.com", new_tab=True)
print(f"Open tabs: {len(browser.tabs)}")

​
Manage cookies

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

# Get all cookies
cookies = await browser.cookies.get_all()

# Save cookies
await browser.cookies.save("session.dat")

# Load cookies
await browser.cookies.load("session.dat")

# Clear cookies
await browser.cookies.clear()

​
Grant permissions

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

​
Context manager

async with await zd.start() as browser:
    tab = await browser.get("https://example.com")
    # Browser automatically stops when exiting context

​
Iterate over tabs

browser = await zd.start()
await browser.get("https://example.com")
await browser.get("https://github.com", new_tab=True)

for tab in browser.tabs:
    print(f"Tab URL: {tab.url}")

​
Notes

  • Always call await browser.stop() when finished to properly close the browser
  • The Browser object manages the parent browser process
  • Multiple tabs share the same browser process
  • Use context managers for automatic cleanup
  • On Linux as root, sandbox is automatically disabled
  • start() - Helper function to create a Browser
  • Tab - Tab class for controlling individual tabs
  • Config - Configuration options

Build docs developers (and LLMs) love

Get started for freeTalk to us