Ocarina on Ocarina — précis

02.03.01 — Le type Result[T]

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

02.03.01 — Le type `Result[T]`#

Fichier source : src/ocarina/railway/result.py — zéro dépendance.

Code#

from dataclasses import dataclass, field
from typing import TypeGuard, final


class _BaseResult:
    """Base class ensuring both Ok and Fail have error attribute for type narrowing."""
    error: Exception | None


@final
@dataclass(frozen=True)
class Ok[T](_BaseResult):
    value: T
    error: None = None


@final
@dataclass(frozen=True)
class Fail(_BaseResult):
    error: Exception = field(default_factory=lambda: Exception("Unknown error"))


type Result[T] = Ok[T] | Fail


def is_ok[T](result: Result[T]) -> TypeGuard[Ok[T]]:
    return isinstance(result, Ok)


def is_fail[T](result: Result[T]) -> TypeGuard[Fail]:
    return isinstance(result, Fail)

Six décisions de design à décortiquer#

1. `_BaseResult` comme parent commun#

class _BaseResult:
    error: Exception | None

But unique : permettre à mypy d’accéder à result.error sans narrowing préalable. Sans cette base, on devrait écrire :

02.04.01 — Le flot validate → assert_that → execute → raise_if_invalid

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

02.04.01 — Le flot `validate → assert_that → execute → raise_if_invalid`#

Fichier source : src/ocarina/dsl/invariants/validate.py (entry-point) + src/ocarina/dsl/invariants/internals/validation_chain.py

La machine à états#

Diagramme#

validate(value: T)
       │
       ▼
ValidationStartBlock[T]
       │
       └─ assert_that(predicate, *, msg=None)
              │
              ▼
       ValidationAssertBlock[T]   ← état qui accepte plusieurs continuations
              │
              ├─► assert_that(P)     [boucle, AND chaînable, voir le diagramme dédié]
              ├─► otherwise(P)       [OR, voir 03-otherwise-any-of.md]
              ├─► then(U, name=...)  [change de valeur, voir 04-then-chain-of-validations.md]
              └─► execute()          → _ValidationResult
                                          │
                                          ├─ is_valid: bool
                                          ├─ errors: Sequence[InvariantViolationError]
                                          ├─ validated_values: Sequence[Any]
                                          └─ raise_if_invalid() : None | raise AggregateInvariantViolationError

Boucle `assert_that`#

assert_that formule une assertion sur la valeur courante. Plusieurs assert_that peuvent se suivre, chacun ajoutant une condition supplémentaire à la chaîne (AND logique, ordre préservé).

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.

02.10.01 — WebDriversPool[Driver]

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

02.10.01 — `WebDriversPool[Driver]`#

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

Pool thread-safe de drivers, max concurrence garantie par sémaphore, warmup asynchrone surveillé, shutdown propre. Pas de réutilisation : chaque acquire() détruit son driver à la fin (état propre).

Constructeur#

@final
class WebDriversPool[Driver]:
    def __init__(
        self,
        create_driver: Thunk[BuiltWebDriver[Driver]],
        max_size: int,
        warmup_timeout: float | None = None,
    ) -> None:
        self._create_driver = create_driver
        self._pool: Queue[BuiltWebDriver[Driver]] = Queue(max_size)
        self._semaphore = Semaphore(max_size)
        self._warmup_timeout = (
            warmup_timeout if warmup_timeout is not None and warmup_timeout > 0.1
            else 60.0 * 5
        )

Primitive	Rôle
`Queue(max_size)`	File des drivers pré-créés disponibles.
`Semaphore(max_size)`	Garantit que jamais plus de `max_size` drivers ne vivent simultanément (qu’ils soient en queue ou acquis).
`warmup_timeout`	Délai max sans progression de warmup avant de lever `WarmupTimeoutError`. Par défaut 300s.

`acquire()`#

@contextmanager
def acquire(self) -> Iterator[Driver]:
    try:
        driver, dispose = self._pool.get_nowait()
    except Empty:
        self._semaphore.acquire()
        try:
            driver, dispose = self._create_driver()
        except Exception:
            self._semaphore.release()
            raise

    try:
        yield driver
    finally:
        with suppress(Exception):
            dispose()
        self._semaphore.release()

              acquire()
                  │
                  ▼
   ┌──────────────────────────────────┐
   │ pool.get_nowait()                │── OK ─► driver, dispose         ← cas warmup
   └──────────────┬───────────────────┘
                  │ Empty
                  ▼
   ┌──────────────────────────────────┐
   │ sem.acquire()                    │  ← bloque si N drivers vivants
   └──────────────┬───────────────────┘
                  ▼
   ┌──────────────────────────────────┐
   │ create_driver()                  │── leve ─► sem.release(); raise
   └──────────────┬───────────────────┘
                  ▼
   ┌──────────────────────────────────┐
   │ yield driver                     │  ← caller utilise
   └──────────────┬───────────────────┘
                  ▼
                finally :
                  with suppress : dispose()       ← driver détruit
                  sem.release()                   ← rend une place

1. Pas de réutilisation#

Queue.get_nowait() consomme l’entrée. Une fois sorti, le driver n’est jamais remis dans la queue. À la fin (finally), il est disposé.

02.11.01 — CliBuilder + CliArg + _SilentArgumentParser

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

02.11.01 — `CliBuilder` + `CliArg` + `_SilentArgumentParser`#

Fichier source : src/ocarina/opinionated/cli/builder.py

Surcouche déclarative au-dessus d’argparse. Permet d’agréger les erreurs de validation, ré-écrire la sortie d’aide en cas d’erreur, et enregistrer des effets post-parse.

`_SilentArgumentParser`#

class _SilentArgumentParser(ArgumentParser):
    def error(self, message: str) -> Never:
        """Raise an error."""
        raise ValueError(message)

L’ArgumentParser standard appelle sys.exit(2) directement en cas d’erreur. Avec cette merde, on ne peut pas intercepter, on ne peut pas agréger plusieurs erreurs.

_SilentArgumentParser re-route les erreurs en ValueError. Donc CliBuilder.parse peut les attraper et les agréger.

02.03.02 — La machine à états du builder

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

02.03.02 — La machine à états du builder#

Fichier source : src/ocarina/dsl/testing_with_railway/internals/action_chain.py

C’est ici qu’est implémentée toute la mécanique ROP : le passage par quatre états successifs typés, qui interdit littéralement (au sens du type-checker) toute fantaisie syntaxique. Le DSL est aussi son propre système immunitaire.

