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

07.01 — Arborescence

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

07.01 — Arborescence#

src/
├── main.py                                                     # entry point (cf. README)
│
├── api/                                                        # clients HTTP externes
│   ├── retrieve_dashboard_otp_code.py                          # filter + sort + pick OTP
│   ├── get_otp_history.py                                      # HTTP GET /api/otp-history
│   └── constants/endpoints.py                                  # URLs des endpoints tests-workers
│
├── caches/                                                     # cache L1 in-memory
│   ├── l1.py                                                   # dogpile.cache.memory TTL 30m
│   └── reserve_free_cache_key.py                               # UUID + threading.Lock
│
├── constants/                                                  # constantes
│   ├── pages/
│   │   ├── homepage.py                                         # HOMEPAGE_URL
│   │   ├── dashboard.py                                        # DASHBOARD_URL + ids des inputs
│   │   ├── random_loaders.py
│   │   ├── sacred_upload.py
│   │   ├── corsicamon.py
│   │   ├── chaotic_form.py
│   │   ├── madness.py
│   │   ├── random_error_page.py
│   │   └── donkey_sausage_eater_detector.py
│   └── sys/
│       ├── redis_keys.py                                       # OTP_SEND_LOCK_KEY, ...
│       └── transient_errors.py                                 # (WebDriverException, HttpError...)
│
├── lib/
│   ├── connectors/test_steps/actions/                          # fonctions (TPOM) -> TPOM
│   │   ├── homepage.py
│   │   ├── dashboard_login.py                                  # ~10 connectors (with/without retries)
│   │   ├── dashboard_welcome.py
│   │   ├── dashboard_protected_page.py
│   │   ├── sacred_upload.py
│   │   ├── corsicamon_enter_api_key.py
│   │   ├── corsicamon_main.py
│   │   ├── chaotic_form.py
│   │   ├── random_error.py
│   │   ├── random_loaders.py
│   │   ├── madness.py
│   │   ├── this_is_bastia.py
│   │   ├── cors_errors.py
│   │   ├── bsod.py
│   │   ├── dsed.py
│   │   └── ids_bypassed.py
│   ├── custom_errors/
│   │   ├── http.py                                             # HttpErrorPageReachedError
│   │   └── transient_error.py                                  # TransientError
│   └── ext/                                                    # extensions / adapters
│       ├── ocarina/
│       │   ├── adapters/
│       │   │   ├── agnostic/
│       │   │   │   ├── act.py                                  # ⭐ adapter act (hook on_failure)
│       │   │   │   ├── env_getters.py                          # ⭐ adapter EnvGetters typé
│       │   │   │   └── match_page.py                           # ⭐ adapter match_page
│       │   │   └── selenium/
│       │   │       ├── test_suite.py                           # ⭐ adapter TestSuite
│       │   │       ├── test_campaign.py                        # ⭐ adapter TestCampaign
│       │   │       ├── cli_getters.py                          # getters typés depuis le CliStore
│       │   │       ├── logs.py                                 # create_just_log_error, etc.
│       │   │       └── screenshotter.py                        # take_screenshot helper
│       │   └── regex/error_page.py                             # ERROR_PAGE_REGEX
│       ├── redis/
│       │   └── client.py                                       # Singleton client Redis
│       └── selenium/
│           ├── humanize/                                       # ⭐ HumanizedDriver + keyboard
│           │   ├── proxy.py
│           │   └── keyboard.py
│           ├── pages/verify_elements_presence.py
│           └── watchers/catch_me_if_you_can_watcher.py         # ⭐ Watcher callback
│
├── pages/                                                      # POMs (Selenium + SeleniumTitleMixin)
│   ├── homepage.py
│   ├── random_loaders.py
│   ├── chaotic_form.py
│   ├── random_error.py
│   ├── sacred_upload/
│   │   ├── sacred_upload.py
│   │   └── fixtures/                                           # fichiers à uploader
│   ├── dashboard/
│   │   ├── login.py                                            # ⭐ avec OTP, retries, redis locks
│   │   ├── welcome_page.py
│   │   └── protected_page.py
│   ├── corsicamon/
│   │   ├── enter_api_key.py
│   │   └── main.py
│   ├── madness/
│   │   ├── base.py
│   │   ├── matchers.py                                         # has_cors, has_this_is_bastia
│   │   ├── cors.py
│   │   └── this_is_bastia.py
│   └── donkey_sausage_detector/
│       └── ids_bypassed.py
│
└── tests/
    ├── cycles/e2e.py                                           # ⭐ TestCycle (smoke + main)
    ├── campaigns/
    │   ├── global_smoke_tests.py                               # smoke
    │   ├── corsicamon.py                                       # main (+ smoke variant)
    │   ├── dashboard_login.py                                  # main
    │   ├── randomness.py                                       # main
    │   └── sacred_upload.py                                    # main
    ├── suites/
    │   ├── global_smoke_tests.py
    │   ├── randomness.py
    │   ├── dashboard/
    │   │   ├── access/
    │   │   │   ├── happy_paths.py
    │   │   │   └── unhappy_paths.py
    │   │   └── data_driven/multi_login.py
    │   ├── sacred_upload/{happy_paths,unhappy_paths}.py
    │   └── corsicamon/{smoke_tests,happy_paths,unhappy_paths}.py
    └── scenarios/
        ├── homepage/verify_homepage.py
        ├── dashboard/
        │   ├── access/{happy_paths,unhappy_paths}.py
        │   ├── back_to_igoristan.py
        │   └── data_driven/{multi_login,datasets/multi_login}.py
        ├── sacred_upload/{upload_files,just_go_back_to_igoristan}.py
        ├── corsicamon/{enter_api_key,new_draw,add_corsicamon,back_to_igoristan}.py
        └── randomness/
            ├── level_1/{random_error_page,random_loaders_page}.py
            ├── level_2/{dsed,madness}.py
            ├── level_3/chaotic_form.py
            └── level_4/walkthrough.py

