Selenium on Ocarina — précis

02.05.01 — Test[Driver]

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

02.05.01 — `Test[Driver]`#

Fichier source : 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 paramètres :

Paramètre	Type	Rôle
`name`	`TestName` (`str`)	Label humain ; apparaît dans le rapport, et devient le nom du fichier de log (donc soumis à `is_valid_filename`).
`test_id`	`str \| None`	Identifiant stable pour `--only` / `--exclude`. Si absent : prend `name`.
`test_scenario`	`TestScenario[Driver]` (alias = `Callable[[Driver, ILogger], Scenario[Driver]]`)	Factory qui construit le `Scenario` au moment de l’exécution.
`pre_test_scenarios_fragments`	`Sequence[TestScenarioFragment[Driver]] \| None`	Fonctions `(driver, logger) -> TestChain` exécutées avant le scénario principal.
`post_test_scenarios_fragments`	`Sequence[TestScenarioFragment[Driver]] \| None`	Fonctions `(driver, logger) -> TestChain` exécutées après le scénario principal.
`skipped`	`bool`	Si `True`, le test est enregistré mais pas exécuté.

1. `@final`#

Pas d’héritage utilisateur. Si l’on veut un test « spécial », on compose via les fragments ou via un scénario, on ne sous-classe pas.

04.01 — Stratégie « dehors comme un utilisateur »

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

04.01 — Stratégie « dehors comme un utilisateur »#

C’est la posture documentée dès le conftest.py des tests scénarios. Aucun test ne triche en regardant les internes.

`tests/scenarios/conftest.py`#

Composant	Rôle
`FakeDriver` (dataclass)	Driver minimaliste : `title`, `disposed`. Aucune méthode Selenium.
`make_built_driver()`	Factory `(FakeDriver, dispose)`, soit la signature attendue par `WebDriversPool`.
`make_pool(max_size=2)`	`WebDriversPool[FakeDriver]` prêt à l’emploi.
`RecordingPOM(POMBase)`	POM qui consigne ses appels et peut être configuré pour lever.
`acting(pom, step)`	`ActionSuccess[RecordingPOM]` complet (failure+success en no-op).
`scenario_of("ok", "ok2")`	`TestScenario[FakeDriver]` à N steps.
`failing_scenario(step="boom", exc=...)`	Scénario à 1 step qui lève.
`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 qui exécute un `ChainRunner` et retourne le `ActionChain`.

`FakeDriver`#

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

C’est tout. Le cœur d’Ocarina n’appelle aucune API Selenium.

02.10.02 — DriverBuilder[Driver]

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

02.10.02 — `DriverBuilder[Driver]`#

Fichier source : src/ocarina/infra/driver_builder.py

Encapsule la gestion du profil (souvent une copie tmp d’un répertoire utilisateur) et produit la paire (driver, dispose) attendue par la pool.

Pourquoi un builder ?#

Quand on construit un driver Selenium avec un profil, il faut :

Copier le profil dans un dossier temporaire (sinon Firefox/Chrome locked sur le profil original).
Lancer le driver en pointant vers le dossier temporaire.
À la fin : driver.quit() puis supprimer le dossier temporaire.

DriverBuilder factorise ces trois étapes :

00.03 — Flux d'exécution global d'une campagne e2e

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

00.03 — Flux d’exécution global d’une campagne e2e#

Un python -u src/main.py … lancé sur l’une des deux suites (ocarina-example ou ocarina-with-ai-example) déclenche cette chaîne :

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 dépendances externes
           - 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) si 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()                  (optionnel)
              │                             ├─ watchers.start()         (daemon threads)
              │                             ├─ chain_runners            (DSL Railway)
              │                             ├─ watchers.stop()
              │                             └─ teardown()               (toujours)
              ├─ campaigns (main)
              │  (skippées si un smoke a fail)
              │
SUT   ────────┼────────────────────────────────────────────────────────────
              │
              ▼
       Selenium WebDriver ⇄ navigateur réel
       parfois : OTP HTTP GET + Redis (côté ocarina-example)
              │
              ▼
       (6) run_plugins(results)
              ├─ generate_docx_proof  (lit l'arbre de logs, fabrique des .docx)
              ├─ generate_json_results (sérialise results en .json)
              ├─ d'autres si déclarés (parallélisés via ThreadPoolExecutor)
              │
              ▼
       (6') post_exec(results)
              ├─ pretty_print_results (ANSI, hiérarchique)
              └─ has_test_cycle_failed → sys.exit(1) le cas échéant

Détail des étapes#

(1) Parse CLI#

create_selenium_auto_cli_store() détecte l’OS via platform.system() :

02.10.03 — Screenshotter[TDriver]

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

02.10.03 — `Screenshotter[TDriver]`#

Fichier source : src/ocarina/infra/screenshotter.py

Utilitaire de capture d’écran générique, thread-safe, agnostique du driver via un Protocol, configurable via une dataclass. Supporte le burst.

`Protocol`#

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

C’est tout. N’importe quel objet qui a une méthode save_screenshot(path: str) -> bool est utilisable. Selenium WebDriver l’a nativement (driver.save_screenshot), Playwright peut être wrappé, un fake driver en test l’expose trivialement.

`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

