gamesheet_sdk.common.browser

Reusable Playwright browser session for the JS-heavy WebUI path.

Sibling of gamesheet_sdk.common.session with matching shape: - One context owning cookies and localStorage. - Storage state persisted via Config.browser_state_path. - Base-URL resolution against Config.base_url. - Context-manager that saves state on exit. Browsers are heavyweight, so BrowserSession starts Playwright lazily on first reach for the browser; bare construction is free.

Classes

BrowserSession

A Playwright-driven session for the JavaScript-heavy code path.

class gamesheet_sdk.common.browser.BrowserSession

Bases: object

A Playwright-driven session for the JavaScript-heavy code path.

Mirror of gamesheet_sdk.Session for flows where requests is not enough (single-page apps, anti-bot challenges, anything that needs a real engine to render).

Example:

from gamesheet_sdk import BrowserSession, Config
with BrowserSession(Config()) as bs:
    page = bs.goto("/login")
    page.fill("input[name='email']", "...")

Initialize a browser session without starting Playwright.

Stores the configuration and sets up internal state for lazy browser initialization. Playwright and Chromium are only launched when context or goto() is first accessed. This makes construction cheap and allows sessions that never reach for the browser (e.g. configuration-only runs) to avoid the startup overhead.

Parameters:

config (Config | None) – Optional configuration object. If None, a default Config is created.

__init__(config=None)

Initialize a browser session without starting Playwright.

Stores the configuration and sets up internal state for lazy browser initialization. Playwright and Chromium are only launched when context or goto() is first accessed. This makes construction cheap and allows sessions that never reach for the browser (e.g. configuration-only runs) to avoid the startup overhead.

Parameters:

config (Config | None) – Optional configuration object. If None, a default Config is created.

property context: BrowserContext

The underlying Playwright BrowserContext.

Starts Playwright and launches Chromium on first access, so a BrowserSession that never reaches for the browser is effectively free.

Returns:

The active browser context.

Return type:

BrowserContext

Raises:

• RuntimeError – If the session has already been closed.

• ValueError – If the browser failed to start (defensive check).

new_page()

Open a fresh tab in the session’s context and return it.

Starts Playwright and Chromium on first call if not already running. :returns: Return value. :rtype: Page

Return type:

Page

goto(url, **kwargs)

Open a fresh tab navigated to url.

url may be absolute or a path relative to Config.base_url. Starts Playwright and Chromium on first call if not already running.

Example:

with BrowserSession() as bs:
    page = bs.goto("/login", wait_until="networkidle")
    page.fill("input[name='email']", "test@example.com")

Parameters:

• url (str) – An absolute or relative URL to navigate to.

• kwargs (Any) – Additional keyword arguments passed to playwright.sync_api.Page.goto().

Returns:

A Page navigated to the resolved URL.

Return type:

Page

save()

Persist the current storage state to Config.browser_state_path.

No-op if the browser has not been started yet (there is nothing to save) or if close() has already been called.

close()

Persist storage state and shut Playwright down.

Idempotent: calling close() more than once is safe.