Robocorp Browser

Common errors

• BrowserNotFoundError: Failed to start a browser: - chromium: Could not get browser version.

  cause The underlying Playwright browser executable is not installed or cannot be found, or there's an incompatibility with the system environment.
  fix Run `playwright install` in your environment to ensure the necessary browser binaries are downloaded. Alternatively, configure `browser.configure(install=True)` which attempts to download if the browser fails to launch. Ensure your system meets Playwright's requirements.

• RuntimeError: If persistent_context_directory is specified in the configuration and this method is called a RuntimeError is raised (as in this case this API is not applicable as the browser and the context must be created at once and the browser can't be reused for the session).

  cause You are attempting to call `browser.browser()` while `persistent_context_directory` has been set in `browser.configure()`. The `browser.browser()` method is incompatible with persistent contexts.
  fix Instead of `browser.browser()`, use `browser.page()` or `browser.context()` after calling `browser.configure(persistent_context_directory='...')`. These methods correctly manage the browser and context with the persistent directory.

• UnicodeEncodeError: 'charmap' codec can't encode character '\u2013' in position ...

  cause This typically occurs on Windows systems when the default console code page is not set to a Unicode-compatible encoding, leading to issues with non-ASCII characters in logs or outputs.
  fix Ensure your Windows system's code page is set to Unicode (e.g., UTF-8). This can often be resolved by changing system locale settings or running scripts with `chcp 65001` (though robust solutions involve proper encoding handling within Python or environment configuration).

Warnings

• breaking The default behavior of the `headless` option in `browser.configure` changed in version 2.0.0. If `headless` is unset or set to `None`, the browser UI will now be shown (i.e., `headless=False`) unless running in a Linux VM without a `DISPLAY` or `WAYLAND_DISPLAY` environment variable set.
  Fix: Explicitly set `headless=True` to ensure headless execution or `headless=False` to ensure UI is always shown, regardless of the environment detection.
• gotcha When using `persistent_context_directory` in `browser.configure` (introduced in 2.2.0), calling `browser.browser()` directly will raise a `RuntimeError`. This is because the persistent context requires the browser and context to be created together.
  Fix: After configuring `persistent_context_directory`, interact with the browser using `browser.page()` or `browser.context()` directly, which implicitly handle the browser instance creation with the persistent context.
• gotcha `robocorp-browser` is not included in the `robocorp` metapackage. If you are using `robocorp-tasks` or other Robocorp tools, you must explicitly declare `robocorp-browser` as a dependency in your project's `conda.yaml`, `package.yaml`, `requirements.txt`, or similar configuration file.
  Fix: Add `robocorp-browser` to your project's dependency management file (e.g., `pip install robocorp-browser` locally, or add to `requirements.txt` / `conda.yaml` for Robocorp environments).

Install

• pip install robocorp-browser Install `robocorp-browser`

Imports

• browser

  from robocorp import browser

• task

  from robocorp.tasks import task

  For defining automation tasks, typically used with robocorp-browser.
• vault

  from robocorp import vault

  For accessing secrets, commonly used with robocorp-browser automation for logins.

Quickstart

This quickstart demonstrates how to initialize the browser, configure its behavior (like headless mode and slow motion), navigate to a URL, and interact with elements using the underlying Playwright API. It also shows how to integrate with `robocorp-tasks` and `robocorp-vault` for defining tasks and managing secrets.

import os
from robocorp import browser
from robocorp.tasks import task
from robocorp import vault # For secret management example

@task
def automate_browser_example():
    """Start a browser, navigate, and interact with a page."""
    # Configure browser settings (optional)
    browser.configure(
        browser_engine="chromium",
        headless=True, # Set to False to see the browser UI
        slowmo=100, # Run interactions in slow motion (milliseconds)
        screenshot="only-on-failure", # Capture screenshot on error
    )

    # Get a secret (example: login credentials)
    # In a real scenario, configure 'default-account' in Robocorp Vault
    # For quickstart, we use environment variables as a fallback
    username = os.environ.get('TEST_USERNAME', 'user')
    password = os.environ.get('TEST_PASSWORD', 'pass')
    
    try:
        account = vault.get_secret("default-account")
        username = account["username"]
        password = account["password"]
    except Exception:
        print("Warning: Could not get secret 'default-account'. Using environment variables or defaults.")

    # Navigate to a page (this will automatically launch the browser if not already open)
    page = browser.goto("https://www.example.com/login") # Replace with a real login page

    # Interact with elements using Playwright API
    # Example: fill login form (replace with actual selectors)
    # page.fill("#username_field", username)
    # page.fill("#password_field", password)
    # page.click("#login_button")

    # Perform some action, e.g., take a screenshot
    browser.screenshot(page=page, path="output/example_screenshot.png")
    print(f"Navigated to {page.url} and took a screenshot.")

    # The browser instance is automatically closed when the task finishes.