Champ	Type	Rôle	Default
`output_dir`	`Path`	Répertoire des screenshots	—
`file_ext`	`str`	Extension (`.png`, `.jpg`)	`.png`
`health_check`	`HealthCheck[TDriver] \| None`	`(driver) -> None` qui lève si driver mort	`None`
`save_full_page`	`SaveFullPageScreenshot[TDriver] \| None`	`(driver, path) -> bool` pour les screenshots pleine page (Firefox uniquement)	`None`
`default_burst_delay`	`float`	Délai entre 2 shots en mode burst	`0.5`s
`max_filename_retries`	`int`	Max essais pour générer un nom unique	`500`
`uuid_length`	`int`	Longueur du suffix UUID dans le nom	`8`

Immutable. On configure une fois et on exporte.

02.11.03 — Auto CLI store + flags + validation

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

02.11.03 — Auto CLI store + flags + validation#

Fichier source : src/ocarina/opinionated/cli/selenium/create_cli_store.py

Flags#

Flag	Default	Type	Validation
`--driver-path`	`""`	`str`	`is_file` (sauf `--browser safari`)
`--profile-path`	`None`	`str`	`is_none` OR `is_dir`
`--browser`	`None` (requis)	`str`	`choices` argparse (par OS)
`--not-headless`	`False` (= headless par défaut)	`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",
]

Ces clés sont l’unique vocabulaire du store. Les call-sites les utilisent : store.get("workers"), store.get("browser"), etc.

10.04 — Workflows ocarina-with-ai-example

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

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

Voir aussi ../08-ai-example/09-ci-matrix.md

Vue d’ensemble#

Workflow	Trigger	OS	Effet	Note
`ai_proof_ci.yml`	push main, PR, dispatch	ubuntu × py 3.14	`ruff format src/ --check` + `ruff check src/` + `mypy src/`	Gate PR, rapide
`ai_proof_e2e.yml`	dispatch	ubuntu × matrice firefox+chrome	warm-up Heroku + run + sed filter ChromeDriver C++ stacks + upload	Manuel uniquement

Différences avec `ocarina-example`#

Aspect	`ocarina-example`	`ocarina-with-ai-example`
Matrice browser	Firefox seul (e2e.yml)	Firefox + Chrome (parallélisés)
SUT	Igoristan (GitHub Pages)	CURA (Heroku eco-dyno)
Pre-run	warm-up Redis client	warm-up Heroku dyno
Filtre output	aucun	sed filtre les stack frames C++ ChromeDriver
`WAIT_TIMEOUT`	default 10	15 (compense les latences Heroku)

warm-up Heroku#

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 — Posture politique du projet

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

01.05 — Posture politique du projet#

Le Holy Book ne sépare pas la philosophie de la politique du dépôt lui-même. Cinq engagements opérationnels en découlent.

1. Incorruptibilité#

« Transmettre Ocarina, c’est transmettre une voiture dont j’ai fait tout l’entretien moi-même, pour moi-même, donc très précautionneusement. En revanche, elle est et restera transmise telle quelle. C’est ma voiture. »

« J’y ai canalisé toute ma colère, pour y mettre tout mon amour. »

02.10.05 — Adapters Selenium

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

02.10.05 — Adapters Selenium#

Dossier source : src/ocarina/infra/selenium/

Tout ce qui matérialise les abstractions (POMBase, WebDriversPool, Screenshotter) en version Selenium. Vit hors du DSL pur — et depuis la 1.1.3 il a un jumeau : src/ocarina/infra/playwright/ livre exactement les mêmes contrats en version Playwright. Changer de backend, c’est désormais choisir un dossier, pas l’écrire.

Fichiers du dossier#

Fichier	Rôle
`create_driver.py`	`_build_firefox`, `_build_chrome`, `_build_edge`, `_build_safari` + dispatch
`create_drivers_pool.py`	`create_selenium_drivers_pool` (utilise `DriverBuilder` + `WebDriversPool`)
`create_screenshotter.py`	`create_selenium_screenshotter` + `_selenium_save_full_page` (Firefox-only)
`driver_healthcheck.py`	`driver_healthcheck(driver)` — ping `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:
    # … identique à Chrome avec EdgeService/EdgeOptions/Edge …


