Add DriverWrapper.connect_cdp for CDP browser connections

Problem:
MOPS requires users to manually create driver objects when connecting to
remote browsers via Chrome DevTools Protocol (CDP). This involves
boilerplate code for lifecycle management and cleanup.

Use cases:
- Testing Electron apps on remote machines via CDP + SSH tunnel
- Connecting to cloud browser services (BrowserStack, Sauce Labs)
- Attaching to an already-running browser instance for debugging
- Testing CEF-based or WebView2 applications

Solution:
Add a factory classmethod DriverWrapper.connect_cdp(endpoint_url) that
handles the full lifecycle. Supports both Playwright and Selenium engines
via the engine parameter (default: "playwright").

Playwright engine:
  Starts Playwright, connects via chromium.connect_over_cdp, wraps the
  resulting page. Playwright instance is stopped on quit().

Selenium engine:
  Creates Chrome WebDriver with debugger_address option pointing to the
  CDP endpoint.

Architectural changes:
- DriverWrapper.is_cdp flag: identifies CDP-connected wrappers, used by
  PlayDriver.quit() to skip tracing on pre-existing CDP contexts
- PlayDriver.quit(): tracing.stop() skipped for CDP (not just caught);
  page.close() and context.close() wrapped in try/except
- CoreDriver.quit(): wrapped in try/except for externally-managed browsers
- PlayDriver.get_inner_window_size(): null-safe for CDP default viewport

API:
- DriverWrapper.connect_cdp(endpoint_url, engine, timeout, page_index,
  viewport_size) — main entry point
- DriverWrapperABC.connect_cdp() — abstract interface
- DriverWrapper.is_cdp — bool flag (False by default, True after connect_cdp)

Version bump: 3.3.1 -> 3.4.0

Documentation:
- Getting Started: CDP section with both engine examples + limitations
- Index: CDP listed in key features
- DriverWrapper overview: CDP mentioned in description and status attrs
- CHANGELOG: v3.4.0 entry

Tests: 14 unit tests covering both engines, is_cdp flag, URL parsing,
parameters, cleanup, sessions, and compatibility

Made-with: Cursor

Author: wwakabobik

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 <br>
 
+## v3.4.0
+
+### Added
+- `DriverWrapper.connect_cdp` class method for connecting to remote browsers via CDP (supports both Playwright and Selenium engines)
+- `DriverWrapper.is_cdp` flag to identify CDP-connected driver instances
+- `PlayDriver.quit` graceful error handling for CDP and pre-existing contexts; tracing skip for CDP
+- `CoreDriver.quit` graceful error handling for externally-managed browsers (CDP)
+- `PlayDriver.get_inner_window_size` null-safe viewport handling for CDP connections
+
+---
+
 ## v3.3.1
 *Release date: 2026-01-05*
 

docs/source/driver_wrapper/index.md

@@ -15,6 +15,10 @@ The `DriverWrapper` module provides a unified interface to interact with differe
 such as _Selenium_, _Appium_, and _Playwright_. It abstracts the complexities of these frameworks and offers a seamless 
 experience for managing driver sessions, performing operations, and handling cross-platform automation tasks.
 
+It also supports connecting to remote browsers via **Chrome DevTools Protocol (CDP)** using the
+`DriverWrapper.connect_cdp()` class method, enabling testing of Electron applications, cloud browser
+services, and pre-existing browser instances.
+
 <br>
 
 ### Core Benefits & Rules
@@ -26,7 +30,7 @@ experience for managing driver sessions, performing operations, and handling cro
    - The `DriverWrapper` and its underlying `Driver` instance are easily accessible within your `Page`, `Group`, and `Element` objects, allowing for consistent and efficient interactions across your test suite.
 
 3. **Dynamic Status Attributes:**
-   - `DriverWrapper` provides various status attributes (e.g., `is_mobile`, `is_selenium`, `is_playwright`) that help you tailor your test behavior based on the current driver environment, ensuring more precise control and adaptability in your tests.
+   - `DriverWrapper` provides various status attributes (e.g., `is_mobile`, `is_selenium`, `is_playwright`, `is_cdp`) that help you tailor your test behavior based on the current driver environment, ensuring more precise control and adaptability in your tests.
 
 4. **Optimal Driver Setup:**
    - The initialization of the source driver should be handled within your testing framework. This approach ensures that the browser or device starts with the most appropriate configuration, leading to more reliable and efficient test executions.

docs/source/getting_started.md

@@ -142,6 +142,60 @@ def driver_wrapper():
 
 ---
 
