Zendriver

https://zendriver.dev/
Admin
Zendriver is a blazing fast, async-first, undetectable web scraping and automation framework using...
Tokens:1,022,436
Snippets:6,484
Trust Score:4.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Initial Setup for Infinite Scrolling

Source: https://zendriver.dev/tutorials/infinite-scrolling

This snippet shows the basic setup to start a browser and navigate to a page. It attempts to select elements before they are loaded, resulting in an empty list.

```python
import asyncio

import zendriver as zd


async def main() -> None:
    browser = await zd.start()
    page = await browser.get(
        "https://cdpdriver.github.io/examples/scrollable-cards.html",
    )

    # Not yet loaded, so empty
    card_container = await page.select("#card-container")
    cards = card_container.children
    print(cards)  # []

    await browser.stop()


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Initial Zendriver Setup

Source: https://zendriver.dev/tutorials/account-creation

Sets up the Zendriver browser instance and navigates to the target login/signup page. This is the starting point for most Zendriver automation scripts.

```python
import asyncio

import zendriver as zd


async def main() -> None:
    browser = await zd.start()
    page = await browser.get(
        "https://cdpdriver.github.io/examples/login-page.html",
    )

    # TODO: Sign-up and login

    await browser.stop()


if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Basic Zendriver Usage: Visit URL and Save Screenshot

Source: https://zendriver.dev/

Example of starting Zendriver, navigating to a URL, and saving a screenshot. Requires asyncio.

```python
import asyncio

import zendriver as zd


async def main():
    browser = await zd.start()
    page = await browser.get("https://www.browserscan.net/bot-detection")
    await page.save_screenshot("browserscan.png")
    await browser.stop()


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Initial Zendriver Script Setup

Source: https://zendriver.dev/tutorials/api-responses

Sets up a basic Zendriver script to launch a browser and navigate to a target page. This serves as the starting point before implementing API response handling.

```python
import asyncio

import zendriver as zd


async def main() -> None:
    browser = await zd.start()

    # TODO: Read the API response
    page = await browser.get(
        "https://cdpdriver.github.io/examples/api-request.html",
    )

    await browser.stop()


if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Launch Browser with Default Configuration

Source: https://zendriver.dev/reference/core/util

Use this function to launch a browser instance with default settings. It can be called with no parameters for quick setup. Ensure to use `await start()`.

```python
async def start(
    config: Optional[Config] = None,
    *,
    user_data_dir: Optional[PathLike] = None,
    headless: Optional[bool] = False,
    browser_executable_path: Optional[PathLike] = None,
    browser: BrowserType = "auto",
    browser_args: Optional[List[str]] = None,
    sandbox: Optional[bool] = True,
    lang: Optional[str] = None,
    host: Optional[str] = None,
    port: Optional[int] = None,
    expert: Optional[bool] = None,
    user_agent: Optional[str] = None,
    **kwargs: Any,
) -> Browser:
    """
    helper function to launch a browser. it accepts several keyword parameters.
    conveniently, you can just call it bare (no parameters) to quickly launch an instance
    with best practice defaults.
    note: this should be called ```await start()```

    :param user_data_dir:

    :param headless:

    :param browser_executable_path:

    :param browser_args: ["--some-chromeparam=somevalue", "some-other-param=someval"]

    :param sandbox: default True, but when set to False it adds --no-sandbox to the params, also
    when using linux under a root user, it adds False automatically (else chrome won't start

    :param lang: language string

    :param port: if you connect to an existing debuggable session, you can specify the port here
                 if both host and port are provided, zendriver will not start a local chrome browser!

    :param host: if you connect to an existing debuggable session, you can specify the host here
                 if both host and port are provided, zendriver will not start a local chrome browser!

    :param expert:  when set to True, enabled "expert" mode.
                    This conveys, the inclusion of parameters: --disable-web-security ----disable-site-isolation-trials,
                    as well as some scripts and patching useful for debugging (for example, ensuring shadow-root is always in "open" mode)

    :param user_agent: if set, this will be used as the user agent for the browser.

    :return:
    """
    if not config:
        config = Config(
            user_data_dir,
            headless,
            browser_executable_path,
            browser,
            browser_args,
            sandbox,
            lang,
            host=host,
            port=port,
            expert=expert,
            user_agent=user_agent,
            **kwargs,
        )
    from .browser import Browser

    return await Browser.create(config)

```

--------------------------------

### start()

Source: https://zendriver.dev/reference/cdp/profiler

Starts the profiler. No parameters or return values are specified in the documentation.

```APIDOC
## start()

### Description
Starts the profiler.
```

--------------------------------

### Basic Zendriver Usage

Source: https://zendriver.dev/quickstart

Demonstrates basic browser automation: starting the browser, navigating to a URL, getting page content, taking a screenshot, and closing the browser.

```python
import asyncio
import zendriver as zd

async def main():
    browser = await zd.start()
    page = await browser.get('https://example.com')

    # get HTML content of the page as a string
    content = await page.get_content()

    # save a screenshot
    await page.save_screenshot()

    # close the browser window
    await browser.stop()


if __name__ == '__main__':
    asyncio.run(main())

```

--------------------------------

### launch

Source: https://zendriver.dev/reference/cdp/pwa

Launches the installed web app. Optionally, a URL can be provided to launch within the same web app instead of the default start URL. Returns a Target.TargetID.