def _build_safari(*, profile_path, driver_path, headless, wait_timeout) -> WebDriver:
    # … Safari ne supporte ni driver_path (utilise safaridriver natif macOS),
    #   ni profile_path (pas de profile custom), ni headless …

1. `implicitly_wait` défini une seule fois#

Chaque builder appelle driver.implicitly_wait(wait_timeout) une fois. Donc, tout find_element qui ne trouve pas l’élément immédiatement attend jusqu’à wait_timeout secondes avant de lever NoSuchElementException.

02.07 — Watcher[Driver]

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

02.07 — `Watcher[Driver]`#

Fichier source : src/ocarina/dsl/testing/watcher.py

Observateur parallélisé qui tourne en daemon thread aux côtés de la test_chain. Conçu pour détecter les frictions imprévisibles et sans impact direct sur le scénario qui se produisent pendant que le scénario tourne : toasts d’erreur aléatoires, validations parasites, popups inattendus.

Le problème#

Citation du Holy Book (handling-flakiness) :

Plus surprenant encore : des applications affichant des toasts d’erreur sans raison apparente, ou des formulaires signalant des erreurs de validation sur des saisies pourtant correctes, sans pour autant bloquer le parcours.

07.07 — HumanizedDriver

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

07.07 — `HumanizedDriver`#

Fichier source : src/lib/ext/selenium/humanize/proxy.py