Sémantique des dossiers#

Dossier	Rôle	Convention
`pages/`	POMs (héritent `SeleniumTitleMixin, POMBase`)	Une classe par page, fluent (`return self`)
`lib/connectors/test_steps/actions/`	Connectors `(TPOM) -> TPOM`	Fonctions pures ; si paramètres, closures
`lib/custom_errors/`	Exceptions projet	Sous-classes d’Exception
`lib/ext/ocarina/adapters/`	Adapters au-dessus d’Ocarina	Cf. `02-adapters.md`
`lib/ext/redis/`	Wrapper Singleton Redis	Pour les locks distribués
`lib/ext/selenium/`	Extensions Selenium spécifiques au projet	`HumanizedDriver`, `Watcher` callback
`caches/`	Cache L1 in-memory	`dogpile.cache.memory` + UUID reservation
`constants/`	Constantes	URLs, redis keys, transient errors
`api/`	Clients HTTP externes	OTP retrieval, OTP history
`tests/`	Hiérarchie ISTQB	cycles / campaigns / suites / scenarios

`lib/` vs `pages/`#

pages/ : POMs, encapsulent l’état d’une page (locators, méthodes d’action).
lib/connectors/test_steps/actions/ : connectors, fonctions qui réfèrent aux POMs.

act(on_homepage, open_homepage)
#                ^^^^^^^^^^^^^
#                connector défini dans lib/connectors/test_steps/actions/homepage.py

def open_homepage(p: Homepage) -> Homepage:
    return p.open()

Le CLAUDE.md du projet IA en fait une discipline :

03.03 — Évaluation paresseuse

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

03.03 — Évaluation paresseuse#

Dans Ocarina, rien n’est exécuté tant qu’on ne l’a pas explicitement déclenché. C’est ce qui rend les scénarios composables comme des valeurs.

Zzz#