```APIDOC
## PWA.launch

### Description
Launches the installed web app. Optionally, a URL can be provided to launch within the same web app instead of the default start URL. Returns a Target.TargetID.

### Method
POST

### Endpoint
/session/{session_id}/chromium/send

### Parameters
#### Request Body
- **manifestId** (str) - Required - The identity of the manifest to launch.
- **url** (Optional[str]) - Optional - The URL to launch within the web app.

### Request Example
```json
{
  "method": "PWA.launch",
  "params": {
    "manifestId": "isolated-app://<SignedWebBundleId>",
    "url": "https://example.com/specific-page"
  }
}
```

### Response
#### Success Response (200)
- **targetId** (TargetID) - ID of the tab target created as a result.

#### Response Example
```json
{
  "result": {
    "targetId": "<target_id>"
  },
  "id": "<command_id>"
}
```
```

--------------------------------

### Starting a Browser Instance

Source: https://zendriver.dev/reference/core/browser

This snippet shows the process of starting a browser instance, including setting the executable path, adding arguments, and handling connection attempts. It also demonstrates error handling for failed connections.

```python
if getattr(self.config, "_extensions", None):
            self.config.add_argument(
                "--load-extension=%s" % ",".join(str(_) for _ in self.config._extensions)
            )  # noqa

        if self.config.lang is not None:
            self.config.add_argument(f"--lang={self.config.lang}")

        exe = self.config.browser_executable_path
        params = self.config()
        params.append("about:blank")

        logger.info(
            "starting\n\texecutable :%s\n\narguments:\n%s", exe, "\n\t".join(params)
        )
        if not connect_existing:
            self._process = util._start_process(exe, params, is_posix)
            self._process_pid = self._process.pid

        self._http = HTTPApi((self.config.host, self.config.port))
        util.get_registered_instances().add(self)
        await asyncio.sleep(self.config.browser_connection_timeout)
        for _ in range(self.config.browser_connection_max_tries):
            if await self.test_connection():
                break

            await asyncio.sleep(self.config.browser_connection_timeout)

        if not self.info:
            if self._process is not None:
                stderr = await util._read_process_stderr(self._process)
                logger.info(
                    "Browser stderr: %s", stderr if stderr else "No output from browser"
                )

            await self.stop()
            raise Exception(
                (
                    """
                ---------------------
                Failed to connect to browser
                ---------------------
                One of the causes could be when you are running as root.
                In that case you need to pass no_sandbox=True
                """
                )
            )

        self.connection = Connection(self.info.webSocketDebuggerUrl, _owner=self)

        if self.config.autodiscover_targets:
            logger.info("enabling autodiscover targets")

            self.connection.handlers[cdp.target.TargetInfoChanged] = [
                self._handle_target_update
            ]
            self.connection.handlers[cdp.target.TargetCreated] = [
                self._handle_target_update
            ]
            self.connection.handlers[cdp.target.TargetDestroyed] = [
                self._handle_target_update
            ]
            self.connection.handlers[cdp.target.TargetCrashed] = [
                self._handle_target_update
            ]
            await self.connection.send(cdp.target.set_discover_targets(discover=True))
        await self.update_targets()
        return self
```

--------------------------------

### start_desktop_mirroring

Source: https://zendriver.dev/reference/cdp/cast

Starts mirroring the desktop to the sink.

```APIDOC
## Cast.startDesktopMirroring

### Description
Starts mirroring the desktop to the sink.

### Method
POST

### Endpoint
/json

### Parameters
#### Query Parameters
- **sink_name** (str) - Required - The name of the sink to mirror to.

### Request Example
```json
{
  "method": "Cast.startDesktopMirroring",
  "params": {
    "sinkName": "mySink"
  }
}
```

### Response
(No specific response schema documented)
```

--------------------------------

### start(config=None, *, user_data_dir=None, headless=False, browser_executable_path=None, browser='auto', browser_args=None, sandbox=True, lang=None, host=None, port=None, expert=None, user_agent=None, **kwargs)

Source: https://zendriver.dev/reference/core/util

A helper function to launch a browser instance. It can be called with no parameters for default settings or with various keyword arguments to customize the browser launch. Note: this function should be called using `await start()`.

```APIDOC
## start(config=None, *, user_data_dir=None, headless=False, browser_executable_path=None, browser='auto', browser_args=None, sandbox=True, lang=None, host=None, port=None, expert=None, user_agent=None, **kwargs)

### Description
Helper function to launch a browser. It accepts several keyword parameters. Conveniently, you can call it bare (no parameters) to quickly launch an instance with best-practice defaults. Note: this should be called `await start()`.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- `user_data_dir` (Optional[PathLike]): Path to the user data directory.
- `headless` (Optional[bool]): Whether to run the browser in headless mode. Defaults to `False`.
- `browser_executable_path` (Optional[PathLike]): Path to the browser executable.
- `browser_args` (Optional[List[str]]): List of arguments to pass to the browser. Example: `["--some-chromeparam=somevalue", "some-other-param=someval"]`.
- `sandbox` (Optional[bool]): Whether to enable the sandbox. Defaults to `True`. If set to `False`, `--no-sandbox` is added to browser arguments. Automatically set to `False` when running on Linux as root user.
- `lang` (Optional[str]): Language string for the browser locale.
- `port` (Optional[int]): Port to connect to an existing debuggable session. If both `host` and `port` are provided, Zendriver will not start a local Chrome browser.
- `host` (Optional[str]): Host to connect to an existing debuggable session. If both `host` and `port` are provided, Zendriver will not start a local Chrome browser.
- `expert` (Optional[bool]): Enables "expert" mode when set to `True`. This includes parameters like `--disable-web-security`, `--disable-site-isolation-trials`, and useful debugging scripts.
- `user_agent` (Optional[str]): User agent string to be used for the browser.

### Returns
- `Browser`: An instance of the Browser class.

### Example
```python
import asyncio
from zendriver import start

