Skip to content

Automate browser based workflows with AI

Bind richer per-selected-engine browser error families (RUS-5) (#7801)

LawyZheng3746821034af
diff --git a/skyvern/webeye/browser_engine.py b/skyvern/webeye/browser_engine.py
index 74df5e95c..691dfbb5e 100644
--- a/skyvern/webeye/browser_engine.py
+++ b/skyvern/webeye/browser_engine.py
@@ -26,6 +26,7 @@ import importlib.metadata
from dataclasses import dataclass, field
from typing import Awaitable, Callable
+import structlog
from playwright.async_api import Error as _PlaywrightError
from playwright.async_api import Playwright
from playwright.async_api import TimeoutError as _PlaywrightTimeoutError
@@ -39,8 +40,11 @@ from skyvern.webeye.browser_errors import (
classify_browser_error,
)
+LOG = structlog.get_logger()
+
BrowserDriverStarter = Callable[[], Awaitable[Playwright]]
BrowserEngineErrorLoader = Callable[[], "tuple[type[BaseException], type[BaseException]]"]
+BrowserEngineRichErrorLoader = Callable[[], "BrowserEngineRichErrorTypes"]
STOCK_ENGINE_NAME = "playwright"
RUSTWRIGHT_ENGINE_NAME = "rustwright"
@@ -105,6 +109,21 @@ class BrowserEngineMetadata:
return self.allowed_browser_sources is None or browser_source in self.allowed_browser_sources
+@dataclass(frozen=True)
+class BrowserEngineRichErrorTypes:
+ """Native identities for the richer taxonomy families a driver package exposes, beyond the
+ base+timeout pair every driver has. A spec's rich loader imports these lazily from the driver
+ package (never at spec construction); each family is optional — an empty tuple means the engine
+ exposes no distinct native class for it (its detection, if any, is left to a predicate-based
+ boundary), never a silent downgrade. Carried onto the selection so ``classify_error`` can preserve
+ target-closed / CDP-transport / retryable distinctions instead of flattening them into the base.
+ """
+
+ target_closed_types: tuple[type[BaseException], ...] = ()
+ cdp_connection_types: tuple[type[BaseException], ...] = ()
+ retryable_types: tuple[type[BaseException], ...] = ()
+
+
@dataclass(frozen=True)
class BrowserEngineSelection:
"""A single run's pinned engine. Immutable; created once and carried through the browser
@@ -118,10 +137,17 @@ class BrowserEngineSelection:
timeout_error_type: type[BaseException]
metadata: BrowserEngineMetadata
selection_reason: str
- # Derived once from the two identities above (which ``select()`` loaded lazily from the driver
+ # The richer taxonomy families' native identities, loaded lazily by ``select()`` from the driver
+ # package alongside the base+timeout pair. Each defaults empty: an engine that exposes no distinct
+ # native class for a family (e.g. stock Playwright has no dedicated CDP-transport class) simply
+ # leaves it unbound. A directly-constructed selection with none of these still binds base+timeout.
+ target_closed_error_types: tuple[type[BaseException], ...] = ()
+ cdp_connection_error_types: tuple[type[BaseException], ...] = ()
+ retryable_error_types: tuple[type[BaseException], ...] = ()
+ # Derived once from the identities above (which ``select()`` loaded lazily from the driver
# package), never passed in: the immutable error-family binding that ``classify_error`` uses. The
- # base+timeout pair is the stable public identity every driver exposes; richer families would be
- # supplied here only if a package exposed additional stable public identities.
+ # base+timeout pair is the stable public identity every driver exposes; the richer families are
+ # populated only for the native classes the selected engine actually exposes.
error_families: BrowserEngineErrorFamilies = field(init=False)
def __post_init__(self) -> None:
@@ -135,16 +161,37 @@ class BrowserEngineSelection:
f"timeout identity {self.timeout_error_type.__name__} must be {self.error_type.__name__} or a "
f"subclass of it; got an incompatible hierarchy for engine {self.name!r}"
)
+ # Invariant: every richer-family native identity must itself be a subclass of the engine's base
+ # error, so a positive classification implies is_engine_error — the selection can never match a
+ # foreign engine's class into one of its own families. A richer type outside the base family
+ # would let classification fire on an error this engine did not raise (foreign-engine false
+ # classification); fail loudly rather than bind it. Stdlib/transport errors that are not engine
+ # errors belong to a predicate at the boundary, not to these native-identity bindings.
+ for family_name, types in (
+ ("target_closed_error_types", self.target_closed_error_types),
+ ("cdp_connection_error_types", self.cdp_connection_error_types),
+ ("retryable_error_types", self.retryable_error_types),
+ ):
+ for entry in types:
+ if not (isinstance(entry, type) and issubclass(entry, self.error_type)):
+ raise BrowserErrorFamiliesConfigError(
+ f"{family_name} entry {entry!r} must be a subclass of the engine's base error "
+ f"{self.error_type.__name__} for engine {self.name!r}"
+ )
# A real driver's timeout is a distinct subclass of its base error, so both identities occupy
# separate families. Only when an engine reports the same class for both (base is the timeout)
# is the base entry dropped: the class already appears in the more-specific timeout family,
- # which classification checks first, and a native type may live in only one family.
+ # which classification checks first, and a native type may live in only one family. The richer
+ # families' one-type-per-family / disjointness checks are enforced by BrowserEngineErrorFamilies.
base_error_types = () if self.error_type is self.timeout_error_type else (self.error_type,)
object.__setattr__(
self,
"error_families",
BrowserEngineErrorFamilies(
timeout_types=(self.timeout_error_type,),
+ target_closed_types=self.target_closed_error_types,
+ cdp_connection_types=self.cdp_connection_error_types,
+ retryable_types=self.retryable_error_types,
base_error_types=base_error_types,
),
)
@@ -195,10 +242,21 @@ class BrowserEngineSpec:
_start_driver: BrowserDriverStarter
_load_error_types: BrowserEngineErrorLoader
allowed_browser_sources: frozenset[str] | None = None
+ # Optional lazy loader for the richer taxonomy families' native identities. ``None`` means the
+ # engine binds only base+timeout (the richer families stay empty). Like ``_load_error_types`` it
+ # is never called at spec construction, so a spec for an absent engine stays inert until selected.
+ _load_rich_error_types: BrowserEngineRichErrorLoader | None = None
def is_installed(self) -> bool:
+ # Validate BOTH loaders under the one installed/unavailable contract: an engine whose base
+ # driver imports but whose richer-family identities do not (e.g. a private target-closed module
+ # drifts) is NOT usable, because select() would fail closed on that same import. Reporting it
+ # installed would let a default resolver pick it and then have select() raise; validating both
+ # here keeps is_installed() and select() consistent so the default falls back instead.
try:
self._load_error_types()
+ if self._load_rich_error_types is not None:
+ self._load_rich_error_types()
return True
except ImportError:
return False
@@ -206,13 +264,18 @@ class BrowserEngineSpec:
def select(self, *, selection_reason: str) -> BrowserEngineSelection:
try:
error_type, timeout_error_type = self._load_error_types()
+ rich = self._load_rich_error_types() if self._load_rich_error_types is not None else None
except ImportError as exc:
raise BrowserEngineUnavailable(self.name) from exc
+ rich = rich if rich is not None else BrowserEngineRichErrorTypes()
return BrowserEngineSelection(
name=self.name,
start_driver=self._start_driver,
error_type=error_type,
timeout_error_type=timeout_error_type,
+ target_closed_error_types=rich.target_closed_types,
+ cdp_connection_error_types=rich.cdp_connection_types,
+ retryable_error_types=rich.retryable_types,
metadata=BrowserEngineMetadata(
name=self.name,
version=resolve_engine_version(self.name),
@@ -255,6 +318,35 @@ def _stock_error_types() -> tuple[type[BaseException], type[BaseException]]:
return _PlaywrightError, _PlaywrightTimeoutError
+def _stock_rich_error_types() -> BrowserEngineRichErrorTypes:
+ # Stock Playwright exposes a distinct native target-closed class; it has no dedicated native class
+ # for CDP-transport or retryable failures (those are message/stdlib-shaped and detected by a
+ # predicate at the boundary, not bound here), so those families stay empty. The target-closed class
+ # lives in a PRIVATE module (playwright._impl._errors) with no API-stability guarantee, imported
+ # lazily here so it never resolves at module import.
+ #
+ # Stock is the always-on default path (the OSS default resolver selects it unguarded, and cloud
+ # falls back to it as last resort), so its richer-family binding must never make stock globally
+ # unavailable. Target-closed detection is additive/best-effort, so if a future Playwright bump
+ # moves or drops that private module we degrade to empty rich families (base+timeout, from the
+ # stable public surface, still bind) with a warning — rather than fail select() and break browser
+ # creation for every run. The except is narrow (ImportError from this one optional import); it is
+ # stock-specific and does NOT relax the fail-loud contract for non-stock/explicitly-selected engines.
+ try:
+ from playwright._impl._errors import TargetClosedError as PlaywrightTargetClosedError
+ except ImportError:
+ LOG.warning(
+ "playwright_private_target_closed_import_unavailable",
+ detail=(
+ "playwright._impl._errors.TargetClosedError could not be imported (likely a Playwright "
+ "upgrade moved it); stock engine binds no target-closed family this run. Base and "
+ "timeout families are unaffected."
+ ),
+ )
+ return BrowserEngineRichErrorTypes()
+ return BrowserEngineRichErrorTypes(target_closed_types=(PlaywrightTargetClosedError,))
+
+
async def _start_rustwright_driver() -> Playwright:
from rustwright.async_api import async_playwright as rustwright_async_playwright
@@ -268,11 +360,23 @@ def _rustwright_error_types() -> tuple[type[BaseException], type[BaseException]]
return RustwrightError, RustwrightTimeoutError
+def _rustwright_rich_error_types() -> BrowserEngineRichErrorTypes:
+ # Rustwright (evaluated at rev f4d8091 / 0.1.0a2) exposes a public ``TargetClosedError`` that
+ # subclasses its base ``Error`` and is disjoint from ``TimeoutError`` — same shape as stock. Like
+ # stock it exposes no distinct native CDP-transport or retryable class (its dead-port connect
+ # errors land on the base ``Error`` family), so those stay empty. Imported lazily: this is never
+ # called until a run selects rustwright, so an image lacking the package stays inert.
+ from rustwright.async_api import TargetClosedError as RustwrightTargetClosedError
+
+ return BrowserEngineRichErrorTypes(target_closed_types=(RustwrightTargetClosedError,))
+
+
PLAYWRIGHT_SPEC = BrowserEngineSpec(
name=STOCK_ENGINE_NAME,
_start_driver=_start_stock_driver,
_load_error_types=_stock_error_types,
allowed_browser_sources=None,
+ _load_rich_error_types=_stock_rich_error_types,
)
RUSTWRIGHT_SPEC = BrowserEngineSpec(
@@ -280,6 +384,7 @@ RUSTWRIGHT_SPEC = BrowserEngineSpec(
_start_driver=_start_rustwright_driver,
_load_error_types=_rustwright_error_types,
allowed_browser_sources=RUSTWRIGHT_ALLOWED_BROWSER_SOURCES,
+ _load_rich_error_types=_rustwright_rich_error_types,
)
REGISTRY = BrowserEngineRegistry()
diff --git a/tests/unit/test_browser_engine.py b/tests/unit/test_browser_engine.py
index cda9d81a3..b7b08fa4a 100644
--- a/tests/unit/test_browser_engine.py
+++ b/tests/unit/test_browser_engine.py
@@ -11,9 +11,11 @@ from __future__ import annotations
import asyncio
import dataclasses
import re
+import sys
from pathlib import Path
import pytest
+from playwright._impl._errors import TargetClosedError as PlaywrightTargetClosedError
from playwright.async_api import Error as PlaywrightError
from playwright.async_api import TimeoutError as PlaywrightTimeoutError
@@ -24,16 +26,21 @@ from skyvern.webeye.browser_engine import (
BrowserEngineContext,
BrowserEngineMetadata,
BrowserEngineRegistry,
+ BrowserEngineRichErrorTypes,
BrowserEngineSelection,
BrowserEngineSpec,
+ BrowserEngineUnavailable,
BrowserSourceNotSupportedByEngine,
UnknownBrowserEngine,
resolve_browser_engine,
)
from skyvern.webeye.browser_errors import (
BrowserAutomationError,
+ BrowserCdpConnectionError,
BrowserEngineErrorFamilies,
BrowserErrorFamiliesConfigError,
+ BrowserRetryableCdpError,
+ BrowserTargetClosedError,
BrowserTimeoutError,
)
@@ -65,12 +72,18 @@ def _selection(
*,
allowed_sources: frozenset[str] | None = None,
start=_never_start,
+ target_closed_types: tuple[type[BaseException], ...] = (),
+ cdp_connection_types: tuple[type[BaseException], ...] = (),
+ retryable_types: tuple[type[BaseException], ...] = (),
) -> BrowserEngineSelection:
return BrowserEngineSelection(
name=name,
start_driver=start,
error_type=error_type,
timeout_error_type=timeout_type,
+ target_closed_error_types=target_closed_types,
+ cdp_connection_error_types=cdp_connection_types,
+ retryable_error_types=retryable_types,
metadata=BrowserEngineMetadata(name=name, version="0.0.0", allowed_browser_sources=allowed_sources),
selection_reason="test",
)
@@ -123,6 +136,26 @@ def test_rustwright_spec_fails_closed_when_driver_absent():
spec.select(selection_reason="explicit-rustwright")
+def test_rustwright_spec_has_rich_error_loader_wired_and_lazy():
+ # Every candidate engine (not just stock) binds the richer families: the rustwright spec carries a
+ # rich loader. It must stay lazy — importing this module registered the spec without importing the
+ # (absent) rustwright package, so the loader is only invoked at select().
+ spec = browser_engine.REGISTRY.get(browser_engine.RUSTWRIGHT_ENGINE_NAME)
+ assert spec._load_rich_error_types is browser_engine._rustwright_rich_error_types
+ assert "rustwright" not in sys.modules # registering the spec never imported the driver
+
+
+def test_rustwright_rich_loader_imports_the_real_driver_and_fails_closed_when_absent():
+ # The rich loader binds the REAL native identity (a lazy ``from rustwright.async_api import
+ # TargetClosedError``), not a stub: with the package absent it raises ModuleNotFoundError naming
+ # the driver, and select() surfaces that as BrowserEngineUnavailable (never silent empty families).
+ with pytest.raises(ModuleNotFoundError) as excinfo:
+ browser_engine._rustwright_rich_error_types()
+ assert excinfo.value.name == "rustwright"
+ with pytest.raises(browser_engine.BrowserEngineUnavailable):
+ browser_engine.RUSTWRIGHT_SPEC.select(selection_reason="explicit-rustwright")
+
+
# Representative neutral source strings (not a canonical source registry — that belongs to the cloud
# wiring slice). Deny-all is source-independent: it must reject whatever source it is handed, so the
# sample only needs to be varied, including the ``None`` unattributed case.
@@ -373,6 +406,291 @@ def test_unrelated_base_and_timeout_identities_reject_construction():
_selection("engine-unrelated", error_type=_Base, timeout_type=_Unrelated)
+# --- S34: richer per-selection error-family binding ---------------------------------------------
+#
+# A fake engine whose native classes span every richer family. Each subclasses the engine base error
+# (an engine's own target-closed/CDP/retryable errors are engine errors), and retryable subclasses
+# CDP-connection so a single instance matches both families via inheritance — this is what proves the
+# classifier's retryable-before-CDP precedence survives the selection binding.
+class _RichEngineError(Exception):
+ pass
+
+
+class _RichEngineTimeout(_RichEngineError):
+ pass
+
+
+class _RichTargetClosed(_RichEngineError):
+ pass
+
+
+class _RichCdpConnection(_RichEngineError):
+ pass
+
+
+class _RichRetryable(_RichCdpConnection):
+ pass
+
+
+def _rich_selection() -> BrowserEngineSelection:
+ return _selection(
+ "engine-rich",
+ _RichEngineError,
+ _RichEngineTimeout,
+ target_closed_types=(_RichTargetClosed,),
+ cdp_connection_types=(_RichCdpConnection,),
+ retryable_types=(_RichRetryable,),
+ )
+
+
+def test_stock_selection_binds_target_closed_family_from_native_identity():
+ # Stock Playwright exposes a distinct native target-closed class; the selection must bind it as a
+ # target-closed family (previously it was flattened into the base error family).
+ sel = browser_engine.REGISTRY.get(STOCK_ENGINE_NAME).select(selection_reason="test")
+ assert sel.error_families.target_closed_types == (PlaywrightTargetClosedError,)
+ assert sel.target_closed_error_types == (PlaywrightTargetClosedError,)
+ # Stock has no dedicated native CDP-transport/retryable class: those families stay empty (bound by
+ # a boundary predicate later, not here), never silently merged into base.
+ assert sel.error_families.cdp_connection_types == ()
+ assert sel.error_families.retryable_types == ()
+
+
+def test_stock_selection_classifies_native_target_closed_with_full_fidelity():
+ # The bug this slice closes: classify must return the specific BrowserTargetClosedError, not a
+ # flattened BrowserAutomationError, preserving the native error as __cause__.
+ sel = browser_engine.REGISTRY.get(STOCK_ENGINE_NAME).select(selection_reason="test")
+ native = PlaywrightTargetClosedError("target page closed")
+ classified = sel.classify_error(native)
+ assert type(classified) is BrowserTargetClosedError
+ assert classified.__cause__ is native
+
+
+def test_rich_selection_binds_all_families_from_native_identities():
+ sel = _rich_selection()
+ fam = sel.error_families
+ assert fam.timeout_types == (_RichEngineTimeout,)
+ assert fam.target_closed_types == (_RichTargetClosed,)
+ assert fam.cdp_connection_types == (_RichCdpConnection,)
+ assert fam.retryable_types == (_RichRetryable,)
+ assert fam.base_error_types == (_RichEngineError,)
+
+
+def test_rich_selection_classify_preserves_family_precedence():
+ # retryable -> target-closed -> timeout -> cdp-connection -> base, exactly as browser_errors defines
+ # it; the retryable/CDP pair verifies the most-specific-first ordering under inheritance.
+ sel = _rich_selection()
+ retry = _RichRetryable("transient disconnect")
+ assert type(sel.classify_error(retry)) is BrowserRetryableCdpError
+ assert sel.classify_error(retry).__cause__ is retry
+ assert type(sel.classify_error(_RichCdpConnection("transport"))) is BrowserCdpConnectionError
+ assert type(sel.classify_error(_RichTargetClosed("closed"))) is BrowserTargetClosedError
+ assert type(sel.classify_error(_RichEngineTimeout("slow"))) is BrowserTimeoutError
+ assert type(sel.classify_error(_RichEngineError("boom"))) is BrowserAutomationError
+
+
+def test_rich_selection_does_not_classify_foreign_engine_errors():
+ # Engine isolation: a rich engine's families must never fire on another engine's native errors,
+ # even a foreign target-closed/retryable-looking one; the caller must re-raise (None).
+ sel = _rich_selection()
+ assert sel.classify_error(_EngineAError("foreign base")) is None
+ assert sel.classify_error(_EngineATimeout("foreign timeout")) is None
+ assert sel.classify_error(ValueError("unrelated")) is None
+
+
+def test_spec_rich_loader_is_lazy_and_populates_families_via_select():
+ # The rich loader is never called at spec construction (lazy, like _load_error_types) and only
+ # runs at select(); the resulting selection carries the richer families.
+ calls: list[str] = []
+
+ def _load_rich() -> BrowserEngineRichErrorTypes:
+ calls.append("rich")
+ return BrowserEngineRichErrorTypes(
+ target_closed_types=(_RichTargetClosed,),
+ cdp_connection_types=(_RichCdpConnection,),
+ retryable_types=(_RichRetryable,),
+ )
+
+ spec = BrowserEngineSpec(
+ name="engine-rich",
+ _start_driver=_never_start,
+ _load_error_types=lambda: (_RichEngineError, _RichEngineTimeout),
+ _load_rich_error_types=_load_rich,
+ )
+ assert calls == [] # constructing the spec imported nothing
+ sel = spec.select(selection_reason="test")
+ assert calls == ["rich"]
+ assert sel.error_families.retryable_types == (_RichRetryable,)
+ assert sel.error_families.target_closed_types == (_RichTargetClosed,)
+
+
+def test_spec_without_rich_loader_binds_only_base_and_timeout():
+ # Optional empty families: a spec that supplies no rich loader still selects, with the richer
+ # families empty (backward-compatible with engines that only expose base+timeout).
+ spec = BrowserEngineSpec(
+ name="engine-plain",
+ _start_driver=_never_start,
+ _load_error_types=lambda: (_EngineAError, _EngineATimeout),
+ )
+ sel = spec.select(selection_reason="test")
+ assert sel.error_families.target_closed_types == ()
+ assert sel.error_families.cdp_connection_types == ()
+ assert sel.error_families.retryable_types == ()
+ assert sel.error_families.timeout_types == (_EngineATimeout,)
+
+
+def test_spec_rich_loader_import_error_fails_closed():
+ # A rich loader that cannot import its driver package fails closed at select() (BrowserEngine
+ # Unavailable), exactly like the base loader — never a silent fallback to empty families.
+ def _load_rich() -> BrowserEngineRichErrorTypes:
+ raise ImportError("driver package absent")
+
+ spec = BrowserEngineSpec(
+ name="engine-absent-rich",
+ _start_driver=_never_start,
+ _load_error_types=lambda: (_EngineAError, _EngineATimeout),
+ _load_rich_error_types=_load_rich,
+ )
+ with pytest.raises(BrowserEngineUnavailable):
+ spec.select(selection_reason="test")
+
+
+def test_is_installed_false_when_rich_loader_import_fails_though_base_imports():
+ # is_installed() validates BOTH loaders: an engine whose base driver imports but whose richer-family
+ # identities do not (e.g. a private target-closed module drifts) is NOT usable — select() would fail
+ # closed on that same import — so a default resolver keying on is_installed() must skip it, not pick
+ # it and then have select() raise. Base imports fine here; only the rich loader is broken.
+ def _load_rich() -> BrowserEngineRichErrorTypes:
+ raise ImportError("private rich-family module drifted")
+
+ spec = BrowserEngineSpec(
+ name="engine-rich-drift",
+ _start_driver=_never_start,
+ _load_error_types=lambda: (_EngineAError, _EngineATimeout),
+ _load_rich_error_types=_load_rich,
+ )
+ assert spec.is_installed() is False
+ # And the contract stays consistent: explicit selection of the same drifted engine fails loud.
+ with pytest.raises(BrowserEngineUnavailable):
+ spec.select(selection_reason="explicit")
+
+
+def test_is_installed_true_when_both_loaders_import_and_stays_lazy_until_probed():
+ # With both loaders importable, is_installed() is True. Neither loader runs at construction (lazy);
+ # both run only when is_installed() probes them.
+ calls: list[str] = []
+
+ def _load_base() -> tuple[type[BaseException], type[BaseException]]:
+ calls.append("base")
+ return _RichEngineError, _RichEngineTimeout
+
+ def _load_rich() -> BrowserEngineRichErrorTypes:
+ calls.append("rich")
+ return BrowserEngineRichErrorTypes(target_closed_types=(_RichTargetClosed,))
+
+ spec = BrowserEngineSpec(
+ name="engine-both",
+ _start_driver=_never_start,
+ _load_error_types=_load_base,
+ _load_rich_error_types=_load_rich,
+ )
+ assert calls == [] # construction imported nothing
+ assert spec.is_installed() is True
+ assert calls == ["base", "rich"] # is_installed probed both loaders
+
+
+def test_is_installed_true_with_no_rich_loader():
+ # A spec that supplies no rich loader is installed as long as its base loader imports (backward
+ # compatible with engines that only expose base+timeout).
+ spec = BrowserEngineSpec(
+ name="engine-base-only",
+ _start_driver=_never_start,
+ _load_error_types=lambda: (_EngineAError, _EngineATimeout),
+ )
+ assert spec.is_installed() is True
+
+
+def test_stock_spec_rich_loader_import_is_lazy_not_module_level():
+ # Regression: the stock target-closed identity is imported inside the rich loader, not at module
+ # scope, so importing browser_engine never resolves the private playwright._impl._errors module.
+ source = Path(browser_engine.__file__).read_text()
+ assert "_PlaywrightTargetClosedError" not in source
+ assert "from playwright._impl._errors import" in source # present, but only inside the loader body
+ # The installed stock spec still resolves the identity when probed/selected.
+ assert browser_engine.PLAYWRIGHT_SPEC.is_installed() is True
+ sel = browser_engine.PLAYWRIGHT_SPEC.select(selection_reason="test")
+ assert sel.error_families.target_closed_types == (PlaywrightTargetClosedError,)
+
+
+def test_stock_selection_degrades_when_private_target_closed_import_moves(monkeypatch):
+ # The stock engine is the always-on default path (OSS default resolver + cloud last-resort
+ # fallback), so a Playwright bump that moves the PRIVATE playwright._impl._errors module must NOT
+ # make stock globally unavailable. Simulate the module being gone: select() still succeeds, the
+ # stable public base+timeout stay bound, and the target-closed family degrades to empty (best
+ # effort) instead of raising BrowserEngineUnavailable.
+ monkeypatch.setitem(sys.modules, "playwright._impl._errors", None)
+ assert browser_engine.PLAYWRIGHT_SPEC.is_installed() is True
+ sel = browser_engine.PLAYWRIGHT_SPEC.select(selection_reason="test")
+ assert sel.name == STOCK_ENGINE_NAME
+ assert sel.error_families.target_closed_types == ()
+ assert sel.error_families.timeout_types == (PlaywrightTimeoutError,)
+ assert sel.error_families.base_error_types == (PlaywrightError,)
+
+
+async def test_default_resolver_survives_private_target_closed_import_move(monkeypatch):
+ # The OSS default resolver calls stock select() UNGUARDED by is_installed(); a moved private
+ # target-closed module must not turn every default run into BrowserEngineUnavailable.
+ monkeypatch.setitem(sys.modules, "playwright._impl._errors", None)
+ sel = await resolve_browser_engine(BrowserEngineContext(browser_source="local-browser"))
+ assert sel.name == STOCK_ENGINE_NAME
+ assert sel.error_families.target_closed_types == ()
+
+
+def test_nonstock_rich_loader_stays_fail_loud_when_its_import_moves():
+ # Degradation is stock-SPECIFIC: a non-stock engine whose rich loader raises ImportError still
+ # fails closed (is_installed False + select raises), so an explicitly selected or misconfigured
+ # engine never silently loses fidelity. This guards against broadening the stock best-effort path.
+ def _load_rich() -> BrowserEngineRichErrorTypes:
+ raise ImportError("private module moved")
+
+ spec = BrowserEngineSpec(
+ name="engine-nonstock",
+ _start_driver=_never_start,
+ _load_error_types=lambda: (_EngineAError, _EngineATimeout),
+ _load_rich_error_types=_load_rich,
+ )
+ assert spec.is_installed() is False
+ with pytest.raises(BrowserEngineUnavailable):
+ spec.select(selection_reason="explicit")
+
+
+def test_rich_family_type_outside_base_family_rejects_construction():
+ # Fail-loud invariant: a richer-family native type that is NOT a subclass of the engine base error
+ # would let classification fire on a foreign error; reject it at construction.
+ with pytest.raises(BrowserErrorFamiliesConfigError):
+ _selection("engine-bad", _RichEngineError, _RichEngineTimeout, target_closed_types=(_EngineAError,))
+
+
+def test_rich_family_type_duplicated_across_families_rejects_construction():
+ # A native type may belong to only one family; binding the same class as both CDP-connection and
+ # retryable must fail loudly (enforced by BrowserEngineErrorFamilies, surfaced at selection build).
+ with pytest.raises(BrowserErrorFamiliesConfigError):
+ _selection(
+ "engine-dup",
+ _RichEngineError,
+ _RichEngineTimeout,
+ cdp_connection_types=(_RichCdpConnection,),
+ retryable_types=(_RichCdpConnection,),
+ )
+
+
+def test_rich_family_type_colliding_with_base_rejects_construction():
+ # Binding the engine base error itself into a richer family collides with the derived base family;
+ # reject rather than silently shadow the base-error classification.
+ with pytest.raises(BrowserErrorFamiliesConfigError):
+ _selection("engine-base-collide", _RichEngineError, _RichEngineTimeout, target_closed_types=(_RichEngineError,))
+
+
async def _ok_start():
return object()