Endroit	Forme	Déclencheur
`ChainRunner[T]`	`Thunk[ActionChain[T]]`	`runner.run()`
`validate(...)`	`ValidationStartBlock` / `ValidationAssertBlock`	`.execute()`
`match_page(...)`	retourne un `ChainRunner[Any]`	`.run()` (via la chaîne englobante)
`Watcher.callback`	`Callable[[Watcher], None]`	`_loop` quand `start()` est appelé
`logger.set_prefix(thunk)`	`Thunk[str]`	recalculé à chaque appel de log
`Scenario.setup` / `teardown`	`Effect`	appelé par `TestExecutor`
`bootstrap(post_exec=...)`	`Callable[[TestCycleResults], None]`	appelé après `run_plugins`
`CliBuilder(effects_factory=lambda ns: (...))`	`Effects`	appelés après le parse argparse
`test_scenario: TestScenario[Driver]`	`Callable[[Driver, ILogger], Scenario[Driver]]`	appelé par `Test.spawn`
`dispatch[mode]()` dans `TestCycle.run_all`	dict de `Thunk[bool]`	appelé en lookup

`ChainRunner`#

runner = drive_page(act1, act2, act3)        # ⚠️  rien exécuté
# … plus tard …
chain = runner.run()                         # ▶︎  exécution

Capacité	Sans paresse	Avec paresse
Stocker un scénario dans une variable	impossible (déjà exécuté)	trivial
Multiplier `[runner] * 5`	exécute 1 fois, on a 5 références au résultat	exécute 5 fois
Passer un `runner` à un autre `runner` (composition)	impossible	trivial
Réordonner les `act` dans un test refactor	difficile	trivial

`validate(...).execute()`#

v = validate(value, name="x").assert_that(is_positive).assert_that(is_not_zero)
# … on peut composer …
combined = chain_validations(v, other_validation)
# … rien d'exécuté jusqu'ici …
combined.execute().raise_if_invalid()        # ▶︎  exécution + agrégation

C’est ce qui permet à _ValidationChain de collecter toutes les erreurs avant d’en lever une seule (AggregateInvariantViolationError).

07.03 — Scénarios Dashboard login

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

Trois familles : happy paths, unhappy paths, data-driven multi-login. Tous exercent le useAuth à 10% de raté et la coordination OTP.

`dashboard_login`#

# src/tests/campaigns/dashboard_login.py
def create_igoristan_login_campaign(*, drivers_pool: SeleniumWebDriversPool) -> TestCampaign:
    return TestCampaign(
        name="Dashboard login",
        suites=[
            create_igoristan_login_happy_paths_test_suite(drivers_pool=drivers_pool),
            create_igoristan_login_unhappy_paths_test_suite(drivers_pool=drivers_pool),
            create_igoristan_login_data_driven_test_suite(drivers_pool=drivers_pool),
        ],
    )

Happy paths#

# src/tests/suites/dashboard/access/happy_paths.py
def create_igoristan_login_happy_paths_test_suite(*, drivers_pool) -> TestSuite:
    return TestSuite(
        name="Login happy paths",
        tests=[
            test_dashboard_login_without_otp_happy_path,
            test_dashboard_login_with_otp_happy_path,
            test_dashboard_login_page_back_to_igoristan_button,
        ],
        drivers_pool=drivers_pool,
    )

