je_web_runner.api.frontend

Façade: device emulation / geo locale / multi-tab / shadow / storybook / state diff / pom codegen / visual review.

class je_web_runner.api.frontend.BrowserStateSnapshot(cookies: Dict[str, ~typing.Dict[str, ~typing.Any]]=<factory>, local_storage: Dict[str, str]=<factory>, session_storage: Dict[str, str]=<factory>)

Bases: object

One snapshot of cookies + localStorage + sessionStorage.

cookies: Dict[str, Dict[str, Any]]

local_storage: Dict[str, str]

session_storage: Dict[str, str]

exception je_web_runner.api.frontend.DeviceEmulationError

Bases: WebRunnerException

Raised when an unknown preset is requested or driver isn’t supported.

class je_web_runner.api.frontend.DevicePreset(name: 'str', width: 'int', height: 'int', device_scale_factor: 'float', is_mobile: 'bool', has_touch: 'bool', user_agent: 'str')

Bases: object

device_scale_factor: float

has_touch: bool

height: int

is_mobile: bool

name: str

user_agent: str

width: int

class je_web_runner.api.frontend.DiscoveredElement(name: 'str', strategy: 'str', value: 'str', tag: 'str', source: 'str')

Bases: object

name: str

source: str

strategy: str

tag: str

value: str

exception je_web_runner.api.frontend.GeoLocaleError

Bases: WebRunnerException

Raised when override parameters are invalid or driver unsupported.

class je_web_runner.api.frontend.GeoOverride(latitude: 'Optional[float]' = None, longitude: 'Optional[float]' = None, accuracy_meters: 'float' = 50.0, timezone: 'Optional[str]' = None, locale: 'Optional[str]' = None)

Bases: object

accuracy_meters: float = 50.0

latitude: float | None = None

locale: str | None = None

longitude: float | None = None

timezone: str | None = None

validate() → None

exception je_web_runner.api.frontend.MultiTabError

Bases: WebRunnerException

Raised when a tab alias is unknown or driver does not support windows.

exception je_web_runner.api.frontend.PomCodegenError

Bases: WebRunnerException

Raised on invalid input or duplicate-key conflicts.

exception je_web_runner.api.frontend.ShadowPierceError

Bases: WebRunnerException

Raised when the driver doesn’t expose a JS evaluation surface.

class je_web_runner.api.frontend.SnapshotOutcome(story_id: 'str', image_path: 'Path', matched_baseline: 'bool', diff_percent: 'float' = 0.0, note: 'Optional[str]' = None)

Bases: object

diff_percent: float = 0.0

image_path: Path

matched_baseline: bool

note: str | None = None

story_id: str

class je_web_runner.api.frontend.StateChanges(added: 'Dict[str, Any]'=<factory>, removed: 'Dict[str, Any]'=<factory>, changed: 'Dict[str, Tuple[Any, Any]]'=<factory>)

Bases: object

added: Dict[str, Any]

changed: Dict[str, Tuple[Any, Any]]

property has_changes: bool

removed: Dict[str, Any]

class je_web_runner.api.frontend.StateDiff(cookies: 'StateChanges' = <factory>, local_storage: 'StateChanges' = <factory>, session_storage: 'StateChanges' = <factory>)

Bases: object

cookies: StateChanges

property has_changes: bool

local_storage: StateChanges

session_storage: StateChanges

exception je_web_runner.api.frontend.StateDiffError

Bases: WebRunnerException

Raised when capture / diff input is invalid.

exception je_web_runner.api.frontend.StorybookError

Bases: WebRunnerException

Raised when Storybook metadata can’t be parsed.

exception je_web_runner.api.frontend.StorybookSnapshotError

Bases: WebRunnerException

Raised when iteration / capture / compare fails.

class je_web_runner.api.frontend.StorybookSnapshotReport(outcomes: 'List[SnapshotOutcome]' = <factory>)

Bases: object

property failures: List[SnapshotOutcome]

outcomes: List[SnapshotOutcome]

property passed: bool

