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 :

03.01 — Effect, Thunk[T], Result[T]#

Trois lignes de code dans custom_types/ + une dans railway/. Tout le DSL repose dessus.

Triplet#

# src/ocarina/custom_types/effect.py
type Effect = Callable[[], None]
type Effects = tuple[Effect, ...]

# src/ocarina/custom_types/thunk.py
type Thunk[T] = Callable[[], T]

# src/ocarina/railway/result.py
type Result[T] = Ok[T] | Fail

Distinction Effect vs Thunk#

log_msg: Effect = lambda: print("hello")        # () -> None
get_42: Thunk[int] = lambda: 42                 # () -> int
fetch:  Thunk[Result[int]] = lambda: Ok(42)     # () -> Result[int]

Si la fonction retourne quelque chose qu’on va consommer ailleurs → Thunk[T].
Sinon → Effect.

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 :

01.03 — KISS et complexité ostentatoire#

La critique reçue#

Le premier retour public reçu par Ocarina, systématique d’après l’auteur :

La première « critique » a souvent été la même : « Tu te vantes de quelque chose qui est très simple. »

Le Holy Book y répond longuement. Trois piliers : le caractère opérant de la simplicité, la distinction simple ≠ peu élaboré, et le refus de toutes les contre-propositions « créatives » reçues.

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#

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#

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#

Filiation#

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

01.04 — Citations et influences revendiquées#

Les références citées dans le Holy Book ne sont pas neutres : elles fixent le cadre théorique d’Ocarina. On les recoupe ici par grands axes, puis on en propose une lecture d’ensemble.

Axe technique — Programmation fonctionnelle, types, langages#

Axe culturel — Anti-narcissisme, simplicité, KISS bien compris#

Axe politique — Code, souveraineté, anti-startup-nation#

Axe identitaire / underground#

Axe IA / outillage moderne#

Cohérence d’ensemble#

Toutes ces influences pointent vers trois axes convergents :

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

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#

Le pourquoi du DSL d’invariants#

1. 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.
2. 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.
3. 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.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.