def dashboard_login_without_otp_happy_path(driver, logger):
    dashboard_creds = create_env_getters().get_credentials("dashboard")
    on_dashboard_login_page = DashboardLoginPage(driver=driver)
    on_dashboard_welcome_page = DashboardWelcomePage(driver=driver)

    just_log_error = create_just_log_error(logger=logger)
    log_error_with_current_url = create_log_error_with_current_url(logger=logger, driver=driver)
    just_log_success = create_just_log_success(logger=logger)
    log_success_with_current_url_and_take_screenshot = create_log_success_with_current_url_and_take_screenshot(...)

    retries_amount = max(get_max_workers(), 10)

    return [
        drive_page(
            act(on_dashboard_login_page, open_dashboard_login_page)
                .failure(just_log_error("Failed to open the dashboard login page..."))
                .success(just_log_success("Opened the dashboard login page!")),
            act(on_dashboard_login_page, verify_dashboard_login_page)
                .failure(log_error_with_current_url("Failed to verify..."))
                .success(log_success_with_current_url_and_take_screenshot("Verified!")),
            act(on_dashboard_login_page,
                login_without_otp_and_with_retries(dashboard_creds, retries_amount, logger=logger))
                .failure(just_log_error("Failed to connect to the dashboard without OTP..."))
                .success(just_log_success("Connected to the dashboard!")),
        ),
        drive_page(
            act(on_dashboard_welcome_page, verify_dashboard_welcome_page)
                .failure(log_error_with_current_url("Failed to verify..."))
                .success(log_success_with_current_url_and_take_screenshot("Verified!")),
        ),
    ]

retries_amount = max(get_max_workers(), 10) : on rejoue le login interne (au POM) au moins 10 fois, à cause des 10% d’échec aléatoire.
login_without_otp_and_with_retries(creds, retries_amount, logger=logger) : closure qui capture creds + nb retries + logger. Le connector retourne Callable[[DashboardLoginPage], DashboardLoginPage].
2 drive_page : login + welcome page. Chacun ouvre, vérifie, screenshot.
Log factories partout : aucune lambda inline.
SeleniumTitleMixin côté POM : get_current_title() est utilisé par le hook on_failure de act.

def dashboard_login_with_otp_happy_path(driver, logger):
    # ... setup pareil ...

    cache = in_memory_cache_with_30m_ttl
    fresh_cache_key_for_username = reserve_free_cache_key(cache)
    fresh_cache_key_for_otp_send_button_click_date = reserve_free_cache_key(cache)

    return [
        drive_page(
            act(on_dashboard_login_page, open_dashboard_login_page)...,
            act(on_dashboard_login_page, verify_dashboard_login_page)...,
            act(on_dashboard_login_page,
                start_to_login_with_otp_and_with_retries(
                    dashboard_creds, retries_amount,
                    cache=cache, logger=logger,
                    username_cache_key=fresh_cache_key_for_username,
                    otp_send_button_click_date_cache_key=fresh_cache_key_for_otp_send_button_click_date,
                ))...,
            act(on_dashboard_login_page, verify_otp_screen)...,
            act(on_dashboard_login_page,
                type_otp_with_retries(
                    retries_amount,
                    cache=cache, logger=logger,
                    username_cache_key=fresh_cache_key_for_username,
                    otp_send_button_click_date_cache_key=fresh_cache_key_for_otp_send_button_click_date,
                ))...,
        ),
        drive_page(
            act(on_dashboard_welcome_page, verify_dashboard_welcome_page)...,
            act(on_dashboard_welcome_page, click_on_go_to_nested_page_btn)...,
        ),
        drive_page(
            act(on_dashboard_protected_page, verify_dashboard_protected_page)...,
        ),
    ]

Trois drive_page. Cinq act dans le premier. Cache L1 + clés réservées pour partager des valeurs entre acts (cf. 08-caches-locks.md).

03.05 — Programmation déclarative

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

03.05 — Programmation déclarative#

Un scénario d’Ocarina décrit, il n’exécute pas. C’est ce qui le rend factorisable, multipliable, et lisible.

Démonstration#

return [
    drive_page(
        act(on_homepage, open_then_verify_homepage)
            .failure(just_log_error("Failed to reach the homepage..."))
            .success(log_success_with_current_url_and_take_screenshot("On the homepage!")),
        act(on_homepage, click_book_call_page_cta)
            .failure(just_log_error("Failed to click on the 'Book a call' CTA..."))
            .success(just_log_success("Clicked on the 'Book a call' CTA!")),
    ),
    drive_page(
        act(on_book_a_call_page, verify_book_call_page)
            .failure(just_log_error("Failed to verify the 'Book a call' page..."))
            .success(log_success_with_current_url_and_take_screenshot("On the 'Book a call' page!")),
    ),
]