class je_web_runner.api.frontend.StorybookStory(id: 'str', title: 'str', name: 'str', kind: 'str' = 'story', parameters: 'Optional[Dict[str, Any]]' = None)

Bases: object

id: str

property iframe_path: str: Storybook serves stories on /iframe.html?id=<id>&viewMode=story.

kind: str = 'story'

name: str

parameters: Dict[str, Any] | None = None

title: str

class je_web_runner.api.frontend.TabChoreographer(tabs: Dict[str, ~je_web_runner.utils.multi_tab.choreographer.TabHandle]=<factory>)

Bases: object

Track and switch between named browser tabs.

aliases() → List[str]

close(driver: Any, alias: str) → None

open_new(driver: Any, alias: str, url: str | None = None) → TabHandle: Open a fresh blank tab and register it under alias.

register_current(driver: Any, alias: str) → TabHandle

switch_to(driver: Any, alias: str) → TabHandle

tabs: Dict[str, TabHandle]

with_tab(driver: Any, alias: str, action: Callable[[Any], Any]) → Any: Run action(driver) while the given alias is active.

class je_web_runner.api.frontend.TabHandle(alias: 'str', handle: 'str')

Bases: object

alias: str

handle: str

class je_web_runner.api.frontend.VirtualAuthenticator(authenticator_id: 'str', protocol: 'str' = 'ctap2', transport: 'str' = 'internal', has_resident_key: 'bool' = True, has_user_verification: 'bool' = True, is_user_verified: 'bool' = True)

Bases: object

authenticator_id: str

has_resident_key: bool = True

has_user_verification: bool = True

is_user_verified: bool = True

protocol: str = 'ctap2'

transport: str = 'internal'

exception je_web_runner.api.frontend.VisualReviewError

Bases: WebRunnerException

Raised when accept / list operations fail.

class je_web_runner.api.frontend.VisualReviewServer(baseline_dir: str, current_dir: str, host: str = '127.0.0.1', port: int = 0)

Bases: object

HTTP server that powers the review UI.

start() → str

stop() → None

exception je_web_runner.api.frontend.WebAuthnError

Bases: WebRunnerException

Raised when CDP doesn’t surface the WebAuthn domain or call fails.

je_web_runner.api.frontend.accept_baseline(baseline_dir: str, current_dir: str, name: str) → Path: Copy current_dir/name over baseline_dir/name (creating dir).

je_web_runner.api.frontend.add_credential(driver: Any, authenticator: VirtualAuthenticator, credential: Dict[str, Any]) → None

je_web_runner.api.frontend.apply_overrides(driver: Any, override: GeoOverride) → List[str]: 對 Selenium driver 透過 execute_cdp_cmd 套用所有 override Issue every CDP command from cdp_payloads(). Returns the list of method names actually invoked.

je_web_runner.api.frontend.apply_to_chrome_options(options: Any, preset_name: str) → Any: Add Chrome --window-size / --user-agent for a Selenium ChromeOptions.

je_web_runner.api.frontend.assert_no_visual_regressions(report: StorybookSnapshotReport, allow_stories: Iterable[str] | None = None) → None

je_web_runner.api.frontend.assert_pierced_visible(driver: Any, css_selector: str) → None: Raise unless at least one matching node is found in the shadow tree.

je_web_runner.api.frontend.available_presets() → List[str]

je_web_runner.api.frontend.capture_state(driver: Any) → BrowserStateSnapshot: 抓 driver 當下的 cookies + localStorage + sessionStorage Take a snapshot. Selenium drivers expose get_cookies directly; Playwright pages expose them on page.context.cookies().

je_web_runner.api.frontend.capture_story_snapshots(stories: Iterable[StorybookStory], base_url: str, *, output_dir: str | Path, take_screenshot: Callable[[str], bytes], navigate: Callable[[str], None], baseline_dir: str | Path | None = None, comparator: Callable[[bytes, Path], Dict[str, Any]] | None = None) → StorybookSnapshotReport: 對每個 story 截圖並（可選）跟 baseline 比對；回傳 StorybookSnapshotReport。