async def main():
    browser = await start()
    # ... use the browser instance ...
    await browser.close()

asyncio.run(main())
```
```

--------------------------------

### install

Source: https://zendriver.dev/reference/cdp/pwa

Installs the given manifest identity, optionally using the given installUrlOrBundleUrl. Supports file installation and dev proxy installation modes.

```APIDOC
## PWA.install

### Description
Installs the given manifest identity, optionally using the given installUrlOrBundleUrl. Supports file installation and dev proxy installation modes.

### Method
POST

### Endpoint
/session/{session_id}/chromium/send

### Parameters
#### Request Body
- **manifestId** (str) - Required - The identity of the manifest to install.
- **installUrlOrBundleUrl** (Optional[str]) - Optional - The location of the app or bundle overriding the one derived from the manifestId. Can be a file:// or http(s):// URL for a signed web bundle, or http(s):// for a dev mode IWA.

### Request Example
```json
{
  "method": "PWA.install",
  "params": {
    "manifestId": "isolated-app://<SignedWebBundleId>",
    "installUrlOrBundleUrl": "file:///path/to/your/app.swbn"
  }
}
```

### Response
#### Success Response (200)
(No specific response fields documented, typically an empty JSON object on success for CDP commands)

#### Response Example
```json
{
  "result": {},
  "id": "<command_id>"
}
```
```

--------------------------------

### DownloadWillBegin Event Structure

Source: https://zendriver.dev/reference/cdp/browser

Represents the Browser.downloadWillBegin event, fired when a download is about to start. Includes frame ID, download GUID, URL, and suggested filename.

```python
@event_class("Browser.downloadWillBegin")
@dataclass
class DownloadWillBegin:
    """
    **EXPERIMENTAL**

    Fired when page is about to start a download.
    """

    #: Id of the frame that caused the download to begin.
    frame_id: page.FrameId
    #: Global unique identifier of the download.
    guid: str
    #: URL of the resource being downloaded.
    url: str
    #: Suggested file name of the resource (the actual name of the file saved on disk may differ).
    suggested_filename: str

    @classmethod
    def from_json(cls, json: T_JSON_DICT) -> DownloadWillBegin:
        return cls(
            frame_id=page.FrameId.from_json(json["frameId"]),
            guid=str(json["guid"]),
            url=str(json["url"]),
            suggested_filename=str(json["suggestedFilename"]),
        )
```

--------------------------------

### Start Desktop Mirroring

Source: https://zendriver.dev/reference/cdp/cast

Initiates mirroring of the desktop to the specified sink.

```python
def start_desktop_mirroring(
    sink_name: str,
) -> typing.Generator[T_JSON_DICT, T_JSON_DICT, None]:
    """
    Starts mirroring the desktop to the sink.

    :param sink_name:
    """
    params: T_JSON_DICT = dict()
    params["sinkName"] = sink_name
    cmd_dict: T_JSON_DICT = {
        "method": "Cast.startDesktopMirroring",
        "params": params,
    }
    json = yield cmd_dict
```

--------------------------------

### Start Browser Connection

Source: https://zendriver.dev/reference/core/browser

Initiates the browser connection and starts discovering targets. This is typically the first step in establishing communication with a browser instance.

```python
await self.connection.send(cdp.target.set_discover_targets(discover=True))
    await self.update_targets()
    return self
```

--------------------------------

### start_tab_mirroring

Source: https://zendriver.dev/reference/cdp/cast

Starts mirroring the tab to the sink.

```APIDOC
## Cast.startTabMirroring

### Description
Starts mirroring the tab to the sink.

### Method
POST

### Endpoint
/json

### Parameters
#### Query Parameters
- **sink_name** (str) - Required - The name of the sink to mirror to.

### Request Example
```json
{
  "method": "Cast.startTabMirroring",
  "params": {
    "sinkName": "mySink"
  }
}
```

### Response
(No specific response schema documented)
```

--------------------------------

### Launch a PWA

Source: https://zendriver.dev/reference/cdp/pwa

Launches an installed PWA. Optionally, a specific URL within the PWA can be provided to launch instead of the default start URL. Returns the Target ID of the created tab.

```python
def launch(
    manifest_id: str, url: typing.Optional[str] = None
) -> typing.Generator[T_JSON_DICT, T_JSON_DICT, target.TargetID]:
    """
    Launches the installed web app, or an url in the same web app instead of the
    default start url if it is provided. Returns a page Target.TargetID which
    can be used to attach to via Target.attachToTarget or similar APIs.

    :param manifest_id:
    :param url: *(Optional)*
    :returns: ID of the tab target created as a result.
    """
    params: T_JSON_DICT = dict()
    params["manifestId"] = manifest_id
    if url is not None:
        params["url"] = url
    cmd_dict: T_JSON_DICT = {
        "method": "PWA.launch",
        "params": params,
    }
    json = yield cmd_dict
    return target.TargetID.from_json(json["targetId"])
```

