# BrowserBase Integration

## Route Donobu test sessions through BrowserBase cloud browsers for CI environments, high parallelism, or sites with bot detection.

[BrowserBase](https://www.browserbase.com/) is a cloud browser infrastructure service. Donobu can route test sessions through BrowserBase instead of launching a local Playwright browser, which is useful for CI environments, high parallelism, or sites that employ bot detection.

## When to use BrowserBase
- **CI without a display server**: cloud browsers run headlessly without requiring `xvfb` or similar
- **High parallelism**: run many concurrent sessions without managing local browser processes
- **Bot detection bypass**: BrowserBase browsers appear more like real users to fingerprinting-based protections
- **Consistent environment**: remove browser version discrepancies between developer machines and CI

## Configuration

Set two environment variables before running your tests:

```bash
export BROWSERBASE_API_KEY=your_browserbase_api_key
export BROWSERBASE_PROJECT_ID=your_browserbase_project_id
```

No code changes are required. When both variables are present, Donobu automatically routes all browser sessions through BrowserBase instead of launching a local Chromium instance.

## GitHub Actions example

```yaml
- name: Run tests (BrowserBase)
  env:
    DONOBU_API_KEY: ${{ secrets.DONOBU_API_KEY }}
    BROWSERBASE_API_KEY: ${{ secrets.BROWSERBASE_API_KEY }}
    BROWSERBASE_PROJECT_ID: ${{ secrets.BROWSERBASE_PROJECT_ID }}
  run: npx donobu test
```

## What changes compared to local execution
- **Browser launch**: Donobu connects to a BrowserBase-managed browser over a remote debugging protocol rather than spawning a local process
- **Session lifecycle**: BrowserBase manages session isolation and cleanup
- **Network routing**: traffic from the browser originates from BrowserBase's infrastructure, not your machine or CI runner

All Donobu and Playwright APIs work identically — `page.ai`, `page.find`, `page.changeTab`, etc. behave the same way.

## Limitations and considerations
- BrowserBase usage is metered — factor session costs into your CI budget
- Very long-running tests may hit BrowserBase session time limits; check your plan's limits and keep `timeout` values reasonable
- Some Playwright features that require direct access to the browser process (e.g. `page.context().setOffline`) may behave differently in a remote session — consult BrowserBase's documentation for compatibility details.