je_web_runner.api.frontend.cdp_emulation_command(preset_name: str) → Dict[str, Any]: Return the CDP Emulation.setDeviceMetricsOverride payload.

je_web_runner.api.frontend.cdp_payloads(override: GeoOverride) → List[Dict[str, Any]]: Return a list of (method, params) CDP commands.

je_web_runner.api.frontend.clear_credentials(driver: Any, authenticator: VirtualAuthenticator) → None

je_web_runner.api.frontend.diff_states(before: BrowserStateSnapshot, after: BrowserStateSnapshot) → StateDiff

je_web_runner.api.frontend.discover_elements_from_html(html: str) → List[DiscoveredElement]: Collect every wrap-worthy element from the HTML snapshot.

je_web_runner.api.frontend.discover_stories(source: str | Path | Dict[str, Any], skip_examples: bool = True) → List[StorybookStory]: 從 index.json / stories.json 抽出每個 story 的最小描述 Read a Storybook index file (or in-memory dict) and return the list of stories. skip_examples filters the Example/Introduction story that the default-init template ships with.

je_web_runner.api.frontend.enable_virtual_authenticator(driver: Any, protocol: str = 'ctap2', transport: str = 'internal', has_resident_key: bool = True, has_user_verification: bool = True, is_user_verified: bool = True) → VirtualAuthenticator: 啟用 WebAuthn domain 並新增一個 virtual authenticator Enable the WebAuthn CDP domain and register a fresh virtual authenticator. Returns a VirtualAuthenticator whose authenticator_id callers must pass back for credential mgmt.

je_web_runner.api.frontend.filter_stories_by_kind(stories: Iterable[StorybookStory], kind_prefix: str) → List[StorybookStory]: Return stories whose title starts with kind_prefix.

je_web_runner.api.frontend.find_all(driver: Any, css_selector: str, limit: int = 1000) → List[Any]: Return up to limit matching nodes across the shadow tree.

je_web_runner.api.frontend.find_first(driver: Any, css_selector: str) → Any: 從 document 起遞迴穿透 open shadow roots 找第一個符合 CSS 選擇器的節點。 Return the first node matching css_selector anywhere in the document, walking through open shadow roots. None when no match.

je_web_runner.api.frontend.get_preset(name: str) → DevicePreset

je_web_runner.api.frontend.list_credentials(driver: Any, authenticator: VirtualAuthenticator) → List[Dict[str, Any]]

je_web_runner.api.frontend.list_diffs(baseline_dir: str, current_dir: str) → List[Dict[str, str]]: Return [{name, status}] for every paired snapshot.

je_web_runner.api.frontend.plan_actions_for_stories(stories: Iterable[StorybookStory], base_url: str, *, run_a11y: bool = True, capture_screenshot: bool = True, extra_per_story: Sequence[List[Any]] | None = None) → List[List[Any]]: 對每個 story 產生 [navigate, optional a11y, optional screenshot, extras]。 Build a flat action list that visits each story under base_url and optionally runs the axe-core audit + screenshot. extra_per_story is appended verbatim after the per-story block.

je_web_runner.api.frontend.playwright_context_kwargs(override: GeoOverride) → Dict[str, Any]: Return new_context kwargs for Playwright.

je_web_runner.api.frontend.playwright_kwargs(preset_name: str) → Dict[str, Any]: Return new_context kwargs for Playwright.

je_web_runner.api.frontend.register_preset(preset: DevicePreset) → None: Replace or add a preset by name.

je_web_runner.api.frontend.remove_virtual_authenticator(driver: Any, authenticator: VirtualAuthenticator) → None

je_web_runner.api.frontend.render_index(baseline_dir: str, current_dir: str) → str

je_web_runner.api.frontend.render_pom_module(elements: Sequence[DiscoveredElement], class_name: str = 'WebRunnerPage') → str: Render a Python module string defining class_name.

je_web_runner.api.frontend.safe_filename(story: StorybookStory) → str: Convert components-button--primary -> components-button--primary.png.

je_web_runner.api.frontend.set_user_verified(driver: Any, authenticator: VirtualAuthenticator, is_user_verified: bool) → None