Add a new migration guide

Author: mdmintz

examples/migration/raw_selenium/to_playwright/01_hybrid_approach/ReadMe.md

@@ -0,0 +1,84 @@
+<!-- SeleniumBase Docs -->
+
+## 🛠️ Standalone Automation Scripts (Non-Test)
+
+This folder contains examples for users who need to perform web automation **without** using a test runner like `pytest` or `unittest`.
+
+By using the hybrid approach seen in [raw_hybrid_script.py](./raw_hybrid_script.py), SeleniumBase has effectively bridged the gap between raw Selenium and Playwright in order to ease the migration process.
+
+```python
+"""Hybrid Script Example"""
+from playwright.sync_api import sync_playwright, expect
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.ui import WebDriverWait
+from seleniumbase import SB
+
+
+with SB(uc=True) as sb:  # SeleniumBase API
+    sb.activate_cdp_mode()
+    sb.reconnect()  # Reconnects WebDriver to use Selenium
+    driver = sb.driver  # Selenium API
+    endpoint_url = sb.cdp.get_endpoint_url()
+    with sync_playwright() as p:
+        browser = p.chromium.connect_over_cdp(endpoint_url)
+        page = browser.contexts[0].pages[0]  # Playwright API
+
+        # This section uses Selenium
+        driver.get("https://www.saucedemo.com")
+        by_css = By.CSS_SELECTOR  # "css selector"
+        element = driver.find_element(by_css, "#user-name")
+        element.send_keys("standard_user")
+        element = driver.find_element(by_css, "#password")
+        element.send_keys("secret_sauce")
+        element.submit()
+        driver.find_element(by_css, "div.inventory_list")
+        element = driver.find_element(by_css, "span.title")
+        assert element.text == "Products"
+
+        # This section uses Playwright
+        page.click('button[name*="backpack"]')
+        page.click("#shopping_cart_container a")
+        expect(page.locator("span.title")).to_have_text("Your Cart")
+        expect(page.locator("div.cart_item")).to_contain_text("Backpack")
+
+        # This section uses SeleniumBase
+        sb.click("#remove-sauce-labs-backpack")
+        sb.assert_element_not_visible("div.cart_item")
+
+        # This section uses Selenium
+        driver.find_element(by_css, "#react-burger-menu-btn").click()
+        element = WebDriverWait(driver, 10).until(
+            EC.element_to_be_clickable((by_css, "a#logout_sidebar_link"))
+        )
+        element.click()
+        driver.find_element(by_css, "input#login-button")
+```
+
+This folder also includes standalone scripts for raw Selenium, Playwright, and SeleniumBase, which serve as foundational components for the hybrid script that integrates all three.
+
+### 💡 Why use Standalone Scripts?
+While test runners are excellent for verification and reporting, standalone scripts are often preferred for:
+* **Web Scraping:** Extracting data from sites without the overhead of a test framework.
+* **DevOps/Utility Tasks:** Automating repetitive browser-based tasks or health checks.
+* **Rapid Prototyping:** Testing out a new automation flow quickly before formalizing it into a test suite.
+
+### 🌉 The "SB" Advantage
+The `raw_hybrid_script.py` example demonstrates how to use the **`SB()` context manager**. This is a powerful feature of SeleniumBase that allows you to:
+1. **Bridge Engines:** Effortlessly connect Playwright to a browser session already managed by SeleniumBase.
+2. **Stealth by Default:** Use `uc=True` (Undetected Mode) to bypass bot-detection systems that standard Playwright configurations often fail.
+3. **Automatic Cleanup:** The context manager handles closing the browser and cleaning up processes automatically, even if the script encounters an error.
+
+---
+
+### 🚀 Quick Start
+
+To run any of these examples, simply execute them with Python:
+
+```bash
+python raw_hybrid_script.py
+```
+
+--------
+
+[<img src="https://seleniumbase.github.io/cdn/img/fancy_logo_14.png" title="SeleniumBase" width="290">](https://github.com/seleniumbase/SeleniumBase)

examples/migration/raw_selenium/to_playwright/01_hybrid_approach/__init__.py

@@ -0,0 +1,46 @@
+"""Hybrid Script Example"""
+from playwright.sync_api import sync_playwright, expect
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.ui import WebDriverWait
+from seleniumbase import SB
+
+
+with SB(uc=True) as sb:  # SeleniumBase API
+    sb.activate_cdp_mode()
+    sb.reconnect()  # Reconnects WebDriver to use Selenium
+    driver = sb.driver  # Selenium API
+    endpoint_url = sb.cdp.get_endpoint_url()
+    with sync_playwright() as p:
+        browser = p.chromium.connect_over_cdp(endpoint_url)
+        page = browser.contexts[0].pages[0]  # Playwright API
+
+        # This section uses Selenium
+        driver.get("https://www.saucedemo.com")
+        by_css = By.CSS_SELECTOR  # "css selector"
+        element = driver.find_element(by_css, "#user-name")
+        element.send_keys("standard_user")
+        element = driver.find_element(by_css, "#password")
+        element.send_keys("secret_sauce")
+        element.submit()
+        driver.find_element(by_css, "div.inventory_list")
+        element = driver.find_element(by_css, "span.title")
+        assert element.text == "Products"
+
+        # This section uses Playwright
+        page.click('button[name*="backpack"]')
+        page.click("#shopping_cart_container a")
+        expect(page.locator("span.title")).to_have_text("Your Cart")
+        expect(page.locator("div.cart_item")).to_contain_text("Backpack")
+
+        # This section uses SeleniumBase
+        sb.click("#remove-sauce-labs-backpack")
+        sb.assert_element_not_visible("div.cart_item")
+
+        # This section uses Selenium
+        driver.find_element(by_css, "#react-burger-menu-btn").click()
+        element = WebDriverWait(driver, 10).until(
+            EC.element_to_be_clickable((by_css, "a#logout_sidebar_link"))
+        )
+        element.click()
+        driver.find_element(by_css, "input#login-button")

examples/migration/raw_selenium/to_playwright/01_hybrid_approach/non_test_scripts/ReadMe.md

@@ -0,0 +1,23 @@
+from playwright.sync_api import sync_playwright, expect
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(channel="chrome", headless=False)
+    page = browser.new_context().new_page()
+    page.goto("https://www.saucedemo.com")
+    page.fill("#user-name", "standard_user")
+    page.fill("#password", "secret_sauce")
+    page.press("#password", "Enter")
+    expect(page.locator("div.inventory_list")).to_be_visible()
+    expect(page.locator("span.title")).to_contain_text("Products")
+
+    page.click('button[name*="backpack"]')
+    page.click("#shopping_cart_container a")
+    expect(page.locator("span.title")).to_have_text("Your Cart")
+    expect(page.locator("div.cart_item")).to_contain_text("Backpack")
+
+    page.click("#remove-sauce-labs-backpack")
+    expect(page.locator("div.cart_item")).to_be_hidden()
+
+    page.click("#react-burger-menu-btn")
+    page.click("a#logout_sidebar_link")
+    expect(page.locator("input#login-button")).to_be_visible()

examples/migration/raw_selenium/to_playwright/01_hybrid_approach/non_test_scripts/__init__.py

@@ -0,0 +1,20 @@
+from seleniumbase import SB
+
+with SB() as sb:
+    sb.open("https://www.saucedemo.com")
+    sb.type("#user-name", "standard_user")
+    sb.type("#password", "secret_sauce\n")
+    sb.assert_element("div.inventory_list")
+    sb.assert_text("Products", "span.title")
+
+    sb.click('button[name*="backpack"]')
+    sb.click("#shopping_cart_container a")
+    sb.assert_exact_text("Your Cart", "span.title")
+    sb.assert_text("Backpack", "div.cart_item")
+
+    sb.click("#remove-sauce-labs-backpack")
+    sb.assert_element_not_visible("div.cart_item")
+
+    sb.click("#react-burger-menu-btn")
+    sb.click("a#logout_sidebar_link")
+    sb.assert_element("input#login-button")

examples/migration/raw_selenium/to_playwright/01_hybrid_approach/non_test_scripts/raw_hybrid_script.py

@@ -0,0 +1,62 @@
+import sys
+from selenium import webdriver
+from selenium.webdriver.chrome.service import Service
+from selenium.webdriver.common.by import By
+from selenium.webdriver.support import expected_conditions as EC
+from selenium.webdriver.support.ui import WebDriverWait
+
+
+def is_element_visible(driver, selector, by="css selector"):
+    try:
+        element = driver.find_element(by, selector)
+        if element.is_displayed():
+            return True
+    except Exception:
+        pass
+    return False
+
+
+options = webdriver.ChromeOptions()
+options.add_argument("--disable-notifications")
+if "linux" in sys.platform:
+    options.add_argument("--headless")
+options.add_experimental_option(
+    "excludeSwitches", ["enable-automation", "enable-logging"],
+)
+prefs = {
+    "credentials_enable_service": False,
+    "profile.password_manager_enabled": False,
+    "profile.password_manager_leak_detection": False,
+}
+options.add_experimental_option("prefs", prefs)
+service = Service(service_args=["--disable-build-check"])
+
+
+with webdriver.Chrome(options=options, service=service) as driver:
+    driver.get("https://www.saucedemo.com")
+    by_css = By.CSS_SELECTOR  # "css selector"
+    element = driver.find_element(by_css, "#user-name")
+    element.send_keys("standard_user")
+    element = driver.find_element(by_css, "#password")
+    element.send_keys("secret_sauce")
+    element.submit()
+    driver.find_element(by_css, "div.inventory_list")
+    element = driver.find_element(by_css, "span.title")
+    assert element.text == "Products"
+
+    driver.find_element(by_css, 'button[name*="backpack"]').click()
+    driver.find_element(by_css, "#shopping_cart_container a").click()
+    element = driver.find_element(by_css, "span.title")
+    assert element.text == "Your Cart"
+    element = driver.find_element(by_css, "div.cart_item")
+    assert "Backpack" in element.text
+
+    driver.find_element(by_css, "#remove-sauce-labs-backpack").click()
+    assert not is_element_visible(driver, "div.cart_item")
+
+    driver.find_element(by_css, "#react-burger-menu-btn").click()
+    element = WebDriverWait(driver, 10).until(
+        EC.element_to_be_clickable((by_css, "a#logout_sidebar_link"))
+    )
+    element.click()
+    driver.find_element(by_css, "input#login-button")

examples/migration/raw_selenium/to_playwright/01_hybrid_approach/non_test_scripts/raw_script_pw.py

@@ -0,0 +1,57 @@
+"""Playwright TestCase Example"""
+import sys
+from playwright.sync_api import sync_playwright, expect
+from unittest import TestCase
+
+
+class PlaywrightTestCase(TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.playwright = sync_playwright().start()
+        headless = "linux" in sys.platform or "--headless" in sys.argv
+        # Launch browser once for the whole class
+        cls.browser = cls.playwright.chromium.launch(
+            channel="chrome", headless=headless
+        )
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.browser.close()
+        cls.playwright.stop()
+
+    def setUp(self):
+        # Create new session for every test
+        self.context = self.browser.new_context()
+        self.page = self.context.new_page()
+
+    def tearDown(self):
+        # Close the session (browser runs until tearDownClass)
+        self.page.close()
+        self.context.close()
+
+    def test_add_item_to_cart(self):
+        page = self.page
+
+        page.goto("https://www.saucedemo.com")
+        page.fill("#user-name", "standard_user")
+        page.fill("#password", "secret_sauce")
+        page.press("#password", "Enter")
+        expect(page.locator("div.inventory_list")).to_be_visible()
+        expect(page.locator("span.title")).to_contain_text("Products")
+
+        page.click('button[name*="backpack"]')
+        page.click("#shopping_cart_container a")
+        expect(page.locator("span.title")).to_have_text("Your Cart")
+        expect(page.locator("div.cart_item")).to_contain_text("Backpack")
+
+        page.click("#remove-sauce-labs-backpack")
+        expect(page.locator("div.cart_item")).to_be_hidden()
+
+        page.click("#react-burger-menu-btn")
+        page.click("a#logout_sidebar_link")
+        expect(page.locator("input#login-button")).to_be_visible()
+
+
+if __name__ == "__main__":
+    from pytest import main
+    main([__file__, "-s"])

examples/migration/raw_selenium/to_playwright/01_hybrid_approach/non_test_scripts/raw_script_sb.py

@@ -0,0 +1,73 @@
+"""
+Playwright TestCase Example with Tracing.
+Trace logs are saved to: `latest_logs/[TESTPATH]/trace.zip`
+To open Trace Viewer: `playwright show-trace TRACEPATH.zip`
+"""
+import os
+import sys
+from playwright.sync_api import sync_playwright, expect
+from unittest import TestCase
+
+
+class PlaywrightTestCaseWithTracing(TestCase):
+    @classmethod
+    def setUpClass(cls):
+        cls.playwright = sync_playwright().start()
+        headless = "linux" in sys.platform or "--headless" in sys.argv
+        # Launch browser once for the whole class
+        cls.browser = cls.playwright.chromium.launch(
+            channel="chrome", headless=headless
+        )
+
+    @classmethod
+    def tearDownClass(cls):
+        cls.browser.close()
+        cls.playwright.stop()
+
+    def setUp(self):
+        # Create new session for every test
+        self.context = self.browser.new_context()
+        self.context.tracing.start(
+            snapshots=True, screenshots=True, sources=True
+        )
+        self.page = self.context.new_page()
+
+    def tearDown(self):
+        # Close the session (browser runs until tearDownClass)
+        log_folder = "latest_logs"
+        test_id = "%s.%s.%s" % (
+            self.__class__.__module__,
+            self.__class__.__name__,
+            self._testMethodName,
+        )
+        trace_path = os.path.join(log_folder, test_id, "trace.zip")
+        self.context.tracing.stop(path=trace_path)
+        self.page.close()
+        self.context.close()
+
+    def test_add_item_to_cart(self):
+        page = self.page
+
+        page.goto("https://www.saucedemo.com")
+        page.fill("#user-name", "standard_user")
+        page.fill("#password", "secret_sauce")
+        page.press("#password", "Enter")
+        expect(page.locator("div.inventory_list")).to_be_visible()
+        expect(page.locator("span.title")).to_contain_text("Products")
+
+        page.click('button[name*="backpack"]')
+        page.click("#shopping_cart_container a")
+        expect(page.locator("span.title")).to_have_text("Your Cart")
+        expect(page.locator("div.cart_item")).to_contain_text("Backpack")
+
+        page.click("#remove-sauce-labs-backpack")
+        expect(page.locator("div.cart_item")).to_be_hidden()
+
+        page.click("#react-burger-menu-btn")
+        page.click("a#logout_sidebar_link")
+        expect(page.locator("input#login-button")).to_be_visible()
+
+
+if __name__ == "__main__":
+    from pytest import main
+    main([__file__, "-s"])