+<br>
+
+### CDP connection setup
+
+```{note}
+CDP (Chrome DevTools Protocol) connection is useful for testing Electron applications, 
+connecting to cloud browser services, or attaching to an already-running browser instance.
+Both Playwright and Selenium engines are supported.
+```
+
+**Playwright (default):**
+
+```python
+import pytest  # noqa
+from mops.base.driver_wrapper import DriverWrapper
+
+
+@pytest.fixture
+def driver_wrapper():
+    wrapper = DriverWrapper.connect_cdp("http://localhost:9222")
+    yield wrapper
+    wrapper.quit()
+```
+
+**Selenium:**
+
+```python
+import pytest  # noqa
+from mops.base.driver_wrapper import DriverWrapper
+
+
+@pytest.fixture
+def driver_wrapper():
+    wrapper = DriverWrapper.connect_cdp("http://localhost:9222", engine="selenium")
+    yield wrapper
+    wrapper.quit()
+```
+
+```{attention}
+**Playwright CDP limitations:**
+
+- ``record_har_path`` and ``record_video_dir`` cannot be set on pre-existing contexts.
+- Network interception may also be limited.
+- ``viewport_size`` is not set by default — pass it explicitly if your tests rely on ``get_inner_window_size()``.
+- Tab creation via ``create_new_tab()`` may behave differently with CDP contexts.
+
+**Selenium CDP limitations:**
+
+- The browser is managed externally — ``quit()`` will attempt to close it gracefully, 
+  but the browser process may remain if it was started outside the test.
+```
+
+---
+
 ## 4. Write A Test
 
 <br>

docs/source/index.md

@@ -17,6 +17,7 @@ process, giving you the flexibility and power to automate complex testing scenar
 - **Seamless Integration**: Mops integrates with Selenium, Appium, and Playwright, allowing you to use the best-suited engine for your specific testing needs.
 - **Unified API**: A single, easy-to-use API that abstracts away the differences between Selenium, Appium, and Playwright, making your test scripts more readable and maintainable.
 - **Engine Switching**: Switch between Selenium, Appium, and Playwright within the same test case, enabling cross-platform and cross-browser testing with minimal effort.
+- **CDP Connection**: Connect to remote browsers via Chrome DevTools Protocol using `DriverWrapper.connect_cdp()` — ideal for Electron apps, cloud browser services, and pre-existing browser instances. Both Playwright and Selenium engines are supported.
 - **Visual Regression Testing**: Perform visual regression tests using the integrated visual regression tool, available across all supported frameworks. This ensures your UI remains consistent across different browsers and devices.
 - **Advanced Features**: Leverage the advanced features of each framework, such as Playwright's mocks and Appium's real mobile devices support, all while using the same testing framework.
 - **Extensibility**: Extend the framework with custom functionality tailored to your project's specific requirements.

mops/__init__.py

@@ -1,2 +1,2 @@
-__version__ = '3.3.1'
+__version__ = '3.4.0'
 __project_name__ = 'mops'

mops/abstraction/driver_wrapper_abc.py

@@ -2,7 +2,7 @@
 
 from abc import ABC
 from functools import cached_property
-from typing import List, Union, Any, Tuple, TYPE_CHECKING
+from typing import List, Union, Any, Tuple, Optional, Dict, TYPE_CHECKING
 
 from playwright.sync_api import Page as PlaywrightPage
 
@@ -45,6 +45,8 @@ class DriverWrapperABC(ABC):
     is_simulator: bool = False
     is_real_device: bool = False
 
+    is_cdp: bool = False
+
     browser_name: Union[str, None] = None
 
     @cached_property