--------------------------------

### Install Zendriver using pip

Source: https://zendriver.dev/

Install the Zendriver package using pip or other package managers.

```bash
pip install zendriver
# or uv add zendriver, poetry add zendriver, etc.

```

--------------------------------

### Start Profiler

Source: https://zendriver.dev/reference/cdp/profiler

Starts the profiler. This function initiates the profiling process.

```python
def start() -> typing.Generator[T_JSON_DICT, T_JSON_DICT, None]:
    cmd_dict: T_JSON_DICT = {
        "method": "Profiler.start",
    }
    json = yield cmd_dict

```

--------------------------------

### start_screencast

Source: https://zendriver.dev/reference/cdp/page

Starts sending each frame using the `screencastFrame` event. This method is marked as EXPERIMENTAL.

```APIDOC
## start_screencast(format_=None, quality=None, max_width=None, max_height=None, every_nth_frame=None)

### Description
Starts sending each frame using the `screencastFrame` event.

### Parameters
#### Path Parameters
* None

#### Query Parameters
* None

#### Request Body
* **format_** (Optional[str]) - Optional - Image compression format.
* **quality** (Optional[int]) - Optional - Compression quality from range [0..100].
* **max_width** (Optional[int]) - Optional - Maximum screenshot width.
* **max_height** (Optional[int]) - Optional - Maximum screenshot height.
* **every_nth_frame** (Optional[int]) - Optional - Send every n-th frame.

### Request Example
```json
{
  "method": "Page.startScreencast",
  "params": {
    "format": "jpeg",
    "quality": 80,
    "maxWidth": 1920,
    "maxHeight": 1080,
    "everyNthFrame": 2
  }
}
```

### Response
#### Success Response (200)
* The response structure is not explicitly defined in the source.

#### Response Example
* No example provided in the source.
```

--------------------------------

### Example Script for Image Upload

Source: https://zendriver.dev/quickstart

An example script demonstrating interaction with a JavaScript-heavy site, potentially faster than the JavaScript can present elements.

```python
import asyncio
from pathlib import Path
import zendriver as zd

# interesting, this is a typical site which runs completely on javascript, and that causes
# this script to be faster than the js can present the elements. This may be one of the downsides

```

--------------------------------

### Start Screen Casting

Source: https://zendriver.dev/reference/cdp/page

Starts sending frames using the `screencastFrame` event. This is useful for capturing video of the page. Configure image format, quality, dimensions, and frame interval.

```python
import typing

T_JSON_DICT = typing.Dict[str, typing.Any]

def start_screencast(
    format_: typing.Optional[str] = None,
    quality: typing.Optional[int] = None,
    max_width: typing.Optional[int] = None,
    max_height: typing.Optional[int] = None,
    every_nth_frame: typing.Optional[int] = None,
) -> typing.Generator[T_JSON_DICT, T_JSON_DICT, None]:
    """
    Starts sending each frame using the ``screencastFrame`` event.

    **EXPERIMENTAL**

    :param format_: *(Optional)* Image compression format.
    :param quality: *(Optional)* Compression quality from range [0..100].
    :param max_width: *(Optional)* Maximum screenshot width.
    :param max_height: *(Optional)* Maximum screenshot height.
    :param every_nth_frame: *(Optional)* Send every n-th frame.
    """
    params: T_JSON_DICT = dict()
    if format_ is not None:
        params["format"] = format_
    if quality is not None:
        params["quality"] = quality
    if max_width is not None:
        params["maxWidth"] = max_width
    if max_height is not None:
        params["maxHeight"] = max_height
    if every_nth_frame is not None:
        params["everyNthFrame"] = every_nth_frame
    cmd_dict: T_JSON_DICT = {
        "method": "Page.startScreencast",
        "params": params,
    }
    json = yield cmd_dict

```

--------------------------------

### Zendriver Start with Custom Options

Source: https://zendriver.dev/quickstart

Starts the Zendriver browser with custom options like headless mode, user data directory, browser executable path, arguments, and language.

```python
import zendriver as zd

browser = await zd.start(
    headless=False,
    user_data_dir="/path/to/existing/profile",  # by specifying it, it won't be automatically cleaned up when finished
    browser_executable_path="/path/to/some/other/browser",
    browser_args=['--some-browser-arg=true', '--some-other-option'],
    lang="en-US"   # this could set iso-language-code in navigator, not recommended to change
)
tab = await browser.get('https://somewebsite.com')

```

--------------------------------

### Start Native Memory Sampling

Source: https://zendriver.dev/reference/cdp/memory

Starts collecting a native memory profile. Specify the average interval between samples or disable randomization.

```python
def start_sampling(
    sampling_interval: typing.Optional[int] = None,
    suppress_randomness: typing.Optional[bool] = None,
) -> typing.Generator[T_JSON_DICT, T_JSON_DICT, None]:
    """
    Start collecting native memory profile.

    :param sampling_interval: *(Optional)* Average number of bytes between samples.
    :param suppress_randomness: *(Optional)* Do not randomize intervals between samples.
    """
    params: T_JSON_DICT = dict()
    if sampling_interval is not None:
        params["samplingInterval"] = sampling_interval
    if suppress_randomness is not None:
        params["suppressRandomness"] = suppress_randomness
    cmd_dict: T_JSON_DICT = {
        "method": "Memory.startSampling",
        "params": params,
    }
    json = yield cmd_dict

```

