From Selenium to Cloud Browsers: A Migration Guide

Selenium WebDriver has been the standard for browser automation since 2011. Millions of test suites, scraping scripts, and automation workflows are built on it. It works. But managing the infrastructure around it (browser installations, driver versions, grid servers, and Docker containers) has become the bottleneck.

Cloud browsers eliminate that bottleneck. BrowseFleet provides a Selenium-compatible endpoint, so your existing tests work with minimal changes.

Why Teams Migrate from Selenium

Teams do not leave Selenium because it is a bad tool. They leave because of the infrastructure tax:

Driver version management. Selenium requires a browser driver (ChromeDriver, GeckoDriver) that must match the installed browser version exactly. When Chrome auto-updates, ChromeDriver breaks. Teams spend hours debugging version mismatches that have nothing to do with their tests.

Browser installation. Each test environment needs a browser installed. CI containers need Chrome, its 20+ system dependencies, and enough memory to run it. Different CI providers have different base images, leading to "works on my machine" problems.

Selenium Grid. For parallel testing, teams set up Selenium Grid, a hub-and-node architecture for distributing tests across browser instances. Grid is complex to configure, monitor, and maintain. Node registration, session timeouts, and resource limits all need tuning.

Docker overhead. Running Selenium in Docker (via selenium/standalone-chrome or similar images) works but consumes significant resources. Each container needs 512MB-1GB of RAM. Running 20 parallel tests requires 10-20GB of RAM just for browsers.

Flakiness. Selenium tests are notoriously flaky. Timing issues, stale element references, and browser crashes cause intermittent failures that erode confidence in the test suite.

BrowseFleet's Selenium Compatibility

BrowseFleet provides a Remote WebDriver endpoint that accepts standard Selenium connections. Your existing Selenium tests connect to BrowseFleet instead of a local browser or Selenium Grid. The WebDriver protocol is the same. BrowseFleet translates it to CDP internally.

This means: - No ChromeDriver or GeckoDriver to install or manage - No browser binaries on the test machine - No Selenium Grid to set up or maintain - No Docker containers for browsers

Your tests send WebDriver commands to BrowseFleet's HTTP endpoint. BrowseFleet manages the browser instances, handles lifecycle, and provides stealth and proxy features that Selenium does not offer.

Step-by-Step Migration

Step 1: Install the BrowseFleet SDK. This is optional for Selenium. You can use the Remote WebDriver URL directly. But the SDK makes session management easier.

# Python
pip install browsefleet-python

# Node.js
npm install browsefleet

Step 2: Update your WebDriver configuration. Replace the local driver or Grid URL with BrowseFleet's endpoint.

# Python
from browsefleet import BrowseFleet
from selenium import webdriver

bf = BrowseFleet(api_key='bf_...')
session = bf.sessions.create(stealth='full')

# Replace local driver with Remote WebDriver
driver = webdriver.Remote(
    command_executor=session.selenium_url,
    options=webdriver.ChromeOptions(),
)

Step 3: Remove browser installation steps from CI. You no longer need Chrome, ChromeDriver, or their dependencies in your CI pipeline.

# Before
steps:
  - run: sudo apt-get install -y chromium-browser
  - run: pip install chromedriver-autoinstaller
  - run: python -m pytest tests/

# After
steps:
  - run: pip install browsefleet-python
  - run: python -m pytest tests/
    env:
      BROWSEFLEET_API_KEY: ${{ secrets.BF_KEY }}

Step 4: Update teardown. Close BrowseFleet sessions in your test teardown.

def teardown_method(self):
    self.driver.quit()
    self.session.close()  # Clean up BrowseFleet session

Step 5: Run your tests. Your existing Selenium tests should pass without changes to the test logic. The only changes are in the driver setup and teardown.

Before and After Code Comparison

Before: Local Selenium with ChromeDriver

from selenium import webdriver
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.chrome.options import Options

# Complex setup
options = Options()
options.add_argument('--headless=new')
options.add_argument('--no-sandbox')
options.add_argument('--disable-dev-shm-usage')
options.add_argument('--disable-gpu')

service = Service('/usr/local/bin/chromedriver')
driver = webdriver.Chrome(service=service, options=options)

# Test
driver.get('https://myapp.com')
assert 'My App' in driver.title

driver.quit()

After: BrowseFleet

from browsefleet import BrowseFleet
from selenium import webdriver

# Simple setup
bf = BrowseFleet(api_key='bf_...')
session = bf.sessions.create(stealth='full')
driver = webdriver.Remote(
    command_executor=session.selenium_url,
    options=webdriver.ChromeOptions(),
)

# Same test - no changes
driver.get('https://myapp.com')
assert 'My App' in driver.title

driver.quit()
session.close()

The test logic (everything between setup and teardown) is identical. Only the driver initialization changes.

Before: Selenium Grid

driver = webdriver.Remote(
    command_executor='http://selenium-hub:4444/wd/hub',
    options=webdriver.ChromeOptions(),
)

After: BrowseFleet

driver = webdriver.Remote(
    command_executor=session.selenium_url,
    options=webdriver.ChromeOptions(),
)

If you are already using Selenium Grid, the migration is a one-line URL change.

Handling Browser Drivers

One of the biggest advantages of migrating to BrowseFleet is eliminating browser driver management entirely.

With local Selenium, you need: - The correct Chrome/Firefox version installed - A matching ChromeDriver/GeckoDriver version - A mechanism to keep them in sync (chromedriver-autoinstaller, webdriver-manager) - System dependencies for Chrome (libxss1, libnss3, libatk-bridge2.0-0, etc.)

With BrowseFleet, you need: - The browsefleet SDK (or just the endpoint URL) - An API key

That is it. No browser binaries, no driver binaries, no system dependencies. The browser runs on BrowseFleet's infrastructure. Your test machine only needs network access.

What Changes and What Does Not

What changes:

• Driver initialization (local/Grid URL becomes BrowseFleet URL)
• CI pipeline (remove browser installation steps)
• Session cleanup (close BrowseFleet sessions in teardown)
• Infrastructure (no more Grid servers, Docker containers, or browser management)

What does not change:

• Test logic (find elements, click, type, assert - all identical)
• Test structure (test classes, setup, teardown patterns)
• Locator strategies (ID, name, CSS, XPath - all supported)
• Assertions (page title, element text, visibility - all work)
• Wait strategies (explicit waits, expected conditions - all work)
• Page Object patterns (your page objects do not change)

The migration is mechanical. Change the setup, keep the tests. Most teams complete it in an afternoon.

New capabilities after migration:

• Stealth mode for accessing bot-protected sites
• CAPTCHA solving for automated workflows
• Cookie persistence across test runs
• Per-session proxy support
• Screenshots and PDF generation via API
• Scale to 100 concurrent sessions without infrastructure changes