Ce code n’exécute rien. Il décrit :

Chapitre 04 — Tests internes du framework

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

Chapitre 04 — Tests internes du framework#

Comment Ocarina se teste lui-même. Cinq familles de tests, une politique de couverture lucide, un rapport Allure historisé sur GitHub Pages.

Plan#

#	Fichier	Sujet
01	`01-strategy.md`	Stratégie « dehors comme un utilisateur » + le `conftest.py` (FakeDriver, RecordingPOM, builders).
02	`02-cram-prysk.md`	Cram tests (`prysk`) : fichiers `.t`
03	`03-pytest-scenarios.md`	Scénarios de test appliqués au framework (pytest + allure + hypothesis).
04	`04-mypy-plugins-types.md`	Tests sur le typage statiques via `pytest-mypy-plugins` (`*.yml`).
05	`05-syrupy-snapshots.md`	Snapshot tests (`syrupy`) pour `pretty_print_results` et `results_to_json`.
06	`06-hypothesis-properties.md`	Property-based testing pour les invariants.
07	`07-coverage-policy.md`	Politique de couverture : ce qui est testé, ce qui ne l’est PAS, pourquoi.
08	`08-allure-history.md`	Allure + action composite `allure-history` + déploiement GH Pages.

Tableau récapitulatif#

Famille	Outil	Quantité	Sujet	Cible
Scénarios	`pytest` + `allure-pytest`	~15 fichiers `test_*.py`	DSL, orchestration, acteur Playwright	Couvre le comportement
Cram	`prysk`	15 fichiers `.t`	CLI Selenium + Playwright : parsing, validations, defaults	Couvre la surface utilisateur CLI
Types statiques	`pytest-mypy-plugins`	~5 fichiers `*test_types.yml`	Inférences de type, narrowing, erreurs attendues	Couvre le typage
Snapshots	`syrupy`	2 fichiers `.ambr`	Sortie de `pretty_print_results`, `results_to_json`	Couvre le format de sortie
Property-based	`hypothesis`	1 fichier (`test_invariants_properties.py`)	Comportement sur valeurs aléatoires	Couvre la robustesse aux inputs

Approche#

Dans le fichier conftest.py :

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.06 — Scenario[Driver]

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

02.06 — `Scenario[Driver]`#

Fichier source : src/ocarina/custom_types/scenario.py

Dataclass#

@final
@dataclass(frozen=True)
class Scenario[Driver]:
    test_chain: TestChain
    setup: TestSetup = field(default=None)
    teardown: TestTeardown = field(default=None)
    watchers: TestWatchers[Driver] | None = field(default=None)

# src/ocarina/custom_types/test_components.py
type TestChain = Sequence[ChainRunner[Any]]
type TestSetup = Effect | None
type TestTeardown = Effect | None
type TestWatchers[Driver] = Sequence[Watcher[Driver]] | None

Cycle de vie (per attempt)#

1. setup()           — optionnel, Effect libre (DB, API, …)
       → lève     :  skip de test_chain, jump à teardown,
                     return Outcome(setup_failed=True, should_retry=True)
       → ok       :  continue à test_chain

2. test_chain        — la chaîne réelle (Sequence[ChainRunner])
       (les watchers tournent pendant ce temps)

