Selenium on Ocarina — manual

02.05.01 — Test[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.05.01 — `Test[Driver]`#

Source file: src/ocarina/dsl/testing/oc_test.py

Signature#

@final
class Test[Driver]:
    def __init__(
        self,
        *,
        name: TestName,
        test_id: str | None = None,
        test_scenario: TestScenario[Driver],
        pre_test_scenarios_fragments: Sequence[TestScenarioFragment[Driver]] | None = None,
        post_test_scenarios_fragments: Sequence[TestScenarioFragment[Driver]] | None = None,
        skipped: bool = False,
    ) -> None:
        if test_id is None:
            test_id = name
        self.name = name
        self.test_id = test_id
        self._test_scenario = test_scenario
        self._pre_test_scenarios_fragments = pre_test_scenarios_fragments or []
        self._post_test_scenarios_fragments = post_test_scenarios_fragments or []
        self._skipped = skipped

Six parameters:

Parameter	Type	Role
`name`	`TestName` (`str`)	Human label; appears in the report, and becomes the log file name (hence subject to `is_valid_filename`).
`test_id`	`str \| None`	Stable identifier for `--only` / `--exclude`. If absent: takes `name`.
`test_scenario`	`TestScenario[Driver]` (alias = `Callable[[Driver, ILogger], Scenario[Driver]]`)	Factory that builds the `Scenario` at execution time.
`pre_test_scenarios_fragments`	`Sequence[TestScenarioFragment[Driver]] \| None`	`(driver, logger) -> TestChain` functions executed before the main scenario.
`post_test_scenarios_fragments`	`Sequence[TestScenarioFragment[Driver]] \| None`	`(driver, logger) -> TestChain` functions executed after the main scenario.
`skipped`	`bool`	If `True`, the test is registered but not executed.

1. `@final`#

No user inheritance. Want a “special” test? Compose via fragments or a scenario — don’t subclass.

04.01 — From the outside like a user strategy

Wed, 20 May 2026 00:00:00 +0000

04.01 — "From the outside like a user" strategy#

The posture lives in the scenario tests’ conftest.py. No test cheats by peeking at internals.

`tests/scenarios/conftest.py`#

Component	Role
`FakeDriver` (dataclass)	Minimal driver: `title`, `disposed`. No Selenium method.
`make_built_driver()`	Factory `(FakeDriver, dispose)`, i.e. the signature `WebDriversPool` expects.
`make_pool(max_size=2)`	`WebDriversPool[FakeDriver]` ready to go.
`RecordingPOM(POMBase)`	POM that records its calls and can be configured to raise.
`acting(pom, step)`	Full `ActionSuccess[RecordingPOM]` (failure+success as no-ops).
`scenario_of("ok", "ok2")`	`TestScenario[FakeDriver]` with N steps.
`failing_scenario(step="boom", exc=...)`	1-step scenario that raises.
`make_test(name, scenario=..., test_id=..., skipped=False)`	`Test[FakeDriver]`
`make_suite(name, tests, pool=..., transient_errors=..., max_retries_per_test=...)`	`TestSuite[FakeDriver]`
`make_campaign(name, suites, max_workers=1)`	`TestCampaign[FakeDriver]`
`make_cycle(name="cycle", campaigns=..., smoke=..., mode=...)`	`TestCycle[FakeDriver]`
`run_chain(runner)`	Helper that executes a `ChainRunner` and returns the `ActionChain`.

`FakeDriver`#

@dataclass
class FakeDriver:
    title: str = "fake"
    disposed: bool = False

That’s all. Ocarina’s core calls no Selenium API.

02.10.02 — DriverBuilder[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.10.02 — `DriverBuilder[Driver]`#

Source file: src/ocarina/infra/driver_builder.py

Encapsulates profile handling (often a tmp copy of a user directory) and produces the (driver, dispose) pair the pool expects.

Why a builder?#

Building a Selenium driver with a profile requires:

Copy the profile to a temp folder (otherwise Firefox/Chrome locks the original).
Start the driver pointing at the temp folder.
At the end: driver.quit(), then delete the temp folder.

DriverBuilder factors out those three steps:

00.03 — End-to-end execution flow of an e2e campaign

Wed, 20 May 2026 00:00:00 +0000

00.03 — End-to-end execution flow of an e2e campaign#

Run python -u src/main.py … on either suite (ocarina-example or ocarina-with-ai-example) and this chain kicks off:

USER  ────────────────────────────────────────────────────────────────────
       python -u src/main.py --browser firefox --workers 3 [...]
              │
              ▼
       (1) parse CLI
           CliStoreSingleton.push(create_selenium_auto_cli_store())
              │
              ▼
       (2) build pool
           create_selenium_drivers_pool(max_size=N)
              │
              ▼
       (3) warm up external dependencies
           - Redis (ocarina-example)
           - Heroku dyno (ai-example, via curl --retry 6)
              │
              ▼
       (4) bootstrap(
              test_cycle  = create_e2e_test_cycle(drivers_pool),
              run_plugins = lambda results: run_plugins(
                                generate_docx_proof, generate_json_results,
                                exceptions_logger=...),
              post_exec   = pretty_print_results + sys.exit(1) on fail
           )
              │
OCARINA  ─────┼──────────────────────────────────────────────────────────
              │
              ▼
       (5) TestCycle.run_all (saturate_workers=True)
              ├─ smoke_tests_campaigns      [mode: fail-fast | wait-for-all]
              │     └─ TestCampaign.run_all
              │           └─ TestSuite.run (max_workers, saturate_workers)
              │                 └─ ThreadPoolExecutor → TestFlow.run
              │                       └─ pool.acquire() → TestExecutor.execute
              │                             ├─ setup()                  (optional)
              │                             ├─ watchers.start()         (daemon threads)
              │                             ├─ chain_runners            (Railway DSL)
              │                             ├─ watchers.stop()
              │                             └─ teardown()               (always)
              ├─ campaigns (main)
              │  (skipped if a smoke failed)
              │
SUT   ────────┼────────────────────────────────────────────────────────────
              │
              ▼
       Selenium WebDriver ⇄ real browser
       sometimes: OTP HTTP GET + Redis (on the ocarina-example side)
              │
              ▼
       (6) run_plugins(results)
              ├─ generate_docx_proof  (reads the log tree, builds .docx files)
              ├─ generate_json_results (serializes results to .json)
              ├─ others if declared (parallelized via ThreadPoolExecutor)
              │
              ▼
       (6') post_exec(results)
              ├─ pretty_print_results (ANSI, hierarchical)
              └─ has_test_cycle_failed → sys.exit(1) if applicable

Step-by-step#

(1) Parse CLI#

create_selenium_auto_cli_store() detects the OS via platform.system():

02.10.03 — Screenshotter[TDriver]

Wed, 20 May 2026 00:00:00 +0000

02.10.03 — `Screenshotter[TDriver]`#

Source file: src/ocarina/infra/screenshotter.py

Generic, thread-safe screenshot utility. Driver-agnostic via a Protocol, configurable via a dataclass. Supports burst.

`Protocol`#

class ScreenshotDriver(Protocol):
    def save_screenshot(self, path: str) -> bool:
        """Save standard viewport screenshot."""

That’s it. Any object with save_screenshot(path: str) -> bool qualifies. Selenium WebDriver has it natively (driver.save_screenshot), Playwright can be wrapped, a fake driver in tests exposes it trivially.

`ScreenshotterConfig[TDriver]`#

@dataclass(frozen=True)
class ScreenshotterConfig[TDriver: ScreenshotDriver]:
    output_dir: Path
    file_ext: str = ".png"
    health_check: HealthCheck[TDriver] | None = None
    save_full_page: SaveFullPageScreenshot[TDriver] | None = None
    default_burst_delay: float = 0.5
    max_filename_retries: int = 500
    uuid_length: int = 8

Field	Type	Role	Default
`output_dir`	`Path`	Screenshot directory	—
`file_ext`	`str`	Extension (`.png`, `.jpg`)	`.png`
`health_check`	`HealthCheck[TDriver] \| None`	`(driver) -> None` that raises if the driver is dead	`None`
`save_full_page`	`SaveFullPageScreenshot[TDriver] \| None`	`(driver, path) -> bool` for full-page screenshots (Firefox only)	`None`
`default_burst_delay`	`float`	Delay between 2 shots in burst mode	`0.5`s
`max_filename_retries`	`int`	Max attempts to generate a unique name	`500`
`uuid_length`	`int`	UUID suffix length in the name	`8`

Immutable. Configure once, ship.

02.11.03 — Auto CLI store + flags + validation

Wed, 20 May 2026 00:00:00 +0000

02.11.03 — Auto CLI store + flags + validation#

Source file: src/ocarina/opinionated/cli/selenium/create_cli_store.py

Flags#

Flag	Default	Type	Validation
`--driver-path`	`""`	`str`	`is_file` (except `--browser safari`)
`--profile-path`	`None`	`str`	`is_none` OR `is_dir`
`--browser`	`None` (required)	`str`	argparse `choices` (per OS)
`--not-headless`	`False` (= headless by default)	`bool` (`store_true`)	phantom
`--workers`	`5`	`int`	`is_positive` + `is_not_zero`
`--logger`	`"terminal+file"`	`str`	`choices=LOGGERS_CHOICES`
`--wait-timeout`	`10`	`int`	`≤ 60`, `> 0`
`--dont-force-delete-tmp-dirs`	`False`	`bool` (`store_true`)	phantom
`--only`	`[]`	`list[str]` (`nargs="+"`)	phantom + mutex
`--exclude`	`[]`	`list[str]` (`nargs="+"`)	phantom + mutex

_DEFAULT_WORKERS_AMOUNT = 5
_DEFAULT_LOGGER: SupportedLogger = "terminal+file"
_DEFAULT_BROWSER_AUTOMATION_TIMEOUT = 10
_MAX_BROWSER_AUTOMATION_TIMEOUT = 60

`Literal[...]`#

type SeleniumCliStoreKeys = Literal[
    "driver_path", "profile_path", "browser", "headless", "workers",
    "logger", "wait_timeout", "force_delete_tmp_dirs", "only", "exclude",
]

These keys are the store’s whole vocabulary. Call-sites use them: store.get("workers"), store.get("browser"), etc.

10.04 — ocarina-with-ai-example workflows

Wed, 20 May 2026 00:00:00 +0000

10.04 — `ocarina-with-ai-example` workflows#

See also ../08-ai-example/09-ci-matrix.md

Overview#

Workflow	Trigger	OS	Effect	Note
`ai_proof_ci.yml`	push main, PR, dispatch	ubuntu × py 3.14	`ruff format src/ --check` + `ruff check src/` + `mypy src/`	PR gate, fast
`ai_proof_e2e.yml`	dispatch	ubuntu × firefox+chrome matrix	Heroku warm-up + run + sed filter ChromeDriver C++ stacks + upload	Manual only

Differences vs `ocarina-example`#

Aspect	`ocarina-example`	`ocarina-with-ai-example`
Browser matrix	Firefox only (e2e.yml)	Firefox + Chrome (parallelized)
SUT	Igoristan (GitHub Pages)	CURA (Heroku eco-dyno)
Pre-run	warm-up Redis client	warm-up Heroku dyno
Output filter	none	sed filters ChromeDriver C++ stack frames
`WAIT_TIMEOUT`	default 10	15 (compensates for Heroku latency)

Heroku warm-up#

curl -sf --retry 6 --retry-delay 5 --retry-all-errors \
  --max-time 30 https://katalon-demo-cura.herokuapp.com/ > /dev/null
echo "Dyno is warm"

CURA runs on a Heroku dyno that sleeps after inactivity. Tests hitting a cold dyno produce timeouts (false fails) and slow confirmations (false passes on gap tests). Wake it explicitly before any browser opens.

01.05 — The project's political stance

Wed, 20 May 2026 00:00:00 +0000

01.05 — The project’s political stance#

The Holy Book doesn’t separate philosophy from the politics of the repo itself. Five operating commitments come out of it.

1. Incorruptibility#

Sharing Ocarina means sharing a car I have maintained entirely myself, for myself, therefore with great care. Still, it is shared as-is, and will remain so. It’s my car.

I channeled all my anger into it, to pour all my love into it.

02.10.05 — Selenium adapters

Wed, 20 May 2026 00:00:00 +0000

02.10.05 — Selenium adapters#

Source folder: src/ocarina/infra/selenium/

Everything that materializes the abstractions (POMBase, WebDriversPool, Screenshotter) in Selenium flavor. Lives outside the pure DSL — and since 1.1.3 it has a twin: src/ocarina/infra/playwright/ ships the exact same contracts in Playwright flavor. Swapping backend is now picking a folder, not writing one.

Files in the folder#

File	Role
`create_driver.py`	`_build_firefox`, `_build_chrome`, `_build_edge`, `_build_safari` + dispatch
`create_drivers_pool.py`	`create_selenium_drivers_pool` (uses `DriverBuilder` + `WebDriversPool`)
`create_screenshotter.py`	`create_selenium_screenshotter` + `_selenium_save_full_page` (Firefox-only)
`driver_healthcheck.py`	`driver_healthcheck(driver)` — pings `driver.title`
`mixins.py`	`SeleniumTitleMixin`

`create_driver.py`#

def _build_firefox(*, profile_path, driver_path, headless, wait_timeout) -> WebDriver:
    service = FirefoxService(executable_path=driver_path)
    options = FirefoxOptions()
    if headless:
        options.add_argument("-headless")
    if profile_path:
        options.profile = FirefoxProfile(profile_path)
    driver = Firefox(service=service, options=options)
    driver.implicitly_wait(wait_timeout)
    return driver


def _build_chrome(*, profile_path, driver_path, headless, wait_timeout) -> WebDriver:
    service = ChromeService(executable_path=driver_path)
    options = ChromeOptions()
    if headless:
        options.add_argument("--headless=new")
    if profile_path:
        options.add_argument(f"--user-data-dir={profile_path}")
    driver = Chrome(service=service, options=options)
    driver.implicitly_wait(wait_timeout)
    return driver


def _build_edge(*, profile_path, driver_path, headless, wait_timeout) -> WebDriver:
    # … same as Chrome with EdgeService/EdgeOptions/Edge …


def _build_safari(*, profile_path, driver_path, headless, wait_timeout) -> WebDriver:
    # … Safari supports neither driver_path (uses macOS' native safaridriver),
    #   nor profile_path (no custom profile), nor headless …

1. `implicitly_wait` set only once#

Each builder calls driver.implicitly_wait(wait_timeout) once. Any find_element that doesn’t find the element immediately waits up to wait_timeout seconds before raising NoSuchElementException.

02.07 — Watcher[Driver]

Wed, 20 May 2026 00:00:00 +0000

02.07 — `Watcher[Driver]`#

Source file: src/ocarina/dsl/testing/watcher.py

Parallelized observer running as a daemon thread alongside the test_chain. Built to catch unpredictable frictions with no direct impact on the scenario that pop up while the scenario runs: random error toasts, parasitic validations, unexpected popups.

The problem#

Holy Book quote (First real-world hurdles):

Even more surprisingly: apps displaying error toasts for no apparent reason, or forms flagging validation errors on inputs that are actually correct, without blocking the journey.

07.07 — HumanizedDriver

Wed, 20 May 2026 00:00:00 +0000

07.07 — `HumanizedDriver`#

Source file: src/lib/ext/selenium/humanize/proxy.py

Proxy pattern: wraps a Selenium WebDriver and intercepts only find_element* to return WebElements whose send_keys are humanized (slow typing with typos, hesitations, corrections).

Code#

class HumanizedDriver(WebDriver):
    def __init__(self, driver: WebDriver, **keyboard_config: Unpack[KeyboardConfig]) -> None:
        object.__init__(self)
        self._driver = driver
        self._config = keyboard_config

    def find_element(self, by: str | RelativeBy = "id", value: str | None = None) -> _HumanizedWebElement:
        element = self._driver.find_element(by, value)
        return _HumanizedWebElement(element, self._config)

    def find_elements(self, by: str | RelativeBy = "id", value: str | None = None) -> list[WebElement]:
        elements = self._driver.find_elements(by, value)
        return [_HumanizedWebElement(el, self._config) for el in elements]

    def __getattr__(self, name: str):
        return getattr(self._driver, name)

1. Inherits from `WebDriver`#

class HumanizedDriver(WebDriver):

HumanizedDriver passes isinstance(x, WebDriver) checks.

02.08 — POMBase

Wed, 20 May 2026 00:00:00 +0000

02.08 — `POMBase`#

Source file: src/ocarina/pom/base.py

Framework-agnostic abstract base for the Page Object Model. Two required methods. Zero mention of Selenium.

Code#

class POMBase(ABC):
    @abstractmethod
    def verify(self, *, timeout: float | None = None) -> Self:
        ...

    @abstractmethod
    def get_current_title(self) -> str:
        ...

Six bytes of contract (the two signatures). That’s all.

Why two methods#

`verify(timeout=None) -> Self`#

Purpose: prove we’re on the right page. Otherwise, raise.

timeout lets you wait up to a given time for the page to load (handy for Selenium WebDriverWait).
None default lets the implementation decide (typically reading get_timeout() which reads the CLI).
Returning Self enables fluent method chaining (MyPage(...).open().verify().click()).

The only method test-side that’s truly needed to guarantee “I’m on the page I want.” Everything else (click_xxx, enter_xxx) is on the subclass.

08.09 — CI: ai_proof_ci.yml + ai_proof_e2e.yml

Wed, 20 May 2026 00:00:00 +0000

08.09 — CI: `ai_proof_ci.yml` + `ai_proof_e2e.yml`#

Two workflows. Fast PR (lint+typecheck). Manual e2e with a Firefox/Chrome matrix + Heroku warm-up + ChromeDriver stacktrace filtering.

`ai_proof_ci.yml`#

name: ai_proof CI

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

defaults:
  run:
    shell: bash

jobs:
  lint-and-typecheck:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.14"
          allow-prereleases: true
      - uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
      - name: Install dependencies
        if: steps.cache-venv.outputs.cache-hit != 'true'
        run: |
          python -m venv .venv
          .venv/bin/pip install . ruff mypy mypy-extensions typing-extensions pre-commit

      - name: Ruff format check
        run: .venv/bin/ruff format src/ --check

      - name: Ruff lint
        run: .venv/bin/ruff check src/

      - name: Mypy
        run: .venv/bin/mypy src/

Step	Cmd
Ruff format check	`ruff format src/ --check`
Ruff lint	`ruff check src/`
Mypy	`mypy src/`

`ai_proof_e2e.yml`#

name: ai_proof e2e

on:
  workflow_dispatch:

defaults:
  run:
    shell: bash

jobs:
  e2e:
    name: e2e (${{ matrix.browser }})
    runs-on: ubuntu-latest
    env:
      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
      WAIT_TIMEOUT: 15
    strategy:
      fail-fast: false
      matrix:
        include:
          - browser: firefox
            driver: geckodriver
          - browser: chrome
            driver: chromedriver

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.14"
          allow-prereleases: true
      - uses: actions/cache@v4
        with:
          path: .venv
          key: venv-${{ runner.os }}-py${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('pyproject.toml') }}
      - name: Install dependencies
        if: steps.cache-venv.outputs.cache-hit != 'true'
        run: |
          python -m venv .venv
          .venv/bin/pip install . ruff mypy mypy-extensions typing-extensions pre-commit

      # --- Firefox ---

      - name: Install geckodriver
        if: matrix.browser == 'firefox'
        run: |
          GECKO_VERSION=0.36.0
          wget -q https://github.com/mozilla/geckodriver/releases/download/v$GECKO_VERSION/geckodriver-v$GECKO_VERSION-linux64.tar.gz
          tar -xzf geckodriver-v$GECKO_VERSION-linux64.tar.gz
          chmod +x geckodriver

      - name: Setup Firefox
        if: matrix.browser == 'firefox'
        uses: browser-actions/setup-firefox@fcf821c621167805dd63a29662bd7cb5676c81a8

      # --- Chrome ---

      - name: Install chromedriver
        if: matrix.browser == 'chrome'
        run: |
          CHROME_VER=$(google-chrome-stable --version | grep -oP '\d+\.\d+\.\d+\.\d+')
          wget -q -O chromedriver.zip \
            "https://storage.googleapis.com/chrome-for-testing-public/${CHROME_VER}/linux64/chromedriver-linux64.zip"
          unzip -q chromedriver.zip
          mv chromedriver-linux64/chromedriver ./chromedriver
          chmod +x ./chromedriver

      # --- Warm-up ---

      - name: Warm up Heroku dyno
        run: |
          # CURA runs on a Heroku dyno that sleeps after inactivity.
          # Tests hitting a cold dyno produce timeouts (false fails) and slow
          # confirmations (false passes on gap tests). Wake it explicitly
          # before any browser opens.
          curl -sf --retry 6 --retry-delay 5 --retry-all-errors \
            --max-time 30 https://katalon-demo-cura.herokuapp.com/ > /dev/null
          echo "Dyno is warm"

      # --- Run ---

      - name: Run e2e cycle
        run: |
          # ChromeDriver release builds ship without debug symbols. On errors it
          # dumps raw C++ stack frames ("#N 0x<addr> <unknown>") into the WebDriver
          # response, which Selenium surfaces as the exception message — polluting
          # both the live log and the pretty-print summary with unreadable hex noise.
          # No Python-side fix exists. Strip the frames with sed before they land.
          # pipefail preserves Python's exit code through the pipe.
          set -o pipefail
          .venv/bin/python -u src/main.py \
            --driver-path ./${{ matrix.driver }} \
            --browser ${{ matrix.browser }} \
            --workers 3 \
            --wait-timeout ${{ env.WAIT_TIMEOUT }} \
            --logger terminal+file \
            2>&1 | sed -u \
              -e '/Stacktrace:/{N;/\n#[0-9][0-9]* 0x[0-9a-f][0-9a-f]* <unknown>/{s/Stacktrace:\n[^\n]*/HIDDEN/;b};P;D}' \
              -e '/^#[0-9][0-9]* 0x[0-9a-f][0-9a-f]* <unknown>/d'

      - name: Enumerate traces
        if: always()
        run: |
          sync
          find $GITHUB_WORKSPACE/.screenshots -type f 2>/dev/null || true
          find $GITHUB_WORKSPACE/.ocarina_logs -type f 2>/dev/null || true
          find $GITHUB_WORKSPACE/.reports -type f 2>/dev/null || true

      - name: Upload screenshots
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: screenshots-${{ matrix.browser }}
          path: .screenshots/
          retention-days: 7

      # … upload logs, reports similarly ...

Analysis#

`fail-fast: false`#

strategy:
  fail-fast: false
  matrix:
    include:
      - browser: firefox
      - browser: chrome

fail-fast: false — if Firefox fails, Chrome continues. Essential: the point of the run is seeing both browsers, even when one fails.

Chapter 02.10 — Infrastructure

Wed, 20 May 2026 00:00:00 +0000

Chapter 02.10 — Infrastructure#

Everything that touches external resources: driver pool, builders, screenshotters, act counter, and the Selenium adapters that implement them. Since 1.1.3, a parallel infra/playwright/ ships the same contracts in Playwright flavor — same pool, same builder, same ports.

Plan#

#	File	Subject
01	`01-drivers-pool.md`	`WebDriversPool[Driver]`: `Semaphore`, `Queue`, `warmup` with watchdog, `shutdown`.
02	`02-driver-builder.md`	`DriverBuilder[Driver]`: profile and tmp dirs handling.
03	`03-screenshotter.md`	`Screenshotter[TDriver]` + `ScreenshotterConfig`: burst, healthcheck, threadsafe.
04	`04-act-counter.md`	`ActCounter` + `ThreadsBasedActCounter` (thread-local).
05	`05-selenium-adapters.md`	`create_driver` (Firefox/Chrome/Edge/Safari), `create_drivers_pool`, `create_screenshotter`, `driver_healthcheck`, `SeleniumTitleMixin`.
06	`06-playwright-actor.md`	The `PlaywrightDriver` actor: owner thread, marshalling through `submit`, the `call_timeout` liveness ceiling, cross-thread warmup, observe-only Watcher.

`BuiltWebDriver[Driver]`#

type BuiltWebDriver[Driver] = tuple[Driver, Effect]

The exchange unit between the builder and the pool: a (driver, dispose) tuple. dispose is an Effect (no argument, no return) that knows how to clean up that exact driver (driver.quit() + removal of the tmp profile if needed).

02.12 — Custom types & custom errors

Wed, 20 May 2026 00:00:00 +0000

02.12 — Custom types & custom errors#

Ocarina’s shape layer. No logic — types, aliases, exceptions, protocols. What makes the DSL typed without adding runtime logic.

`custom_types/`#

File	Contents
`effect.py`	`type Effect = Callable[[], None]` + `type Effects = tuple[Effect, ...]`
`thunk.py`	`type Thunk[T] = Callable[[], T]`
`tpom.py`	`TypeVar TPOM bound POMBase`
`supports_write.py`	`Protocol SupportsWrite[T]` (`write(s: T) -> Any`)
`built_web_driver.py`	`type BuiltWebDriver[Driver] = tuple[Driver, Effect]`
`scenario.py`	`Scenario[Driver]` (frozen dataclass)
`test_components.py`	`TestChain`, `TestSetup`, `TestTeardown`, `TestWatchers[Driver]`
`test_runner.py`	`TestRunner[Driver]` (frozen dataclass)
`oc_test.py`	`TestName`, `TestScenario[Driver]`, `TestScenarioFragment[Driver]`
`oc_test_layers.py`	`TestId`, `TestResult`, `TestSuiteResult`, `TestSuiteResults`, `TestCampaignResults`, `TestCycleResults`
`selenium/built_web_driver.py`	`BuiltSeleniumWebDriver = BuiltWebDriver[WebDriver]`
`selenium/oc_test_scenario.py`	`SeleniumTestScenario = TestScenario[WebDriver]`
`selenium/supported_browsers.py`	`type SupportedSeleniumBrowser = Literal["chrome", "firefox", "edge", "safari"]`
`selenium/web_drivers_pool.py`	`type SeleniumWebDriversPool = WebDriversPool[WebDriver]`

All these files are excluded from coverage (pyproject.toml#tool.coverage):

Selenium on Ocarina — manual

02.05.01 — Test[Driver]

02.05.01 — Test[Driver]#

Signature#

1. @final#

04.01 — From the outside like a user strategy

04.01 — "From the outside like a user" strategy#

tests/scenarios/conftest.py#

FakeDriver#

02.10.02 — DriverBuilder[Driver]

02.10.02 — DriverBuilder[Driver]#

Why a builder?#

00.03 — End-to-end execution flow of an e2e campaign

00.03 — End-to-end execution flow of an e2e campaign#

Step-by-step#

(1) Parse CLI#

02.10.03 — Screenshotter[TDriver]

02.10.03 — Screenshotter[TDriver]#

Protocol#

ScreenshotterConfig[TDriver]#

02.11.03 — Auto CLI store + flags + validation

02.11.03 — Auto CLI store + flags + validation#

Flags#

Literal[...]#

10.04 — ocarina-with-ai-example workflows

10.04 — ocarina-with-ai-example workflows#

Overview#

Differences vs ocarina-example#

Heroku warm-up#

01.05 — The project's political stance

01.05 — The project’s political stance#

1. Incorruptibility#

02.10.05 — Selenium adapters

02.10.05 — Selenium adapters#

Files in the folder#

create_driver.py#

1. implicitly_wait set only once#

02.07 — Watcher[Driver]

02.07 — Watcher[Driver]#

The problem#

07.07 — HumanizedDriver

07.07 — HumanizedDriver#

Code#

1. Inherits from WebDriver#

02.08 — POMBase

02.08 — POMBase#

Code#

Why two methods#

verify(timeout=None) -> Self#

08.09 — CI: ai_proof_ci.yml + ai_proof_e2e.yml

08.09 — CI: ai_proof_ci.yml + ai_proof_e2e.yml#

ai_proof_ci.yml#

ai_proof_e2e.yml#

Analysis#

fail-fast: false#

Chapter 02.10 — Infrastructure

Chapter 02.10 — Infrastructure#

Plan#

BuiltWebDriver[Driver]#

02.12 — Custom types & custom errors

02.12 — Custom types & custom errors#

custom_types/#

02.05.01 — `Test[Driver]`#

1. `@final`#

`tests/scenarios/conftest.py`#

`FakeDriver`#

02.10.02 — `DriverBuilder[Driver]`#

02.10.03 — `Screenshotter[TDriver]`#

`Protocol`#

`ScreenshotterConfig[TDriver]`#

`Literal[...]`#

10.04 — `ocarina-with-ai-example` workflows#

Differences vs `ocarina-example`#

`create_driver.py`#

1. `implicitly_wait` set only once#

02.07 — `Watcher[Driver]`#

07.07 — `HumanizedDriver`#

1. Inherits from `WebDriver`#

02.08 — `POMBase`#

`verify(timeout=None) -> Self`#

08.09 — CI: `ai_proof_ci.yml` + `ai_proof_e2e.yml`#

`ai_proof_ci.yml`#

`ai_proof_e2e.yml`#

`fail-fast: false`#

`BuiltWebDriver[Driver]`#

`custom_types/`#