--------------------------------

### Load Unpacked Extension

Source: https://zendriver.dev/reference/cdp/extensions

Installs an unpacked extension from a given file path. Can optionally enable the extension in incognito mode. Returns the extension ID upon successful installation. Requires specific connection flags.

```python
def load_unpacked(
    path: str, enable_in_incognito: typing.Optional[bool] = None
) -> typing.Generator[T_JSON_DICT, T_JSON_DICT, str]:
    """
    Installs an unpacked extension from the filesystem similar to
    --load-extension CLI flags. Returns extension ID once the extension
    has been installed. Available if the client is connected using the
    --remote-debugging-pipe flag and the --enable-unsafe-extension-debugging
    flag is set.

    :param path: Absolute file path.
    :param enable_in_incognito: *(Optional)* Enable the extension in incognito
    :returns: Extension id.
    """
    params: T_JSON_DICT = dict()
    params["path"] = path
    if enable_in_incognito is not None:
        params["enableInIncognito"] = enable_in_incognito
    cmd_dict: T_JSON_DICT = {
        "method": "Extensions.loadUnpacked",
        "params": params,
    }
    json = yield cmd_dict
    return str(json["id"])

```

--------------------------------

### Start Tab Mirroring

Source: https://zendriver.dev/reference/cdp/cast

Initiates mirroring of the current tab to the specified sink.

```python
def start_tab_mirroring(
    sink_name: str,
) -> typing.Generator[T_JSON_DICT, T_JSON_DICT, None]:
    """
    Starts mirroring the tab to the sink.

    :param sink_name:
    """
    params: T_JSON_DICT = dict()
    params["sinkName"] = sink_name
    cmd_dict: T_JSON_DICT = {
        "method": "Cast.startTabMirroring",
        "params": params,
    }
    json = yield cmd_dict
```

--------------------------------

### Get Installability Errors (Experimental)

Source: https://zendriver.dev/reference/cdp/page

Retrieves experimental data related to the installability of a web application. Use this to diagnose potential issues preventing installation.

```python
def get_installability_errors() -> (
    typing.Generator[T_JSON_DICT, T_JSON_DICT, typing.List[InstallabilityError]]
):
    """

    **EXPERIMENTAL**

    :returns:
    """
    cmd_dict: T_JSON_DICT = {
        "method": "Page.getInstallabilityErrors",
    }
    json = yield cmd_dict
    return [InstallabilityError.from_json(i) for i in json["installabilityErrors"]]
```

--------------------------------

### DownloadWillBegin Event

Source: https://zendriver.dev/reference/cdp/browser

Represents the Browser.downloadWillBegin event, fired when a page is about to start a download. It includes details about the frame, download GUID, URL, and suggested filename.

```APIDOC
## Browser.downloadWillBegin Event

### Description
Fired when page is about to start a download. This event provides information necessary to track and manage downloads initiated by a web page.

### Event Details
- **frame_id** (page.FrameId) - Required - The ID of the frame that initiated the download.
- **guid** (str) - Required - A globally unique identifier for the download.
- **url** (str) - Required - The URL of the resource being downloaded.
- **suggested_filename** (str) - Required - The suggested filename for the downloaded resource.

### Method
Event

### Parameters
#### Event Parameters
- **frame_id** (page.FrameId) - Required - Id of the frame that caused the download to begin.
- **guid** (str) - Required - Global unique identifier of the download.
- **url** (str) - Required - URL of the resource being downloaded.
- **suggested_filename** (str) - Required - Suggested file name of the resource (the actual name of the file saved on disk may differ).

### Response Example
```json
{
  "frameId": "frame-id-value",
  "guid": "download-guid-123",
  "url": "http://example.com/file.zip",
  "suggestedFilename": "file.zip"
}
```
```

--------------------------------

### Start Browser Instance

Source: https://zendriver.dev/reference/core/browser

Launches a new browser instance. It handles configuration, executable path validation, and connection attempts. Use `Browser.create()` to instantiate.