Proxy pattern : wrappe un WebDriver Selenium et intercepte uniquement find_element* pour retourner des WebElement qui font des send_keys humanisés (frappe lente avec typos, hésitations, 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. Hérite de `WebDriver`#

class HumanizedDriver(WebDriver):

HumanizedDriver passe le type check isinstance(x, WebDriver).

02.08 — POMBase

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

02.08 — `POMBase`#

Fichier source : src/ocarina/pom/base.py

Base abstraite framework-agnostic du Page Object Model. Deux méthodes obligatoires. Aucune mention de Selenium.

Code#

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

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

Six octets de contrat (les deux signatures). C’est tout.

Pourquoi deux méthodes#

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

But : prouver qu’on est sur la bonne page. Sinon, lève.

L’argument timeout permet d’attendre jusqu’à un certain temps que la page se charge (utile pour les Selenium WebDriverWait).
Le default None laisse l’implémentation choisir (typiquement, lire depuis get_timeout() qui lit la CLI).
Le retour Self permet le method chaining fluide (MyPage(...).open().verify().click()).

C’est l’unique méthode dont on a vraiment besoin Test-side pour garantir que « je suis bien sur la page que je veux ». Toutes les actions (click_xxx, enter_xxx) sont laissées à la 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`#

Deux workflows. PR rapide (lint+typecheck). e2e manuel avec matrice Firefox/Chrome + warm-up Heroku + filtrage stacktrace ChromeDriver.

`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 similar ...

Analyse#

`fail-fast: false`#

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

fail-fast: false = si Firefox fail, Chrome continue. Indispensable pour ce projet : la valeur du run est de voir les deux browsers, même si l’un fail.

Chapitre 02.10 — Infrastructure

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

Chapitre 02.10 — Infrastructure#

Tout ce qui touche aux ressources externes : pool de drivers, builders, screenshotters, compteur d’acts, et les adapters Selenium qui implémentent ces abstractions. Depuis la 1.1.3, un infra/playwright/ parallèle livre les mêmes contrats en saveur Playwright — même pool, même builder, mêmes ports.

Plan#

#	Fichier	Sujet
01	`01-drivers-pool.md`	`WebDriversPool[Driver]` : `Semaphore`, `Queue`, `warmup` avec watchdog, `shutdown`.
02	`02-driver-builder.md`	`DriverBuilder[Driver]` : gestion du profile et tmp dirs.
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`	L’acteur `PlaywrightDriver` : thread propriétaire, marshallisation par `submit`, `call_timeout` de liveness, warmup cross-thread, Watcher observe-only.

`BuiltWebDriver[Driver]`#

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

C’est l’unité d’échange entre le builder et la pool : un tuple (driver, dispose). Le dispose est un Effect (sans argument, sans retour) qui sait nettoyer ce driver précisément (driver.quit() + suppression du profile tmp si nécessaire).

02.12 — Custom types & custom errors

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

02.12 — Custom types & custom errors#

Couche shape d’Ocarina. Aucune logique : juste des types, des alias, des exceptions, des protocols. C’est ce qui rend le DSL typé sans logique runtime additionnelle.

`custom_types/`#

Fichier	Contenu
`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]`

Tous ces fichiers sont excluded de la couverture (pyproject.toml#tool.coverage) :

Selenium on Ocarina — précis

02.05.01 — Test[Driver]

02.05.01 — Test[Driver]#

Signature#

1. @final#

04.01 — Stratégie « dehors comme un utilisateur »

04.01 — Stratégie « dehors comme un utilisateur »#

tests/scenarios/conftest.py#

FakeDriver#

02.10.02 — DriverBuilder[Driver]

02.10.02 — DriverBuilder[Driver]#

Pourquoi un builder ?#

00.03 — Flux d'exécution global d'une campagne e2e

00.03 — Flux d’exécution global d’une campagne e2e#

Détail des étapes#

(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 — Workflows ocarina-with-ai-example

10.04 — Workflows ocarina-with-ai-example#

Vue d’ensemble#

Différences avec ocarina-example#

warm-up Heroku#

01.05 — Posture politique du projet

01.05 — Posture politique du projet#

1. Incorruptibilité#

02.10.05 — Adapters Selenium

02.10.05 — Adapters Selenium#

Fichiers du dossier#

create_driver.py#

1. implicitly_wait défini une seule fois#

02.07 — Watcher[Driver]

02.07 — Watcher[Driver]#

Le problème#

07.07 — HumanizedDriver

07.07 — HumanizedDriver#

Code#

1. Hérite de WebDriver#

02.08 — POMBase

02.08 — POMBase#

Code#

Pourquoi deux méthodes#

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#

Analyse#

fail-fast: false#

Chapitre 02.10 — Infrastructure

Chapitre 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 — Workflows `ocarina-with-ai-example`#

Différences avec `ocarina-example`#

`create_driver.py`#

1. `implicitly_wait` défini une seule fois#

02.07 — `Watcher[Driver]`#

07.07 — `HumanizedDriver`#

1. Hérite de `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/`#