Vue d’ensemble#

                      ┌─────────────────┐
   start(action)  →   │  ActionStart[T] │     un Action[T] = Thunk[Result[T]]
                      └────────┬────────┘
                               │ .failure(failure_handler)
                               ▼
                      ┌─────────────────┐
                      │ ActionFailure[T]│
                      └────────┬────────┘
                               │ .success(success_handler)
                               ▼
                      ┌─────────────────┐
                      │ ActionSuccess[T]│
                      └────────┬────────┘
                               │ .execute()   ── exécute action(), fire le handler
                               ▼
                      ┌─────────────────┐
                      │ ActionChain[T]  │     contient (has_failed, result)
                      └──────┬──────────┘
                             │ .then(next_action_or_start)
              ┌──────────────┴──────────────┐
              │                             │
   has_failed=True                   has_failed=False
              │                             │
              ▼                             ▼
   ┌──────────────────┐         ┌──────────────────┐
   │ NeutralAction-   │         │ ActionStart[T]   │  → cycle recommence
   │ Start[T]         │         │  (l'action suiv. │
   │ (rail d'échec :  │         │   sera exécutée) │
   │  toute la chaîne │         └──────────────────┘
   │  devient no-op,  │
   │ tout en gardant  │
   │ l'API fluide)    │
   └──────────────────┘
              │
              ▼ (.failure → .success → .execute, tout en no-op)
   ┌──────────────────┐
   │  ActionChain[T]  │   has_failed=True, result=<le Fail accumulé>
   └──────────────────┘

Les types `Action`, `FailureHandler`, `SuccHandler`#

type Action[T]        = Thunk[Result[T]]      # () -> Result[T]
type FailureHandler   = Callable[[Exception], None]
type SuccHandler      = Effect                # () -> None

Action[T] est un Thunk. Cela veut dire qu’au moment où ActionStart(action) est appelé, rien n’est exécuté. L’action est juste capturée.
FailureHandler reçoit l’exception, mais ne reçoit pas le Fail ni le Result. C’est volontaire : 99% des handlers veulent tracer l’exception, prendre un screenshot, et c’est tout.
SuccHandler est un Effect (sans argument). Idem : un handler de succès log un message statique, fait un screenshot, pas besoin du résultat.

Typestate Pattern : pourquoi on ne peut pas se tromper#

L’enchaînement est strictement linéaire. Chaque méthode renvoie un type différent, qui n’expose que la suite logique de l’enchaînement :

02.04.02 — Catalogue des assertions builtin

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

02.04.02 — Catalogue des assertions builtin#

Fichier source : src/ocarina/dsl/invariants/assertions.py ~25 prédicats.

Toutes les assertions suivent le même contrat :

Soit un prédicat direct (value: T) -> None qui lève InvariantViolationError si le contrat n’est pas respecté.
Soit une closure quand il faut passer un argument de configuration (is_equal_to(cmp), etc.).
Soit, exceptionnellement, une higher-order function (HOF) comme each, placée ici par pragmatisme (créer un fichier entier pour ce seul cas serait overkill).

Tableau complet#

Assertion	Direct / closure / HOF	Domaine	Description
`is_str(value)`	direct	`Any`	Lève si `value` n’est pas une `str`
`is_none(value)`	direct	`Any`	Lève si `value is not None`
`is_not_none(value)`	direct	`Any`	Lève si `value is None`
`is_equal_to(cmp)`	closure	`Any`	Retourne `(value) -> None` qui lève si `value != cmp`
`is_not_equal_to(cmp)`	closure	`Any`	Retourne `(value) -> None` qui lève si `value == cmp`
`is_less_than(cmp)`	closure	`float`	`value < cmp`
`is_less_than_or_equal_to(cmp)`	closure	`float`	`value <= cmp`
`is_greater_than(cmp)`	closure	`float`	`value > cmp`
`is_greater_than_or_equal_to(cmp)`	closure	`float`	`value >= cmp`
`is_positive(value)`	direct	`float`	`value >= 0`
`is_not_zero(value)`	direct	`float`	`value != 0`
`is_in(elements)`	closure	`Any`	`value in tuple(elements)`
`is_file(value)`	direct	`str \| Path`	`Path(value).is_file()`
`is_dir(value)`	direct	`str \| Path`	`Path(value).is_dir()`
`is_iso_date_string(value)`	direct	`str`	`datetime.fromisoformat(value)`
`is_iso_utc_date_string(value)`	direct	`str`	Vérifie ISO + `tzinfo == UTC`
`is_email(value)`	direct	`str`	Pas d’espace, exactement 1 `@`, parts non vides, domaine contient `.`
`has_unique_elements(*, key=None)`	closure	`Iterable[Any]`	Détecte les doublons (lève `DuplicatesError`). Type-strict (`1 ≠ True`), supporte les unhashables.
`is_empty(value)`	direct	`Sized`	`len(value) == 0`
`is_truthy(value)`	direct	`Any`	`bool(value) is True`
`is_valid_filename(value)`	direct	`str`	Cross-platform : chars interdits, mots réservés Windows, pas leading/trailing space ni dot, longueur ≤ 255
`each(predicate)`	HOF	`Iterable[Any]`	Applique `predicate` à chaque élément

Quelques implémentations en détail#

`is_email`#

def is_email(value: str) -> None:
    """Assert that the string is a valid email address (fast check)."""
    if " " in value:
        raise InvariantViolationError(f"'{value}' must not contain whitespace.")
    if value.count("@") != 1:
        raise InvariantViolationError(f"'{value}' must contain exactly one '@' character.")
    local_part, domain_part = value.split("@")
    if not local_part or not domain_part:
        raise InvariantViolationError(f"'{value}' must have non-empty local and domain parts.")
    if "." not in domain_part:
        raise InvariantViolationError(f"Domain part of '{value}' must contain at least one '.'.")

Quatre vérifications minimales. Pas de regex RFC5322. C’est volontaire : l’auteur fait le pari que la validation exhaustive d’un email se fait en envoyant un email, pas en regex.

02.05.02 — TestExecutor[Driver]

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

02.05.02 — `TestExecutor[Driver]`#

Fichier source : src/ocarina/dsl/testing/internals/test_executor.py

Responsabilité unique : exécuter une seule tentative d’un test, avec un seul driver. Ne connaît ni le rejeu, ni la pool de drivers, ni l’agrégation au niveau suite.

`ExecutionOutcome`#

@final
@dataclass(frozen=True, slots=True)
class ExecutionOutcome:
    result: TestResult
    skipped: bool
    setup_failed: bool
    should_retry: bool
    steps_count: int

Champ	Type	Sens
`result`	`TestResult` = `Result[Any] \| None`	Le résultat de la chaîne (Ok, Fail), ou `None` si skip / setup_failed.
`skipped`	`bool`	True si `test_runner.skipped` (i.e. `Test(skipped=True)`).
`setup_failed`	`bool`	True si la fonction `setup()` du scénario a levé.
`should_retry`	`bool`	True si la règle de rejeu s’applique (transient_error détecté).
`steps_count`	`int`	Nombre d’`act` appelés ; `-1` si skip ou setup_failed.

slots=True : empêche l’ajout dynamique d’attributs et économise mémoire. C’est un objet qui circule en hot-path, le slots est justifié.
frozen=True : immutable, sûr à partager entre threads.
@final : pas d’héritage.

Ordre d’exécution d’une tentative#

┌──────────────────────────────────────────────────────────────────────┐
│  test_runner = test.spawn(driver, logger_with_taxonomy)              │
└──────────────────────────────┬───────────────────────────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  test_runner.skipped ?          │── True ─► return Outcome(skipped=True, ...)
              └────────────────┬────────────────┘
                               │ False
                               ▼
              ┌─────────────────────────────────┐
              │  logger.test_name(test.name)    │   (annotation)
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  setup() (si non-None)          │── leve ─► teardown() (si non-None)
              └────────────────┬────────────────┘            ↓
                               │                  return Outcome(setup_failed=True, should_retry=True, ...)
                               ▼
              ┌─────────────────────────────────┐
              │  watchers.start(driver, logger, │
              │                 take_screenshot)│   (1 daemon thread par watcher)
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  _run_chain(chain_runners, ...) │── retourne (result, should_retry)
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  watchers.stop()                │   (toujours)
              └────────────────┬────────────────┘
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  teardown() (si non-None)       │   (TOUJOURS, même si chain a fail)
              └────────────────┬────────────────┘     (les exceptions sont logguées & avalées)
                               │
                               ▼
              ┌─────────────────────────────────┐
              │  steps_count = act_counter.get()│
              │  return Outcome(...)            │
              └─────────────────────────────────┘

`execute`#

def execute(
    self, test: Test[Driver], *,
    driver: Driver,
    taxonomy: tuple[str, ...],
    logger_with_taxonomy: ILogger,
    logger_without_taxonomy: ILogger,
    attempt: int, max_attempts: int,
) -> ExecutionOutcome:
    test_runner = test.spawn(driver, logger_with_taxonomy)

    if test_runner.skipped:
        return ExecutionOutcome(result=None, skipped=True, setup_failed=False,
                                should_retry=False, steps_count=-1)

    logger_without_taxonomy.test_name(test.name)

    if test_runner.setup is not None:
        try:
            test_runner.setup()
        except Exception as exc:
            msg = f"{test.name} -- Setup failed (attempt {attempt}/{max_attempts}): {exc}"
            logger_with_taxonomy.warning(msg)
            if test_runner.teardown is not None:
                self._run_teardown(test_runner.teardown, test_name=test.name, logger=logger_with_taxonomy)
            return ExecutionOutcome(result=None, skipped=False, setup_failed=True,
                                    should_retry=True, steps_count=-1)

    watchers: Sequence[Watcher[Driver]] = test_runner.watchers or []
    self._start_watchers(watchers, driver=driver, test_name=test.name, taxonomy=taxonomy)

    result, should_retry = self._run_chain(
        test_runner.chain_runners, test_name=test.name, attempt=attempt,
        driver=driver, logger=logger_without_taxonomy,
        logger_with_taxonomy=logger_with_taxonomy, max_attempts=max_attempts,
    )

    self._stop_watchers(watchers)

    if test_runner.teardown is not None:
        self._run_teardown(test_runner.teardown, test_name=test.name, logger=logger_with_taxonomy)

    steps_count = self._act_counter.get()
    return ExecutionOutcome(result=result, skipped=False, setup_failed=False,
                            should_retry=should_retry, steps_count=steps_count)

Deux loggers : pourquoi#

logger_with_taxonomy vs logger_without_taxonomy :

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 :

02.11.02 — CliStore[TKeys] + _CliField[T] + phantom_validate

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

02.11.02 — `CliStore[TKeys]` + `_CliField[T]` + `phantom_validate`#

Fichiers source : src/ocarina/opinionated/cli/store.py, src/ocarina/opinionated/cli/phantoms.py

Store write-once des valeurs CLI parsées. Chaque champ valide à l’écriture. Le TKeys: Literal[...] apporte de l’autocomplétion sur les clés.

`_CliField[T]` — champ write-once#

class _CliField[T]:
    def __init__(self, *, validate: ValidationChainBuilder[T]) -> None:
        self._value: T | _Unset = _UNSET
        self._validate = validate

    def set(self, value: T) -> None:
        if not isinstance(self._value, _Unset):
            raise RuntimeError("Value already set.")
        self._validate(_validate(value)).execute().raise_if_invalid()
        self._value = value

    def get(self) -> T:
        if isinstance(self._value, _Unset):
            raise RuntimeError("Value not set yet.")
        return self._value

1. Sentinel `_Unset`#

class _Unset:
    pass

_UNSET = _Unset()

Pourquoi pas None ? Parce que None peut être une valeur légitime (--profile-path n’est pas obligatoire ; sa valeur après parse peut légitimement être None). Une sentinelle dédiée distingue « pas encore set » de « set à None ».

02.03.03 — Le rail d'échec : NeutralAction*

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

02.03.03 — Le rail d’échec : `NeutralAction*`#

Cas particulier du builder : que se passe-t-il quand on enchaîne une action sur un ActionChain qui a déjà échoué ?

Pourquoi des classes Neutral plutôt qu’un `if` côté utilisateur#

Lorsqu’on enchaîne une action sur un ActionChain qui a déjà échoué, on bascule dans trois classes Neutral qui acceptent la même API, mais ne font rien.

Imaginons que le DSL n’ait pas cette mécanique.
Le code utilisateur ressemblerait à :

02.04.03 — .otherwise(...) et _any_of

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

02.04.03 — `.otherwise(...)` et `_any_of`#

Comment Ocarina exprime un OR logique entre deux prédicats sans casser l’agrégation d’erreurs.

Le problème#

Cas concret : on veut « age == 18 OR age <= 65 ». La syntaxe ROP/invariants est strictement chaîne d’assertions ; chaque .assert_that() est un AND. Comment exprimer un OR ?

Code#

def otherwise(self, fallback: Predicate[T], *, msg: str | None = None) -> ValidationAssertBlock[T]:
    if self._last_predicate is None:
        raise RuntimeError("otherwise() must follow assert_that().")

    fallback_with_msg = _with_msg(fallback, msg, self._name)
    combined = _any_of(
        self._last_predicate, *([*self._otherwise_predicates, fallback_with_msg])
    )
    self._chain._steps.pop()                    # remplace le dernier step
    self._chain.add_assertion(self._value, combined, self._name)
    self._last_predicate = combined
    self._otherwise_predicates.append(fallback_with_msg)
    return self

Guard. otherwise() doit suivre un assert_that(). Sans prédicat précédent, on lève. (En pratique, le type-checker l’interdit déjà : ValidationStartBlock.otherwise n’existe pas.)
Combinaison. On combine le prédicat précédent + tous les otherwise déjà accumulés + le nouveau, via _any_of. Le résultat est un prédicat composite.
Remplacement du step. On pop le dernier step du _ValidationChain et on push le step combiné. Sans ça, on aurait à la fois le prédicat original ET le combiné, donc l’erreur originale resurgirait.

`_any_of`#

def _any_of[T](*predicates: _PredicateWithMsg[T]) -> _PredicateWithMsg[T]:
    def _try_predicate(p: _PredicateWithMsg[T], value: T) -> InvariantViolationError | None:
        try:
            p(value)
        except InvariantViolationError as exc:
            return exc
        else:
            return None

    def combined(value: T) -> None:
        errors = []
        for p in predicates:
            error = _try_predicate(p, value)
            if error is None:
                return                              # ✅ un prédicat passe → tout passe
            errors.append(error)

        formatted_error_messages = "  | " + "\n  | ".join(str(e) for e in errors)
        msg = (
            f"All predicates failed for value {value!r}.\n"
            "» At least one of the following conditions must be satisfied:\n"
            f"{formatted_error_messages}"
        )
        raise InvariantViolationError(msg)

    return _PredicateWithMsg(combined)

First success wins : dès qu’un prédicat passe, combined retourne None (succès).
Si tous échouent : on construit un message agrégé listant toutes les raisons d’échec, séparées par |
Le résultat est un _PredicateWithMsg : on peut le rebrancher dans la chaîne comme n’importe quel autre prédicat.
L’agrégation est récursive : si on a 3 otherwise() successifs, le 3e combine (P_orig OR P_otherwise1 OR P_otherwise2 OR P_otherwise3) en un seul prédicat.

Exemple#

validate(age, name="age")
    .assert_that(is_equal_to(18), msg="Must be 18 or at most 65")
    .otherwise(is_less_than_or_equal_to(65), msg="Must be 18 or at most 65")
    .execute()
    .raise_if_invalid()

Si age == 18 : is_equal_to(18) passe → OK.
Si age == 30 : is_equal_to(18) lève, is_less_than_or_equal_to(65) passe → OK.
Si age == 70 : les deux lèvent → InvariantViolationError avec :

age: All predicates failed for value 70.
» At least one of the following conditions must be satisfied:
  | age: Must be 18 or at most 65
  | age: Must be 18 or at most 65

(Le doublon de message vient du fait qu’on a passé le même msg= aux deux ; c’est volontaire ici, on veut exprimer une intention unique.)

02.05.03 — TestFlow[Driver] — politique de rejeu

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

02.05.03 — `TestFlow[Driver]` — politique de rejeu#

Fichier source : src/ocarina/dsl/testing/internals/test_flow.py

Responsabilité unique : pour un seul Test, exécuter la boucle de rejeu, acquérir un driver propre à chaque tentative, et appliquer la politique de backoff.

Pourquoi un niveau intermédiaire entre `TestSuite` et `TestExecutor`#

Niveau	Ne sait pas
`TestExecutor`	Le rejeu, la pool de drivers
`TestFlow`	La concurrence inter-tests, l’agrégation suite-level
`TestSuite`	L’exécution d’une tentative, le rejeu

C’est une séparation vraiment stricte. TestFlow est le seul à connaître à la fois la pool et la politique de rejeu : son job est de combiner les deux.

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.

Chapitre 02 — Ocarina, le framework

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

Chapitre 02 — Ocarina, le framework#

Ce chapitre dépile l’intégralité du framework ocarina (Python 3.14+, version 1.1.10) ainsi que du Railway Oriented Programming jusqu’aux plugins de reporting. Il est structuré comme un parcours en couches : du plus profond (le type Result[T]) vers le plus visible (le bootstrap qui démarre tout).

Plan du chapitre#

#	Sujet	Fichier ou dossier
01	Identité technique, dépendances, toolchain	`01-identity.md`
02	Arborescence complète du module + schéma en couches	`02-module-tree.md`
03	Railway Oriented Programming	`03-railway/`
04	Invariants (validate, assertions, chain_validations)	`04-invariants/`
05	Orchestration (Test → TestSuite → TestCampaign → TestCycle)	`05-orchestration/`
06	Cycle de vie d’un `Scenario`	`06-scenario.md`
07	Watcher	`07-watcher.md`
08	`POMBase`	`08-pom-base.md`
09	Ports & adapters (`ILogger`, `ITakeScreenshot`)	`09-ports.md`
10	Infrastructure (pool, builder, screenshotter, act counter, adapters Selenium)	`10-infra/`
11	Couche opinionated (CLI, loggers, plugins, bootstrap)	`11-opinionated/`
12	Custom types & custom errors	`12-custom-types-errors.md`

Lectures connexes#

Programmation fonctionnelle : ../03-functional/
Comment le framework se teste lui-même : ../04-internal-tests/
Exemples d’usage avec adapters projet : ../07-ocarina-example/, ../08-ai-example/
CI : ../10-cicd/02-ocarina-workflows.md

Chapitre 02.03 — Railway Oriented Programming

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

Chapitre 02.03 — Railway Oriented Programming#

Le cœur d’Ocarina. Tout le DSL repose sur cette mécanique : représenter le succès et l’échec comme deux rails parallèles, faire qu’un échec bascule le train sur le rail d’échec, et l’y fait rester (court-circuit), préserver la composition syntaxique pour que le scénario reste lisible.

Plan#

#	Fichier	Sujet
01	`01-result.md`	`Result[T] = Ok[T] \| Fail`, `is_ok`/`is_fail`
02	`02-action-chain-states.md`	Machine à états `ActionStart → ActionFailure → ActionSuccess → ActionChain`.
03	`03-neutral-rail.md`	Rail d’échec : `NeutralActionStart` / `NeutralActionFailure` / `NeutralActionSuccess`.
04	`04-chain-actions-fold.md`	`ChainRunner[T]` (thunk) + `chain_actions` (fold).
05	`05-create-act-hooks.md`	`create_act` et ses hooks (`on_failure`, `on_run_effect`, `act_counter_effect`).
06	`06-drive-page.md`	`drive_page`, alias sémantique.
07	`07-match-page-when.md`	`match_page` / `when` + politique d’exceptions.

Filiation#

L’inspiration directe est le Railway Oriented Programming popularisé par Scott Wlaschin (F#).

02.03.04 — chain_actions et le ChainRunner

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

02.03.04 — `chain_actions` et le `ChainRunner`#

Fichier source : src/ocarina/dsl/testing_with_railway/chain_actions.py

C’est la primitive qui rend le DSL « plat ». Sans elle, un scénario à N pas serait un escalier de .then(...).failure(...).success(...).execute(). Avec elle, c’est une liste.

« Parenthesis hell »#

Solution :
# Flat, readable syntax
runner = chain_actions(
    action1.failure(h1).success(h2),
    action2.failure(h3).success(h4),
    action3.failure(h5).success(h6)
)
chain = runner.run()  # Execute when ready
Benefits :

Lazy evaluation : Build chain without executing

Flat syntax : No deep nesting

Automatic short-circuiting : Stops on first failure

Composability : ChainRunner is a value

(Extrait de docstring.)

02.04.04 — .then(...) et chain_validations(...)

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

02.04.04 — `.then(...)` et `chain_validations(...)`#

Deux mécanismes différents pour composer plusieurs validations en une seule.

`.then(new_value)`#

def then[U](self, new_value: U, *, name: str | None = None) -> ValidationStartBlock[U]:
    return ValidationStartBlock(new_value, self._chain, name)

Change le type de T à U. Le checker accepte le passage à un autre type.
Conserve la chaîne (self._chain). Toutes les assertions précédentes restent dans la chaîne ; toutes les suivantes s’ajoutent à la chaîne.
Bascule le name : c’est le name fourni à .then() qui sera utilisé pour les assertions ajoutées ensuite (et non celui du block précédent).

Cas d’usage canonique#

validate(user, name="user")
    .assert_that(is_not_none)
    .then(user.email, name="user.email")
    .assert_that(is_email)
    .then(user.age, name="user.age")
    .assert_that(is_positive)
    .assert_that(is_less_than_or_equal_to(120))
    .execute()
    .raise_if_invalid()

Lecture : on valide user puis user.email puis user.age. Si toutes ces validations passent : OK. Si ne serait-ce qu’une seule échoue, toutes les erreurs sont agrégées dans le AggregateInvariantViolationError.

02.05.04 — TestSuite[Driver] — moteur parallélisé

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

02.05.04 — `TestSuite[Driver]` — moteur parallélisé#

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

Responsabilité unique : exécuter une séquence de Test en parallèle, gérer la saturation, le filtrage par IDs, et la validation des invariants pré-exécution.

Constructeur#

def __init__(
    self,
    *,
    name: str,
    tests: Sequence[Test[Driver]],
    create_logger: Thunk[ILogger],
    drivers_pool: WebDriversPool[Driver],
    take_screenshot: ITakeScreenshot[Driver],
    act_counter: ActCounter | None = None,
    transient_errors: tuple[type[Exception], ...] = (),
    copy_indicator: str = "COPY",
    put_space_after_copy_indicator: bool = True,
    max_retries_per_test: int | None = None,
    autoscreen_on_fail: bool = False,
    saturate_workers: bool | None = None,
    only_ids: Iterable[str] = (),
    exclude_ids: Iterable[str] = (),
) -> None:
    self._guards_on_invoke(tests)
    # ... assignations ...
    self._tests = filter_tests_by_ids(
        tests,
        only=only_ids,
        exclude=exclude_ids,
        logger=create_logger().set_prefix(lambda: f"{self.name}: filtering tests..."),
    )

Paramètre	Type	Rôle	Défaut
`name`	`str`	Nom de la suite (apparaît dans logs & rapports)	—
`tests`	`Sequence[Test[Driver]]`	Liste des tests à exécuter	—
`create_logger`	`Thunk[ILogger]`	Factory de logger	—
`drivers_pool`	`WebDriversPool[Driver]`	Pool partagée	—
`take_screenshot`	`ITakeScreenshot[Driver]`	Callable `(driver, logger, category) -> None`	—
`act_counter`	`ActCounter \| None`	Si `None` → `ThreadsBasedActCounter()`	`None`
`transient_errors`	`tuple[type[Exception], ...]`	Exceptions qui déclenchent un retry	`()`
`copy_indicator`	`str`	Préfixe pour les tests clonés en saturation	`"COPY"`
`put_space_after_copy_indicator`	`bool`	`[COPY 1]` (`True`) vs `[COPY1]` (`False`)	`True`
`max_retries_per_test`	`int \| None`	Nombre maximum de retentatives d’un test potentiellement flaky	`None` → `_DEFAULT_MAX_RETRIES_PER_TEST` (8)
`autoscreen_on_fail`	`bool`	Capture automatiquement un ou des screenshots (rafale) en cas d’échec	`False`
`saturate_workers`	`bool \| None`	Clonage des tests pour saturer tous les workers si la pool est suffisamment grosse	`None` → cascade : suite > campaign > bootstrap
`only_ids`	`Iterable[str]`	Filtre `--only`	`()`
`exclude_ids`	`Iterable[str]`	Filtre `--exclude`	`()`

Garde-fous#

Au moment du `init`#

def _guards_on_invoke(self, tests: Sequence[Test[Driver]]) -> None:
    validate_test_runners_ids(tests=tests, name="tests").execute().raise_if_invalid()

→ Tous les test_id doivent être uniques. Sinon : AggregateInvariantViolationError. Levé dès la construction, avant la moindre tentative d’exécution. Si l’utilisateur a dupliqué un test_id par erreur, il l’apprend immédiatement.

02.10.04 — ActCounter + ThreadsBasedActCounter

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

02.10.04 — `ActCounter` + `ThreadsBasedActCounter`#

Compteur thread-local du nombre d’act exécutés par tentative. Permet de reporter au rapport « ce test a fait 17 steps avant d’échouer au step 18 ».

Interface#

# src/ocarina/infra/act_counter.py
class ActCounter:
    def get(self) -> int: ...
    def reset(self) -> None: ...
    def incr_act_call_count(self) -> None: ...

Implémentation par défaut#

# src/ocarina/opinionated/infra/act_counter.py
from threading import local

_thread_local = local()
_COUNTER_KEY: Final[str] = "ocarina_counter"


class ActCounter(_ActCounter):
    def get(self) -> int:
        return getattr(_thread_local, _COUNTER_KEY, 0)

    def reset(self) -> None:
        setattr(_thread_local, _COUNTER_KEY, 0)

    def incr_act_call_count(self) -> None:
        if not hasattr(_thread_local, _COUNTER_KEY):
            self.reset()
        setattr(_thread_local, _COUNTER_KEY, getattr(_thread_local, _COUNTER_KEY) + 1)

threading.local() : un namespace dont les attributs sont par thread. Chaque thread a sa propre valeur.
_COUNTER_KEY = "ocarina_counter" : la clé d’attribut.
Pas de lock : chaque thread n’écrit que sa propre valeur, donc pas de race condition.

Pourquoi thread-local plutôt qu’un compteur partagé + lock ?#

Ocarina est architecturé de sorte qu’un thread = un test. Et aucune envie d’introduire toute une state monad ou quoi, autant placer cette « impureté » (qui reste un “état”) ici. C’est tout.

02.11.04 — Loggers : PrintLogger, FileLogger, PrintAndFileLogger, MutedLogger

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

02.11.04 — Loggers : `PrintLogger`, `FileLogger`, `PrintAndFileLogger`, `MutedLogger`#

Dossier source : src/ocarina/opinionated/loggers/

Quatre implémentations canoniques d’ILogger, plus une factory create_matching_logger. Toutes opt-in.

`create_matching_logger`#

LOGGERS_CHOICES = ("terminal", "file", "terminal+file", "muted")

def create_matching_logger(mode: SupportedLogger) -> ILogger:
    if mode == "terminal":
        return PrintLogger()
    if mode == "file":
        return FileLogger(base_dir=get_default_log_dir())
    if mode == "terminal+file":
        return PrintAndFileLogger(base_dir=get_default_log_dir())
    if mode == "muted":
        return MutedLogger()
    raise ValueError(f"Unsupported logger mode: {mode}")

Et :

def get_default_log_dir() -> Path:
    return Path.cwd() / ".ocarina_logs"

→ Par défaut, les logs vont dans .ocarina_logs/ à la racine du projet utilisateur. Gitignored par convention.

Chapitre 02.04 — Invariants

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

Chapitre 02.04 — Invariants#

Sous-DSL d’Ocarina dédié à l’expression d’invariants typés et composables. Utilisé partout : par la CLI, par les POMs, par les custom_invariants/testing/ qui valident la cohérence des suites avant exécution.

Plan#

#	Fichier	Sujet
01	`01-validate-flow.md`	Le flot complet `validate(value) → assert_that → execute → raise_if_invalid` + la classe `_ValidationChain`.
02	`02-assertions.md`	Catalogue des assertions builtin (`is_str`, `is_email`, `is_positive`, `is_in`, `has_unique_elements`, `each`, `is_valid_filename`, …).
03	`03-otherwise-any-of.md`	`.otherwise(...)` et la combinaison OR via `_any_of`.
04	`04-then-chain-of-validations.md`	`.then(new_value)` et `chain_validations(...)` pour la composition.
05	`05-business-vs-framework-validator.md`	`BusinessInvariantValidator` vs `FrameworkInvariantValidator`
06	`06-invariant-errors.md`	`InvariantViolationError`, `DuplicatesError`, `AggregateInvariantViolationError`.

Le pourquoi du DSL d’invariants#

Garde-fou avant exécution. TestSuite.__init__ valide avant de lancer quoi que ce soit que les noms / IDs des tests sont uniques, que max_workers >= 1, etc.
Validation CLI. Chaque flag a son validate=lambda chain: chain.assert_that(...) dans le CliStore. Les erreurs s’agrègent et sortent en un seul message d’erreur.
Validation côté POM. Les actions de POM peuvent valider leurs paramètres (« retries doit être positif ») via validate(retries, name="retries").assert_that(is_positive).execute().raise_if_invalid().

Le Holy Book le résume :

02.03.05 — create_act et ses hooks

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

02.03.05 — `create_act` et ses hooks#

Fichier source : src/ocarina/dsl/testing_with_railway/constructors/create_act.py

Cette fonction est la primitive de bas niveau qui crée un constructeur de pas de test. Elle est appelée par l’utilisateur une fois, pour créer un verbe act propre au projet. Selon la complexité du projet, on peut envisager plusieurs act distincts avec des hooks différents, mais aucun cas d’usage encore observé pour ça, donc on préconise de n’en créer qu’un seul. Ce n’est pas un singleton pour autant : c’est juste une convention.

02.04.05 — BusinessInvariantValidator vs FrameworkInvariantValidator

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

02.04.05 — `BusinessInvariantValidator` vs `FrameworkInvariantValidator`#

Deux factories — strictement identiques en code — qui existent uniquement pour signaler l’intention.

Code#

class _BaseCustomInvariantValidator:
    @staticmethod
    def create[T](
        value: T,
        name: str,
        build_chain: Callable[[ValidationStartBlock[T], T], ValidationAssertBlock[T]],
    ) -> ValidationAssertBlock[T]:
        return _create_business_invariant_validator(
            value, name, lambda chain: build_chain(chain, value)
        )


@final
class BusinessInvariantValidator(_BaseCustomInvariantValidator):
    """Factory for creating business domain invariant validators.

    Use this for domain-specific validation logic (e.g., "user must be adult",
    "order total must match items").
    """


@final
class FrameworkInvariantValidator(_BaseCustomInvariantValidator):
    """Factory for creating framework-level invariant validators.

    Use this for technical/framework validation logic (e.g., "config must be valid",
    "test structure must be correct").
    """

def _create_business_invariant_validator[T](
    value: T,
    name: str,
    build_chain: ValidationChainBuilder[T],
) -> ValidationAssertBlock[T]:
    start_block = validate(value, name=name)
    return build_chain(start_block)

Pourquoi deux classes ?#

BusinessInvariantValidator signale qu’on valide une règle métier ; FrameworkInvariantValidator, une règle technique du framework. À la lecture du code, l’intention saute aux yeux.
Grep. On peut chercher FrameworkInvariantValidator.create pour trouver tous les invariants framework. Idem pour les business rules côté projet.
Maintenabilité. Si l’on veut un jour ajouter du comportement (log différent, stack-trace différente) à l’une ou à l’autre, on peut le faire sans refactor de tous les call-sites.

Usages#

Invariant	Catégorie	Où il vit
`validate_workers_amount`	Framework	`src/ocarina/custom_invariants/testing/workers.py`
`validate_test_runners_ids`	Framework	`src/ocarina/custom_invariants/testing/oc_test_runners_ids.py`
`validate_test_runners_names`	Framework	`src/ocarina/custom_invariants/testing/oc_test_runners_names.py`
`validate_test_suites_names`	Framework	`src/ocarina/custom_invariants/testing/oc_test_suites_names.py`
`validate_test_campaigns_names`	Framework	`src/ocarina/custom_invariants/testing/oc_test_campaigns_names.py`
`validate_test_cycle_name`	Framework	`src/ocarina/custom_invariants/testing/oc_test_cycles_names.py`
Exemple métier : « l’username doit être l’un de la whitelist »	Business	À écrire côté projet utilisateur
Exemple métier : « la date de réservation doit être future et < 1 an »	Business	À écrire côté projet utilisateur

Pattern complet#

# src/ocarina/custom_invariants/testing/workers.py
from ocarina.dsl.invariants.assertions import is_not_zero, is_positive
from ocarina.dsl.invariants.validate import FrameworkInvariantValidator


def _workers_amount_chain(
    chain: ValidationStartBlock[int],
    value: int,
) -> ValidationAssertBlock[int]:
    msg = f"Value Error: Number of workers must be at least 1 (got: {value})."
    return chain.assert_that(is_positive, msg=msg).assert_that(is_not_zero, msg=msg)


def validate_workers_amount(
    *, workers_amount: int, name: str
) -> ValidationAssertBlock[int]:
    """Validate that workers amount is at least 1."""
    return FrameworkInvariantValidator.create(
        workers_amount, name, _workers_amount_chain
    )

Une fonction privée _workers_amount_chain(chain, value) -> ValidationAssertBlock qui définit le quoi.
Une fonction publique validate_workers_amount(*, workers_amount, name) qui fournit l’API et délègue à FrameworkInvariantValidator.create.
Utilisation côté TestSuite.run : validate_workers_amount(...).execute().raise_if_invalid().

Quelle factory pour quel cas#

Holy Book (extrait du chapitre « Extensibilité ») :

02.05.05 — Saturation des workers

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

02.05.05 — Saturation des workers#

Mécanisme propre à Ocarina : si une suite a moins de tests que de workers disponibles, on clone aléatoirement des tests jusqu’à atteindre le nombre de workers. Les copies sont renommées [COPY 1] <name>, [COPY 2] <name>, etc.

Pourquoi#

Le Holy Book formalise la motivation dans le chapitre « Premiers obstacles du monde réel » :

Son option saturate_workers permet de forcer du clonage aléatoire de tests à l’intérieur d’une suite.

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.11.05 — Plugins de rapport

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

02.11.05 — Plugins de rapport#

Dossier source : src/ocarina/opinionated/plugins/reports/

pretty_print_results, results_to_json, generate_docx_proof, timing. Tous opt-in. Exécutables séquentiellement ou en parallèle via run_plugins.

`pretty_print_results`#

# src/ocarina/opinionated/plugins/reports/pretty_print_results.py
def pretty_print_results(results: TestCycleResults, *, with_colors: bool = False) -> None:
    """Display the full test results."""

Campaign
• Suite
  > Test case 1
    » PASSED
  > Test case 2
    » FAILED
      → Error message
        ⫸ At step 3
  > Test case 3
    » SKIPPED

Test results:
1 FAILED | 1 PASSED | 1 SKIPPED

Aspect	Détail
Hiérarchie	3 niveaux : campagne `•`, suite `>`, cas `»`
Niveaux	`PASSED` (vert), `FAILED` (rouge), `SKIPPED` (gris).
Erreur	Message + step number où ça a fail (« At step 3 »)
Summary	Comptage agrégé en bas

`results_to_json`#

def generate_json_results(*, results: TestCycleResults, output_dir: Path, logger: ILogger) -> None:
    """Write test results to a JSON file in results_dir."""
    output_dir.mkdir(parents=True, exist_ok=True)
    max_stem_length = 8
    max_attempts = 500
    for _ in range(max_attempts):
        filename = f"{uuid.uuid4().hex[:max_stem_length]}.json"
        file_path = output_dir / filename
        if not file_path.exists():
            break
    else:
        raise RuntimeError(f"Can't generate unique JSON filename in: {output_dir}.")

{
  "Campaign": {
    "Suite": {
      "test_case": [
        {"status": "success" | "fail", "error": "..."},
        counter,
        metadata
      ]
    }
  }
}

def _result_to_serializable(v: Any) -> dict[str, str]:
    if is_ok(v):
        return {"status": "success"}
    if is_fail(v):
        return {"status": "fail", "error": str(v.error)}
    raise TypeError(f"Expected Ok or Fail instances, but got: {type(v)}")

Le filename est un UUID hex de 8 chars → 16⁸ ≈ 4 milliards d’options. Pas de collision dans la pratique. 500 retries de sécurité.

Chapitre 02.05 — Orchestration

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

Chapitre 02.05 — Orchestration#

Chaîne Test → TestSuite → TestCampaign → TestCycle : comment chaque niveau s’articule, qui gère la parallélisation, qui gère les rejeux, qui décide du skip, et où vivent les invariants pré-exécution.

Plan#

#	Fichier	Sujet
01	`01-test.md`	La classe `Test[Driver]` — `spawn`, fragments pre/post, skip.
02	`02-test-executor.md`	`TestExecutor` — exécution d’une tentative, ordre : setup → watchers.start → chain → watchers.stop → teardown.
03	`03-test-flow-retries.md`	`TestFlow` — boucle de rejeu (1+max_retries), backoff linéaire, gestion des setup-failures.
04	`04-test-suite.md`	`TestSuite` — parallélisation avec `ThreadPoolExecutor`, filtrage IDs, garde-fous.
05	`05-saturation.md`	Saturation des workers : clonage aléatoire `[COPY N]`. Pourquoi et comment.
06	`06-test-campaign.md`	`TestCampaign` — séquence de suites, `campaign_has_failed`.
07	`07-test-cycle-modes.md`	`TestCycle` — smoke + main, modes `fail-fast` vs `wait-for-all`, `has_test_cycle_failed`.
08	`08-filter-tests-by-ids.md`	`filter_tests_by_ids` — `--only`/`--exclude`, mutex, ignore les unknown IDs.

Schéma#

            ┌────────────────────────────────────────────────┐
            │                  TestCycle                     │
            │                                                │
            │  ┌──────────────────────────────────────────┐  │
            │  │ smoke_tests_campaigns                    │  │ ◄── 1er, gate
            │  │  └─ TestCampaign                         │  │     mode : fail-fast |
            │  │      └─ TestSuite                        │  │            wait-for-all
            │  │          └─ Test                         │  │
            │  └──────────────────────────────────────────┘  │
            │                                                │
            │  ┌──────────────────────────────────────────┐  │
            │  │ campaigns (main)                         │  │ ◄── skippées si
            │  │  └─ TestCampaign                         │  │     un smoke fail
            │  │      └─ TestSuite                        │  │
            │  │          └─ Test                         │  │
            │  └──────────────────────────────────────────┘  │
            └────────────────────────────────────────────────┘

Qui fait quoi ?#

Niveau	Responsabilité unique	Concurrence	Hors périmètre
`Test`	Métadonnées + `spawn(driver, logger)`	aucune	exécution
`TestExecutor`	Une tentative	aucune	rejeu, acquisition de driver
`TestFlow`	Boucle de rejeu	aucune	parallélisation, agrégation
`TestSuite`	Parallélisation + saturation + filtrage IDs	N threads	séquence inter-suites
`TestCampaign`	Séquence de suites	suite-level	smoke vs main
`TestCycle`	Smoke + main + mode	campaign-level	bootstrap / plugins post-exec

Cette séparation stricte est délibérée : TestExecutor ne sait rien des retries, TestFlow ne sait rien de la concurrence, TestSuite ne sait rien de l’agrégation campaign-level. Chaque classe a un seul axe de responsabilité.

02.10.06 — L'acteur Playwright : un thread propriétaire

Mon, 01 Jun 2026 00:00:00 +0000

02.10.06 — L’acteur Playwright : un thread propriétaire#

Dossier source : src/ocarina/infra/playwright/

L’adapter Playwright reprend la structure de l’adapter Selenium fichier pour fichier (create_driver, create_drivers_pool, create_screenshotter, driver_healthcheck, mixins), avec un fichier en plus : driver.py. Ce fichier mérite un chapitre à lui seul. C’est lui qui réconcilie l’API sync de Playwright, intrinsèquement liée à un thread, avec le modèle threadé d’Ocarina (pool, warmup, Watcher).

Le problème : l’API sync de Playwright est thread-affine#

L’API sync de Playwright lie chaque objet qu’elle renvoie (Playwright, Browser, BrowserContext, Page, Locator, …) au thread qui a appelé sync_playwright().start(). Sous le capot, c’est un greenlet épinglé à ce thread. Y toucher depuis un autre thread lève :

02.03.06 — drive_page

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

02.03.06 — `drive_page`#

Fichier source : src/ocarina/opinionated/dsl/drive_page.py

Code#

def drive_page(
    first: ActionSuccess[TPOM], *rest: ActionSuccess[TPOM]
) -> ChainRunner[TPOM]:
    return chain_actions(first, *rest)

C’est exactement chain_actions.

Pourquoi cet alias ?#

1. Sémantique : « je prends le contrôle d’une page »#

Citation du Holy Book (Premiers scénarios) :

drive_page exprime que l’on prend le contrôle d’une page. Toute transition devient explicite par l’ouverture d’un nouveau drive_page.

return [
    drive_page(
        act(on_homepage, open_homepage)...,
        act(on_homepage, verify_homepage)...,
        act(on_homepage, click_cta)...,
    ),                                          # ⬅ fermeture du contrôle de la homepage
    drive_page(                                 # ⬅ ouverture du contrôle de la page suivante
        act(on_target_page, verify_target_page)...,
    ),
]

2. Discipline#

Mélanger des actes sur deux POMs différents dans un même drive_page devient une erreur mypy (cf. 02-action-chain-states.md, section « narrowing par act() »). Cela force concrètement à respecter la sémantique.

02.04.06 — Hiérarchie d'erreurs des invariants

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

02.04.06 — Hiérarchie d’erreurs des invariants#

Fichier source : src/ocarina/dsl/invariants/errors.py

InvariantViolationError (base — sous-classe d'Exception)
├── DuplicatesError                  (levée par `has_unique_elements`)
└── AggregateInvariantViolationError (levée par `_ValidationResult.raise_if_invalid`)

`InvariantViolationError`#

class InvariantViolationError(Exception):
    """Base exception raised when an invariant is violated."""

Une simple sous-classe d’Exception sans logique propre. Tous les prédicats lèvent cette classe (ou une sous-classe).

try:
    validate(value).assert_that(predicate).execute().raise_if_invalid()
except InvariantViolationError as e:
    logger.error(f"Validation failed: {e}")

… attrape toutes les violations en une seule clause.

`DuplicatesError`#

class DuplicatesError(InvariantViolationError):
    def __init__(self, duplicates: Sequence[Any], message: str | None = None) -> None:
        self.duplicates = duplicates
        msg = message or "Duplicate elements detected:\n" + "\n".join(
            f" - {d}" for d in duplicates
        )
        super().__init__(msg)

Stocke la liste des doublons dans .duplicates.
Génère un message « Duplicate elements detected:\n - apple\n - banana » par défaut.
Accepte un message= custom.

Levée par has_unique_elements

02.05.06 — TestCampaign[Driver]

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

02.05.06 — `TestCampaign[Driver]`#

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

Responsabilité unique : exécuter une séquence de suites dans l’ordre, partager une config de workers, et déclarer campaign_has_failed.

Code#

class TestCampaign[Driver]:
    def __init__(
        self,
        *,
        name: str,
        suites: Sequence[TestSuite[Driver]],
        max_workers: int,
        saturate_workers: bool | None = None,
    ) -> None:
        validate_test_suites_names(suites=suites, name="suites").execute().raise_if_invalid()

        self.name = name
        self._suites = suites
        self._results: TestCampaignResults = {}
        self._max_workers = max_workers
        self._saturate_workers = saturate_workers

        for suite in self._suites:
            suite._campaign_name = self.name

    def run_all(
        self, *, skip_all: bool = False, saturate_workers: bool = True
    ) -> TestCampaignResults:
        self._results.clear()

        resolved_saturate_workers = (
            self._saturate_workers
            if self._saturate_workers is not None
            else saturate_workers
        )

        if skip_all:
            for suite in self._suites:
                self._results[suite.name] = {
                    name: (None, -1, test_id)
                    for name, test_id in suite.test_names_and_ids
                }
            return self._results

        for suite in self._suites:
            self._results[suite.name] = suite.run(
                max_workers=self._max_workers,
                saturate_workers=resolved_saturate_workers,
            )

        return self._results


def campaign_has_failed(results: TestCampaignResults) -> bool:
    return any(
        is_test_result_fail(outcome)
        for campaign_results in results.values()
        for outcome, _, _ in campaign_results.values()
    )

Anatomie#

Garde-fou au constructeur#

validate_test_suites_names(suites=suites, name="suites").execute().raise_if_invalid()

→ Les noms de suites de la campagne doivent être uniques — de façon insensible à la casse depuis 1.1.10 (NFC + casefold). Levé dès la construction.

02.11.06 — bootstrap + run_plugins

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

02.11.06 — `bootstrap` + `run_plugins`#

Fichier source : src/ocarina/opinionated/launcher/bootstrap.py

Point d’entrée d’un projet Ocarina.
Trois étapes : cycle.run_all → run_plugins → post_exec.

Code#

def bootstrap[T](
    *,
    test_cycle: TestCycle[T],
    run_plugins: Callable[[TestCycleResults], None],
    post_exec: Callable[[TestCycleResults], None] | None = None,
    saturate_workers: bool = True,
) -> None:
    results = test_cycle.run_all(saturate_workers=saturate_workers)
    run_plugins(results)
    if post_exec:
        post_exec(results)

Ordre#

1. cycle.run_all()  →  results
2. run_plugins(results)
3. post_exec(results) (optionnel)

Étape	Effet	Pourquoi cet ordre
1	Tous les tests s’exécutent	On a besoin des `results` pour la suite
2	Les plugins se lancent (DOCX, JSON, etc.)	Doit s’exécuter avant `post_exec` car peut avoir besoin du temps de génération
3	Post-exec (pretty_print + sys.exit)	Dernière chose ; après ça, le process est mort

Typage#

run_plugins: Callable[[TestCycleResults], None]
post_exec: Callable[[TestCycleResults], None] | None = None

Les deux reçoivent les results en argument :

02.03.07 — match_page / when

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

02.03.07 — `match_page` / `when`#

Fichier source : src/ocarina/dsl/testing_with_railway/match_page.py

Ajouté après coup au framework. Le Holy Book précise : « match_page et when ont été ajoutés après coup, l’Igoristan était tellement aléatoire que le cas d’usage s’est imposé de lui-même. Leur implémentation a été simple, preuve de la flexibilité de la grammaire : d’autres structures analogues pourraient très bien suivre. »

Le problème#

Certaines pages d’une application peuvent être rendues différemment :

02.05.07 — TestCycle[Driver] + modes

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

02.05.07 — `TestCycle[Driver]` + modes#

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

Responsabilité unique : orchestrer les campagnes smoke puis main, et appliquer un mode de gestion d’échec des smoke.

Deux modes#

type Mode = Literal[
    "fail-fast-on-first-smoke-campaigns-sequence-fail",
    "wait-for-all-smoke-tests",
]

Mode	Comportement
`fail-fast-on-first-smoke-campaigns-sequence-fail` (par défaut)	Dès qu’une campagne de smoke fail, les suivantes sont skippées.
`wait-for-all-smoke-tests`	Toutes les campagnes de smoke s’exécutent. Si au moins une fail, les campagnes main sont skippées.

Cas	Mode
Smoke par dépendance (par exemple : “login” puis “dashboard accessible”)	`fail-fast` (si login échoue, dashboard est inutile)
Smoke parallèles (par exemple : “homepage” + “API ping”)	`wait-for-all` (on veut voir les deux)

Le default est fail-fast parce que c’est le cas le plus fréquent.

02.05.08 — filter_tests_by_ids

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

02.05.08 — `filter_tests_by_ids`#

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

Utilisé par TestSuite.__init__ pour appliquer les flags CLI --only <ids> et --exclude <ids>. Mutex : on ne peut pas passer les deux.

Code#

def filter_tests_by_ids[Driver](
    tests: Sequence[Test[Driver]],
    *,
    only: Iterable[str] = (),
    exclude: Iterable[str] = (),
    logger: ILogger,
) -> Sequence[Test[Driver]]:
    only_set = set(only)
    exclude_set = set(exclude)

    if only_set and exclude_set:
        raise ValueError("--only and --exclude cannot be used together")

    known_ids = {test.test_id for test in tests}

    if only_set:
        matched = only_set & known_ids
        if matched:
            joined = ", ".join(sorted(matched))
            logger.info(f"--only: matched test IDs: {joined}")
        return [test for test in tests if test.test_id in only_set]

    if exclude_set:
        matched = exclude_set & known_ids
        if matched:
            joined = ", ".join(sorted(matched))
            logger.info(f"--exclude: matched test IDs: {joined}")
        return [test for test in tests if test.test_id not in exclude_set]

    return tests

Quatre garanties#

1. Mutex `--only` / `--exclude`#

if only_set and exclude_set:
    raise ValueError("--only and --exclude cannot be used together")

Tenter de passer les deux est une erreur runtime (pas une erreur mypy). Sémantiquement, ça n’aurait pas de sens : « ne garder que A, B » ET « exclure C, D » ? Qu’est-ce que c’est que ces putains de conneries (à l’échelle d’une CLI) ? Le mutex évite l’ambiguïté.

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).

Chapitre 02.11 — Couche opinionated/

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

Chapitre 02.11 — Couche `opinionated/`#

Tout ce qui est opt-in : un utilisateur sourcilleux peut tout remplacer. CLI, loggers, plugins de rapport, bootstrap, alias drive_page. Cette couche est ce qu’on voit en surface ; elle n’est pas le cœur, c’est la version « clé en main » qu’Ocarina fournit pour qu’un projet typique n’ait pas à réinventer.

Plan#

#	Fichier	Sujet
01	`01-cli-builder.md`	`CliBuilder`, `CliArg`, `_SilentArgumentParser`.
02	`02-cli-store-phantoms.md`	`CliStore[TKeys]`, `_CliField[T]`, `phantom_validate`.
03	`03-selenium-cli.md`	`create_selenium_auto_cli_store` + flags + validation.
04	`04-loggers.md`	`ILogger` impl : `PrintLogger`, `FileLogger`, `PrintAndFileLogger`, `MutedLogger`, `create_matching_logger`.
05	`05-plugins-reports.md`	`pretty_print_results`, `results_to_json`, `generate_docx_proof`, `timing`.
06	`06-bootstrap-launcher.md`	`bootstrap` + `run_plugins` (parallèle).

Opt-out/opt-in#

Sans `opinionated/`	Avec `opinionated/`
L’utilisateur doit écrire son CLI from scratch	`create_selenium_auto_cli_store()` lui donne tout
L’utilisateur doit écrire son logger	`create_matching_logger("terminal+file")` lui donne tout
L’utilisateur doit écrire ses rapports	`pretty_print_results`, `generate_json_results`, `generate_docx_proof`
L’utilisateur doit écrire son main()	`bootstrap(test_cycle, run_plugins, post_exec)`

Alternatives#

Composant	Remplaçable par…
`CliBuilder` / `CliStore`	Toute lib argparse-like (click, typer, fire)
`PrintLogger` / `FileLogger`	Toute impl d’`ILogger`
`pretty_print_results`	Toute fonction `(TestCycleResults) -> None`
`generate_docx_proof`	Idem
`bootstrap`	Toute fonction `() -> None` qui appelle `TestCycle.run_all` + post-traite
`drive_page`	`chain_actions` direct, ou un alias projet (`drive_section`, `drive_widget`)

Ocarina on Ocarina — précis

02.03.01 — Le type Result[T]

02.03.01 — Le type Result[T]#

Code#

Six décisions de design à décortiquer#

1. _BaseResult comme parent commun#

02.04.01 — Le flot validate → assert_that → execute → raise_if_invalid

02.04.01 — Le flot validate → assert_that → execute → raise_if_invalid#

La machine à états#

Diagramme#

Boucle assert_that#

02.05.01 — Test[Driver]

02.05.01 — Test[Driver]#

Signature#

1. @final#

02.10.01 — WebDriversPool[Driver]

02.10.01 — WebDriversPool[Driver]#

Constructeur#

acquire()#

1. Pas de réutilisation#

02.11.01 — CliBuilder + CliArg + _SilentArgumentParser

02.11.01 — CliBuilder + CliArg + _SilentArgumentParser#

_SilentArgumentParser#

02.03.02 — La machine à états du builder

02.03.02 — La machine à états du builder#

Vue d’ensemble#

Les types Action, FailureHandler, SuccHandler#

Typestate Pattern : pourquoi on ne peut pas se tromper#

02.04.02 — Catalogue des assertions builtin

02.04.02 — Catalogue des assertions builtin#

Tableau complet#

Quelques implémentations en détail#

is_email#

02.05.02 — TestExecutor[Driver]

02.05.02 — TestExecutor[Driver]#

ExecutionOutcome#

Ordre d’exécution d’une tentative#

execute#

Deux loggers : pourquoi#

02.10.02 — DriverBuilder[Driver]

02.10.02 — DriverBuilder[Driver]#

Pourquoi un builder ?#

02.11.02 — CliStore[TKeys] + _CliField[T] + phantom_validate

02.11.02 — CliStore[TKeys] + _CliField[T] + phantom_validate#

_CliField[T] — champ write-once#

1. Sentinel _Unset#

02.03.03 — Le rail d'échec : NeutralAction*

02.03.03 — Le rail d’échec : NeutralAction*#

Pourquoi des classes Neutral plutôt qu’un if côté utilisateur#

02.04.03 — .otherwise(...) et _any_of

02.04.03 — .otherwise(...) et _any_of#

Le problème#

Code#

_any_of#

Exemple#

02.05.03 — TestFlow[Driver] — politique de rejeu

02.05.03 — TestFlow[Driver] — politique de rejeu#

Pourquoi un niveau intermédiaire entre TestSuite et TestExecutor#

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[...]#

Chapitre 02 — Ocarina, le framework

Chapitre 02 — Ocarina, le framework#

Plan du chapitre#

Lectures connexes#

Chapitre 02.03 — Railway Oriented Programming

Chapitre 02.03 — Railway Oriented Programming#

Plan#

Filiation#

02.03.04 — chain_actions et le ChainRunner

02.03.04 — chain_actions et le ChainRunner#

« Parenthesis hell »#

02.04.04 — .then(...) et chain_validations(...)

02.04.04 — .then(...) et chain_validations(...)#

.then(new_value)#

02.03.01 — Le type `Result[T]`#

1. `_BaseResult` comme parent commun#

02.04.01 — Le flot `validate → assert_that → execute → raise_if_invalid`#

Boucle `assert_that`#

02.05.01 — `Test[Driver]`#

1. `@final`#

02.10.01 — `WebDriversPool[Driver]`#

`acquire()`#

02.11.01 — `CliBuilder` + `CliArg` + `_SilentArgumentParser`#

`_SilentArgumentParser`#

Les types `Action`, `FailureHandler`, `SuccHandler`#

`is_email`#

02.05.02 — `TestExecutor[Driver]`#

`ExecutionOutcome`#

`execute`#

02.10.02 — `DriverBuilder[Driver]`#

02.11.02 — `CliStore[TKeys]` + `_CliField[T]` + `phantom_validate`#

`_CliField[T]` — champ write-once#

1. Sentinel `_Unset`#

02.03.03 — Le rail d’échec : `NeutralAction*`#

Pourquoi des classes Neutral plutôt qu’un `if` côté utilisateur#

02.04.03 — `.otherwise(...)` et `_any_of`#

`_any_of`#

02.05.03 — `TestFlow[Driver]` — politique de rejeu#

Pourquoi un niveau intermédiaire entre `TestSuite` et `TestExecutor`#

02.10.03 — `Screenshotter[TDriver]`#

`Protocol`#

`ScreenshotterConfig[TDriver]`#

`Literal[...]`#

02.03.04 — `chain_actions` et le `ChainRunner`#

02.04.04 — `.then(...)` et `chain_validations(...)`#

`.then(new_value)`#

02.05.04 — `TestSuite[Driver]` — moteur parallélisé#

Au moment du `init`#

02.10.04 — `ActCounter` + `ThreadsBasedActCounter`#

02.11.04 — Loggers : `PrintLogger`, `FileLogger`, `PrintAndFileLogger`, `MutedLogger`#

`create_matching_logger`#

02.03.05 — `create_act` et ses hooks#

02.04.05 — `BusinessInvariantValidator` vs `FrameworkInvariantValidator`#

`create_driver.py`#

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

`pretty_print_results`#

`results_to_json`#

02.03.06 — `drive_page`#

`InvariantViolationError`#

`DuplicatesError`#

02.05.06 — `TestCampaign[Driver]`#

02.11.06 — `bootstrap` + `run_plugins`#

02.03.07 — `match_page` / `when`#