```python
async def start(self) -> Browser:
    """launches the actual browser"""
    if not self:
        raise ValueError(
            "Cannot be called as a class method. Use `await Browser.create()` to create a new instance"
        )

    if self._process or self._process_pid:
        if self._process and self._process.returncode is not None:
            return await self.create(config=self.config)
        warnings.warn("ignored! this call has no effect when already running.")
        return self

    connect_existing = False
    if self.config.host is not None and self.config.port is not None:
        connect_existing = True
    else:
        self.config.host = "127.0.0.1"
        self.config.port = util.free_port()

    if not connect_existing:
        logger.debug(
            "BROWSER EXECUTABLE PATH: %s", self.config.browser_executable_path
        )
        if not pathlib.Path(self.config.browser_executable_path).exists():
            raise FileNotFoundError(
                (
                    """
                ---------------------
                Could not determine browser executable.
                ---------------------
                Make sure your browser is installed in the default location (path).
                If you are sure about the browser executable, you can specify it using
                the `browser_executable_path='{}` parameter."""
                ).format(
                    "/path/to/browser/executable"
                    if is_posix
                    else "c:/path/to/your/browser.exe"
                )
            )

    if getattr(self.config, "_extensions", None):  # noqa
        self.config.add_argument(
            "--load-extension=%s"
            % ",".join(str(_) for _ in self.config._extensions)  # noqa
        )

    if self.config.lang is not None:
        self.config.add_argument(f"--lang={self.config.lang}")

    exe = self.config.browser_executable_path
    params = self.config()
    params.append("about:blank")

    logger.info(
        "starting\n\texecutable :%s\n\narguments:\n%s", exe, "\n\t".join(params)
    )
    if not connect_existing:
        self._process = util._start_process(exe, params, is_posix)
        self._process_pid = self._process.pid

    self._http = HTTPApi((self.config.host, self.config.port))
    util.get_registered_instances().add(self)
    await asyncio.sleep(self.config.browser_connection_timeout)
    for _ in range(self.config.browser_connection_max_tries):
        if await self.test_connection():
            break

        await asyncio.sleep(self.config.browser_connection_timeout)

    if not self.info:
        if self._process is not None:
            stderr = await util._read_process_stderr(self._process)
            logger.info(
                "Browser stderr: %s", stderr if stderr else "No output from browser"
            )

        await self.stop()
        raise Exception(
            (
                """
            ---------------------
            Failed to connect to browser
            ---------------------
            One of the causes could be when you are running as root.
            In that case you need to pass no_sandbox=True
            """
            )
        )

    self.connection = Connection(self.info.webSocketDebuggerUrl, _owner=self)

    if self.config.autodiscover_targets:
        logger.info("enabling autodiscover targets")

        self.connection.handlers[cdp.target.TargetInfoChanged] = [
            self._handle_target_update
        ]
        self.connection.handlers[cdp.target.TargetCreated] = [
            self._handle_target_update
        ]
        self.connection.handlers[cdp.target.TargetDestroyed] = [
            self._handle_target_update
        ]
        self.connection.handlers[cdp.target.TargetCrashed] = [
            self._handle_target_update
        ]

```

--------------------------------

### Get Manifest Icons (Deprecated)

Source: https://zendriver.dev/reference/cdp/page

Retrieves manifest icons for a page. This method is deprecated as the returned icon is not guaranteed to be the one used for PWA installation. It is marked as EXPERIMENTAL.

```python
import typing

from zendriver.cdp.cdp_types import T_JSON_DICT
from zendriver.utils import deprecated


@deprecated(version="1.3")
def get_manifest_icons() -> (
    typing.Generator[T_JSON_DICT, T_JSON_DICT, typing.Optional[str]]
):
    """
    Deprecated because it's not guaranteed that the returned icon is in fact the one used for PWA installation.

    .. deprecated:: 1.3

    **EXPERIMENTAL**

    :returns:
    """
    cmd_dict: T_JSON_DICT = {
        "method": "Page.getManifestIcons",
    }
    json = yield cmd_dict
    return (
        str(json["primaryIcon"]) if json.get("primaryIcon", None) is not None else None
    )
```

--------------------------------

### Get Browser Sampling Profile

Source: https://zendriver.dev/reference/cdp/memory

Retrieves the native memory allocations profile collected since the browser process started. This is useful for understanding overall memory usage patterns.

```python
def get_browser_sampling_profile() -> (
    typing.Generator[T_JSON_DICT, T_JSON_DICT, SamplingProfile]
):
    """
    Retrieve native memory allocations profile
    collected since browser process startup.

    :returns:
    """
    cmd_dict: T_JSON_DICT = {
        "method": "Memory.getBrowserSamplingProfile",
    }
    json = yield cmd_dict
    return SamplingProfile.from_json(json["profile"])

```

--------------------------------

### Start Browser Instance

Source: https://zendriver.dev/reference/core/browser

This method launches the browser process. It handles existing processes and ensures a free port is available if not already configured.

```python
if not connect_existing:
            logger.debug(
                "BROWSER EXECUTABLE PATH: %s", self.config.browser_executable_path
            )
            if not pathlib.Path(self.config.browser_executable_path).exists():
                raise FileNotFoundError(
                    (
                        """
                    ---------------------
                    Could not determine browser executable.
                    ---------------------
                    """
                    )
                )
```

--------------------------------

### Browser Initialization with Default Arguments

Source: https://zendriver.dev/reference/core/config

Illustrates the initialization of a browser instance, showing how default arguments are handled and how sandbox mode is automatically disabled when running as root on POSIX systems.

```python
self.sandbox = sandbox
    self.host = host
    self.port = port
    self.expert = expert
    self.disable_webrtc = disable_webrtc
    self.disable_webgl = disable_webgl
    self._extensions: list[PathLike] = []

    # when using posix-ish operating system and running as root
    # you must use no_sandbox = True, which in case is corrected here
    if is_posix and is_root() and sandbox:
        logger.info("detected root usage, auto disabling sandbox mode")
        self.sandbox = False

    self.autodiscover_targets = True
    self.lang = lang

    self.browser_connection_timeout = browser_connection_timeout
    self.browser_connection_max_tries = browser_connection_max_tries

    # other keyword args will be accessible by attribute
    self.__dict__.update(kwargs)
    super().__init__()
    self._default_browser_args = [
        "--remote-allow-origins=*",
        "--no-first-run",
        "--no-service-autorun",
        "--no-default-browser-check",
        "--homepage=about:blank",
        "--no-pings",
        "--password-store=basic",
        "--disable-infobars",
        "--disable-breakpad",
        "--disable-component-update",
        "--disable-backgrounding-occluded-windows",
        "--disable-renderer-backgrounding",
        "--disable-background-networking",
        "--disable-dev-shm-usage",
        "--disable-features=IsolateOrigins,DisableLoadExtensionCommandLineSwitch,site-per-process",
        "--disable-session-crashed-bubble",
        "--disable-search-engine-choice-screen",
    ]