3. teardown()        — optionnel, toujours exécuté
       → lève     :  log warning + ignore (n'affecte pas le verdict)

Si TOUTES les tentatives lèvent au setup :
    → test marqué SKIPPED (pas FAILED)
    → log warning « setup keeps failing »

`setup` et `teardown`#

setup et teardown sont driver-free et injectionless by design.

09.03.07 — Skills Refactor

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

09.03.07 — Skills Refactor#

Skills qui refactor la base de tests automatisés existante.

Listing (potentiellement non exhaustif)#

Skill	Cible
`refactor-fragmentation`	DRY selon préférence utilisateur
`introduce-pom-retries`	Retries internes aux POMs, avec dédoublement (first-try + with-retries)

`refactor-fragmentation`#

input  : la base de tests
output : suggestions de refactor DRY :
            - blocs répétés dans 3+ scénarios → extract en fragment
            - connectors quasi-identiques → extract un connector paramétré
            - séquences de log+screenshot répétées → extract un helper
         + recommandation au cas par cas

CLAUDE.md :

Chapitre 07 — ocarina-example, la suite canonique

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

Chapitre 07 — `ocarina-example`#

Suite e2e conçue pour tester l’Igoristan. C’est l’exemple de référence : tout projet Ocarina commence par lire ce dépôt et copier ses adapters.

Plan#

#	Fichier	Sujet
01	`01-tree.md`	L’arborescence `src/` complète : pages/, lib/, api/, caches/, constants/, tests/.
02	`02-adapters.md`	Les 5 adapters (`act`, `match_page`, `TestSuite`, `TestCampaign`, `EnvGetters`).
03	`03-scenarios-login.md`	Scénarios Dashboard login : happy / unhappy / data-driven.
04	`04-scenarios-corsicamon.md`	Scénarios Corsicamon : api_key, draw, add, back.
05	`05-scenarios-randomness.md`	Scénarios randomness (4 levels) : random_error, random_loaders, dsed, madness, chaotic_form, walkthrough.
06	`06-scenarios-sacred-upload.md`	Scénarios sacred upload : upload_files, back_to_igoristan.
07	`07-humanized-driver.md`	`HumanizedDriver` : proxy Selenium pour simuler la saisie humaine.
08	`08-caches-locks.md`	Cache L1 (`dogpile.cache.memory`) + clés réservées + locks Redis distribués.
09	`09-watcher-catch-me.md`	Le watcher `catch_me_if_you_can` pour le chaotic form.
10	`10-env-getters.md`	`EnvGetters[_CredsKeys, _ValuesKeys]` typé strictement via `Literal`.
11	`11-ci.md`	CI : `main_ci.yml` + `dev_ci.yml` (lint+typecheck) + `e2e.yml` (Redis + Firefox manuel).

Objectif#

Citation du Holy Book (chapitre « Premiers pas ») :

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

Scenarios 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#

07.01 — Arborescence

07.01 — Arborescence#

Sémantique des dossiers#

lib/ vs pages/#

03.03 — Évaluation paresseuse

03.03 — Évaluation paresseuse#

Zzz#

ChainRunner#

validate(...).execute()#

07.03 — Scénarios Dashboard login

07.03 — Scénarios Dashboard login#

dashboard_login#

Happy paths#

Test 1 : login sans OTP#

Test 2 : login avec OTP#

03.05 — Programmation déclarative

03.05 — Programmation déclarative#

Démonstration#

Chapitre 04 — Tests internes du framework

Chapitre 04 — Tests internes du framework#

Plan#

Tableau récapitulatif#

Approche#

02.03.06 — drive_page

02.03.06 — drive_page#

Code#

Pourquoi cet alias ?#

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

2. Discipline#

02.06 — Scenario[Driver]

02.06 — Scenario[Driver]#

Dataclass#

Cycle de vie (per attempt)#

setup et teardown#

09.03.07 — Skills Refactor

09.03.07 — Skills Refactor#

Listing (potentiellement non exhaustif)#

refactor-fragmentation#

Chapitre 07 — ocarina-example, la suite canonique

Chapitre 07 — ocarina-example#

Plan#

Objectif#

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`#

`lib/` vs `pages/`#

`ChainRunner`#

`validate(...).execute()`#

`dashboard_login`#

02.03.06 — `drive_page`#

02.06 — `Scenario[Driver]`#

`setup` et `teardown`#

`refactor-fragmentation`#

Chapitre 07 — `ocarina-example`#

`custom_types/`#