@@ -95,6 +97,55 @@ def quit(self, silent: bool = False, trace_path: str = 'trace.zip'):
         """
         raise NotImplementedError()
 
+    @classmethod
+    def connect_cdp(
+            cls,
+            endpoint_url: str,
+            engine: str = 'playwright',
+            timeout: int = 30000,
+            page_index: int = 0,
+            viewport_size: Optional[Dict[str, int]] = None,
+    ) -> DriverWrapper:
+        """
+        Connect to a remote browser via Chrome DevTools Protocol.
+
+        Creates a connection to the specified CDP endpoint and wraps the resulting
+        driver in a :class:`DriverWrapper`. Useful for testing Electron applications,
+        connecting to cloud browser services, or attaching to an already-running
+        browser instance.
+
+        **Playwright engine:**
+
+        Starts a Playwright instance internally and connects via
+        ``chromium.connect_over_cdp``. The Playwright instance is stopped
+        automatically when :meth:`quit` is called.
+
+        .. note::
+            Some Playwright features are unavailable in CDP mode:
+            ``record_har_path`` and ``record_video_dir`` cannot be set on pre-existing contexts.
+            Network interception may also be limited.
+
+        **Selenium engine:**
+
+        Creates a Chrome WebDriver with ``debugger_address`` option pointing
+        to the CDP endpoint.
+
+        :param endpoint_url: CDP endpoint URL (e.g., ``"http://localhost:9222"``).
+        :type endpoint_url: str
+        :param engine: The engine to use for the connection. ``"playwright"`` or ``"selenium"``.
+        :type engine: str
+        :param timeout: Connection timeout in milliseconds (Playwright only).
+        :type timeout: int
+        :param page_index: Index of the page to use from the connected context
+          (default: 0, Playwright only).
+        :type page_index: int
+        :param viewport_size: Optional viewport size dict ``{"width": int, "height": int}``.
+        :type viewport_size: typing.Optional[typing.Dict[str, int]]
+        :return: Initialized :class:`DriverWrapper` connected to the remote browser.
+        :rtype: DriverWrapper
+        """
+        raise NotImplementedError()
+
     def wait(self, timeout: Union[int, float] = WAIT_UNIT, reason: str = '') -> DriverWrapper:
         """
         Pauses the execution for a specified amount of time.

mops/base/driver_wrapper.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Union, Type, List, Tuple, TYPE_CHECKING
+from typing import Union, Type, List, Tuple, Optional, Dict, TYPE_CHECKING
 
 from PIL import Image
 from appium.webdriver.webdriver import WebDriver as AppiumDriver
@@ -9,6 +9,7 @@
     Page as PlaywrightDriver,
     Browser as PlaywrightBrowser,
     BrowserContext as PlaywrightContext,
+    sync_playwright,
 )
 
 from mops.mixins.objects.box import Box
@@ -122,6 +123,8 @@ class DriverWrapper(InternalMixin, Logging, DriverWrapperABC):
     is_simulator: bool = False
     is_real_device: bool = False
 
+    is_cdp: bool = False
+
     browser_name: Union[str, None] = None
 
     def __new__(cls, *args, **kwargs):
@@ -166,6 +169,133 @@ def __init__(self, driver: Driver):
             self.is_desktop = False
             self.is_mobile = True
 