```

--------------------------------

### __init__

Source: https://zendriver.dev/reference/core/expect

Initializes a new instance of DownloadExpectation.

```APIDOC
## __init__(tab)

Source code in `zendriver/core/expect.py`
```python
def __init__(self, tab: Connection):
    self.tab = tab
    self.future: asyncio.Future[cdp.browser.DownloadWillBegin] = asyncio.Future()
    # TODO: Improve
    self.default_behavior = (
        self.tab._download_behavior[0] if self.tab._download_behavior else "default"
    )
    self.download_path = (
        self.tab._download_behavior[1]
        if self.tab._download_behavior and len(self.tab._download_behavior) > 1
        else None
    )
```
```

--------------------------------

### Get All-Time Sampling Profile

Source: https://zendriver.dev/reference/cdp/memory

Retrieves the native memory allocations profile collected since the renderer process started. This provides a comprehensive view of memory usage over the lifetime of the process.

```python
def get_all_time_sampling_profile() -> (
    typing.Generator[T_JSON_DICT, T_JSON_DICT, SamplingProfile]
):
    """
    Retrieve native memory allocations profile
    collected since renderer process startup.

    :returns:
    """
    cmd_dict: T_JSON_DICT = {
        "method": "Memory.getAllTimeSamplingProfile",
    }
    json = yield cmd_dict
    return SamplingProfile.from_json(json["profile"])
```

--------------------------------

### Get Element Attribute Safely

Source: https://zendriver.dev/reference/core/element

Safely retrieves the value of an attribute by its name. It returns None if the attribute does not exist or if an AttributeError occurs during retrieval. Example: `href = element.get("href")`.

```python
try:
    x = getattr(self.attrs, name, None)
    if x:
        return x  # type: ignore
    return None
except AttributeError:
    return None
```

--------------------------------

### Start Tracing with Options

Source: https://zendriver.dev/reference/cdp/tracing

Initiates trace event collection using the Tracing.start method. This snippet demonstrates how to pass various configuration options, including categories, transfer mode, stream format, and compression. It's useful for setting up detailed performance monitoring.

```python
def start(
    categories: typing.Optional[str] = None,
    options: typing.Optional[str] = None,
    buffer_usage_reporting_interval: typing.Optional[float] = None,
    transfer_mode: typing.Optional[str] = None,
    stream_format: typing.Optional[StreamFormat] = None,
    stream_compression: typing.Optional[StreamCompression] = None,
    trace_config: typing.Optional[TraceConfig] = None,
    perfetto_config: typing.Optional[str] = None,
    tracing_backend: typing.Optional[TracingBackend] = None,
) -> typing.Generator[T_JSON_DICT, T_JSON_DICT, None]:
    """
    Start trace events collection.

    :param categories: **(DEPRECATED)** **(EXPERIMENTAL)** *(Optional)* Category/tag filter
    :param options: **(DEPRECATED)** **(EXPERIMENTAL)** *(Optional)* Tracing options
    :param buffer_usage_reporting_interval: **(EXPERIMENTAL)** *(Optional)* If set, the agent will issue bufferUsage events at this interval, specified in milliseconds
    :param transfer_mode: *(Optional)* Whether to report trace events as series of dataCollected events or to save trace to a stream (defaults to ```ReportEvents```).
    :param stream_format: *(Optional)* Trace data format to use. This only applies when using ````ReturnAsStream```` transfer mode (defaults to ````json````).
    :param stream_compression: **(EXPERIMENTAL)** *(Optional)* Compression format to use. This only applies when using ````ReturnAsStream```` transfer mode (defaults to ````none````)
    :param trace_config: *(Optional)*
    :param perfetto_config: **(EXPERIMENTAL)** *(Optional)* Base64-encoded serialized perfetto.protos.TraceConfig protobuf message When specified, the parameters ````categories````, ````options````, ````traceConfig```` are ignored. (Encoded as a base64 string when passed over JSON)
    :param tracing_backend: **(EXPERIMENTAL)** *(Optional)* Backend type (defaults to ````auto```)
    """
    params: T_JSON_DICT = dict()
    if categories is not None:
        params["categories"] = categories
    if options is not None:
        params["options"] = options
    if buffer_usage_reporting_interval is not None:
        params["bufferUsageReportingInterval"] = buffer_usage_reporting_interval
    if transfer_mode is not None:
        params["transferMode"] = transfer_mode
    if stream_format is not None:
        params["streamFormat"] = stream_format.to_json()
    if stream_compression is not None:
        params["streamCompression"] = stream_compression.to_json()
    if trace_config is not None:
        params["traceConfig"] = trace_config.to_json()
    if perfetto_config is not None:
        params["perfettoConfig"] = perfetto_config
    if tracing_backend is not None:
        params["tracingBackend"] = tracing_backend.to_json()
    cmd_dict: T_JSON_DICT = {
        "method": "Tracing.start",
        "params": params,
    }
    json = yield cmd_dict
```

--------------------------------

### Browser.start

Source: https://zendriver.dev/reference/core/browser

Launches the actual browser instance. This method should be called before interacting with browser functionalities. It handles starting a new browser process or connecting to an existing one.

```APIDOC
## Browser.start

### Description
Launches the actual browser instance. This method should be called before interacting with browser functionalities. It handles starting a new browser process or connecting to an existing one.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
None

### Request Example
```python
await browser.start()
```

### Response
#### Success Response
Returns the Browser instance itself after it has been started.

#### Response Example
```python
# Returns a Browser object
```

### Errors
* **ValueError**: If called as a class method instead of an instance method (use `await Browser.create()` to create an instance).
* **FileNotFoundError**: If the browser executable path is not found.
```

--------------------------------

### DownloadWillBegin Event Structure

Source: https://zendriver.dev/reference/cdp/page

Represents the Page.downloadWillBegin event, fired when a download is about to start. This event is deprecated; use Browser.downloadWillBegin instead. It includes frame ID, download GUID, URL, and suggested filename.

```python
@deprecated(version="1.3")
@event_class("Page.downloadWillBegin")
@dataclass
class DownloadWillBegin:
    """
    **EXPERIMENTAL**

    Fired when page is about to start a download.
    Deprecated. Use Browser.downloadWillBegin instead.
    """

    #: Id of the frame that caused download to begin.
    frame_id: FrameId
    #: Global unique identifier of the download.
    guid: str
    #: URL of the resource being downloaded.
    url: str
    #: Suggested file name of the resource (the actual name of the file saved on disk may differ).
    suggested_filename: str

    @classmethod
    def from_json(cls, json: T_JSON_DICT) -> DownloadWillBegin:
        return cls(
            frame_id=FrameId.from_json(json["frameId"]),
            guid=str(json["guid"]),
            url=str(json["url"]),
            suggested_filename=str(json["suggestedFilename"]),
        )

```

--------------------------------

### Get PWA OS App State

Source: https://zendriver.dev/reference/cdp/pwa

Retrieves the operating system state for a given PWA, including badge count and file handler information. Use this to inspect the current status of an installed PWA on the OS.

```python
def get_os_app_state(
    manifest_id: str,
) -> typing.Generator[
    T_JSON_DICT, T_JSON_DICT, typing.Tuple[int, typing.List[FileHandler]]
]:
    """
    Returns the following OS state for the given manifest id.

    :param manifest_id: The id from the webapp's manifest file, commonly it's the url of the site installing the webapp. See https://web.dev/learn/pwa/web-app-manifest.
    :returns: A tuple with the following items:

        0. **badgeCount** -
        1. **fileHandlers** -
    """
    params: T_JSON_DICT = dict()
    params["manifestId"] = manifest_id
    cmd_dict: T_JSON_DICT = {
        "method": "PWA.getOsAppState",
        "params": params,
    }
    json = yield cmd_dict
    return (
        int(json["badgeCount"]),
        [FileHandler.from_json(i) for i in json["fileHandlers"]],
    )
```

--------------------------------

### Browser Creation and Configuration

Source: https://zendriver.dev/reference/core/browser

This snippet shows the `Browser.create` method, the primary entry point for instantiating a Browser. It accepts a `Config` object or individual configuration parameters to customize the browser session, such as headless mode, user agent, and browser executable path. It also registers an `atexit` handler to ensure the browser is stopped and cleaned up properly.

```python
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:
        """
        entry point for creating an instance
        """
        if not config:
            config = Config(
                user_data_dir=user_data_dir,
                headless=headless,
                user_agent=user_agent,
                browser_executable_path=browser_executable_path,
                browser=browser,
                browser_args=browser_args or [],
                sandbox=sandbox,
                lang=lang,
                host=host,
                port=port,
                **kwargs,
            )
        instance = cls(config)
        await instance.start()

        async def browser_atexit() -> None:
            if not instance.stopped:
                await instance.stop()
            await instance._cleanup_temporary_profile()

        asyncio_atexit.register(browser_atexit)

        return instance
```

--------------------------------

### Create New Account Function

Source: https://zendriver.dev/tutorials/account-creation

Automates the process of creating a new account on the example page. It clicks the sign-up link, fills in the form fields (name, email, password), submits the form, and proceeds to login.

```python
async def create_account(page: Tab, name: str, email: str, password: str) -> None:
    # Click on the "Sign up" link
    sign_up_link = next(a for a in await page.select_all("a") if "Sign up" in a.text)
    await sign_up_link.click()
    await asyncio.sleep(0.5)

    # Fill in the sign-up form
    name_input = await page.select("#signupName")
    await name_input.send_keys(name)
    email_input = await page.select("#signupEmail")
    await email_input.send_keys(email)
    password_input = await page.select("#signupPassword")
    await password_input.send_keys(password)

    # Click the "Sign Up" button
    sign_up_button = next(
        button for button in await page.select_all("button") if "Sign Up" in button.text
    )
    await sign_up_button.click()
    await asyncio.sleep(0.5)

    # Click through confirmation dialog
    proceed_to_login = await page.find(text="Proceed to Login")
    await proceed_to_login.click()
```
Tokens:
Raw