+    @classmethod
+    def connect_cdp(
+            cls,
+            endpoint_url: str,
+            engine: str = 'playwright',
+            timeout: int = 30000,
+            page_index: int = 0,
+            viewport_size: Optional[Dict[str, int]] = None,
+    ) -> DriverWrapper:
+        """
+        Connect to a remote browser via Chrome DevTools Protocol.
+
+        Creates a connection to the specified CDP endpoint and wraps the resulting
+        driver in a :class:`DriverWrapper`. Useful for testing Electron applications,
+        connecting to cloud browser services, or attaching to an already-running
+        browser instance.
+
+        **Playwright engine:**
+
+        Starts a Playwright instance internally and connects via
+        ``chromium.connect_over_cdp``. The Playwright instance is stopped
+        automatically when :meth:`quit` is called.
+
+        .. note::
+            Some Playwright features are unavailable in CDP mode:
+            ``record_har_path`` and ``record_video_dir`` cannot be set on pre-existing contexts.
+            Network interception may also be limited.
+
+        **Selenium engine:**
+
+        Creates a Chrome WebDriver with ``debugger_address`` option pointing
+        to the CDP endpoint.
+
+        :param endpoint_url: CDP endpoint URL (e.g., ``"http://localhost:9222"``).
+        :type endpoint_url: str
+        :param engine: The engine to use for the connection. ``"playwright"`` or ``"selenium"``.
+        :type engine: str
+        :param timeout: Connection timeout in milliseconds (Playwright only).
+        :type timeout: int
+        :param page_index: Index of the page to use from the connected context
+          (default: 0, Playwright only).
+        :type page_index: int
+        :param viewport_size: Optional viewport size dict ``{"width": int, "height": int}``.
+        :type viewport_size: typing.Optional[typing.Dict[str, int]]
+        :return: Initialized :class:`DriverWrapper` connected to the remote browser.
+        :rtype: DriverWrapper
+        """
+        if engine == 'playwright':
+            return cls._connect_cdp_playwright(endpoint_url, timeout, page_index, viewport_size)
+        elif engine == 'selenium':
+            return cls._connect_cdp_selenium(endpoint_url, viewport_size)
+        else:
+            raise DriverWrapperException(f'Unsupported engine "{engine}". Use "playwright" or "selenium".')
+
+    @classmethod
+    def _connect_cdp_playwright(
+            cls,
+            endpoint_url: str,
+            timeout: int,
+            page_index: int,
+            viewport_size: Optional[Dict[str, int]],
+    ) -> DriverWrapper:
+        """
+        Create a Playwright CDP connection and wrap it in a :class:`DriverWrapper`.
+
+        :param endpoint_url: CDP endpoint URL.
+        :type endpoint_url: str
+        :param timeout: Connection timeout in milliseconds.
+        :type timeout: int
+        :param page_index: Index of the page to use from the connected context.
+        :type page_index: int
+        :param viewport_size: Optional viewport dimensions.
+        :type viewport_size: typing.Optional[typing.Dict[str, int]]
+        :return: Initialized :class:`DriverWrapper`.
+        :rtype: DriverWrapper
+        """
+        pw = sync_playwright().start()
+        browser = pw.chromium.connect_over_cdp(endpoint_url, timeout=timeout)
+        context = browser.contexts[0]
+        page = context.pages[page_index]
+
+        if viewport_size:
+            page.set_viewport_size(viewport_size)
+
+        driver = Driver(driver=page, context=context, instance=browser)
+        wrapper = cls(driver)
+        wrapper._playwright_instance = pw
+        wrapper.is_cdp = True
+        return wrapper
+
+    @classmethod
+    def _connect_cdp_selenium(
+            cls,
+            endpoint_url: str,
+            viewport_size: Optional[Dict[str, int]],
+    ) -> DriverWrapper:
+        """
+        Create a Selenium CDP connection and wrap it in a :class:`DriverWrapper`.
+
+        Imports are deferred to avoid requiring Chrome-specific Selenium packages
+        when only Playwright is used.
+
+        :param endpoint_url: CDP endpoint URL.
+        :type endpoint_url: str
+        :param viewport_size: Optional viewport dimensions.
+        :type viewport_size: typing.Optional[typing.Dict[str, int]]
+        :return: Initialized :class:`DriverWrapper`.
+        :rtype: DriverWrapper
+        """
+        from selenium.webdriver.chrome.options import Options as ChromeOptions
+        from selenium.webdriver.chrome.webdriver import WebDriver as ChromeWebDriver
+
+        debugger_address = endpoint_url.replace('http://', '').replace('https://', '').rstrip('/')
+
+        options = ChromeOptions()
+        options.debugger_address = debugger_address
+
+        selenium_driver = ChromeWebDriver(options=options)
+
+        if viewport_size:
+            selenium_driver.set_window_size(viewport_size['width'], viewport_size['height'])
+
+        driver = Driver(driver=selenium_driver)
+        wrapper = cls(driver)
+        wrapper.is_cdp = True
+        return wrapper
+
     def quit(self, silent: bool = False, trace_path: str = 'trace.zip'):
         """
         Quit the driver instance.
@@ -191,6 +321,10 @@ def quit(self, silent: bool = False, trace_path: str = 'trace.zip'):
         self._base_cls.quit(self, trace_path)
         self.session.remove_session(self)
 
+        if getattr(self, '_playwright_instance', None):
+            self._playwright_instance.stop()
+            self._playwright_instance = None
+
     def save_screenshot(
             self,
             file_name: str,

mops/playwright/play_driver.py

@@ -174,14 +174,21 @@ def quit(self, silent: bool = False, trace_path: str = 'trace.zip'):
 
         :return: :obj:`None`
         """
-        if trace_path:
+        if trace_path and not self.is_cdp:
             try:
                 self.context.tracing.stop(path=trace_path)
             except PlaywrightError:
                 pass
 
-        self._base_driver.close()
-        self.context.close()
+        try:
+            self._base_driver.close()
+        except PlaywrightError:
+            pass
+
+        try:
+            self.context.close()
+        except PlaywrightError:
+            pass
 
     def set_cookie(self, cookies: List[dict]) -> PlayDriver:
         """
@@ -313,7 +320,10 @@ def get_inner_window_size(self) -> Size:
 
         :return: The size of the inner window as a :class:`.Size` object.
         """
-        return Size(**self.driver.viewport_size)
+        viewport = self.driver.viewport_size
+        if viewport is None:
+            return Size(width=0, height=0)
+        return Size(**viewport)
 
     def get_window_size(self) -> Size:
         """