Ocarina — précis

00.01 — Cartographie de l'écosystème

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

00.01 — Cartographie de l’écosystème#

L’écosystème Ocarina est constitué de six dépôts publics sur le compte GitHub mojo-molotov. Ils s’organisent en cinq rôles distincts qui se composent :

Rôle	Dépôt	Forme
Framework	`ocarina`	Bibliothèque Python publiée sur PyPI
Application sous test (SUT) publique	`igoristan`	SPA React + Vike déployée sur GitHub Pages
Backend de coordination	`tests-workers`	API Vercel Edge + Upstash Redis
Suite d’exemples	`ocarina-example` (canonique), `ocarina-with-ai-example` (IA)	Projets Python e2e tournés vers l’Igoristan / CURA
Documentation publique	`ocarina-holy-book`	Site VitePress FR + EN, PDF, skills IA

Schéma d’ensemble (big picture)#

┌─────────────────────────────────────────────────────────────────────────────────┐
│                              OCARINA (BIG PICTURE)                              │
└─────────────────────────────────────────────────────────────────────────────────┘

   ┌──────────────────────────────┐         ┌──────────────────────────────────┐
   │  [PACKAGE]  ocarina          │ ──────► │  [PACKAGE]  ocarina-example      │
   │  Framework Python 3.14+      │   pip   │  Suite e2e contre l'Igoristan    │
   │  ROP / DSL / orchestration   │ install │  (Selenium + Firefox + Redis)    │
   └──────────────────────────────┘         └──────────────────────────────────┘
            │  │                                       │  ▲   │
            │  │                                       │  │  utilise
            │  │ pip install ocarina                   │  │  IGOR_API_KEY
            │  ▼                                       ▼  │   │
            │  ┌────────────────────────────────────┐  pilote │
            │  │ [PACKAGE]  ocarina-with-ai-example │  ┌──────┴──────────────────┐
            │  │ Suite e2e CURA Healthcare          │  │ [WEBSITE]  igoristan    │
            │  │ Claude Code, 99% machine           │  │ React 19 + Vike         │
            │  └────────────────────────────────────┘  │ GitHub Pages            │
            │              │                           └──────┬──────────────────┘
            │              │ pilote                           │ fetch OTP
            │              ▼                                  ▼
            │   ┌──────────────────────────────┐    ┌──────────────────────────────┐
            │   │ [WEBSITE]  CURA Healthcare   │    │ [BACKEND]  tests-workers     │
            │   │ Heroku, PHP open source      │    │ Vercel Edge Functions        │
            │   └──────────────────────────────┘    │ + Upstash Redis              │
            │                                       │ /api/otp, /otp-history,      │
            │                                       │ /api/corsicadex              │
            │                                       └──────────────────────────────┘
            │                                                 ▲
            │                                                 │ x-api-key
            │                                                 │ (IGOR_API_KEY ≡ API_SECRET)
            │                                                 │
            ▼
   ┌──────────────────────────────┐
   │  [DOCS]  ocarina-holy-book   │
   │  VitePress FR + EN + RU      │
   │  Skills IA, PDF, llms.txt    │
   │  GitHub Pages                │
   └──────────────────────────────┘

ocarina → suites d’exemples : dépendance Python classique (pip install ocarina).
Suites d’exemples → SUT (Igoristan / CURA) : pilotage navigateur via Selenium.
Suite Igoristan ↔ tests-workers : appels HTTP (OTP, Corsicadex) ; le secret partagé IGOR_API_KEY (côté client) ≡ API_SECRET (côté serveur).

Responsabilités#

Rôle	Contrat	Besoin
Framework	Donner le DSL, l’orchestration, la pool de drivers, les reporters	Doit être petit, auditable, sans dépendances cachées
SUT public	Offrir un terrain de jeu volontairement chaotique (random errors, OTP, formulaires capricieux)	Hébergé en permanence sur GitHub Pages, sans backend lourd
Backend de coordination	Coordonner les workers sur l’OTP, fournir des données pour les tests parallèles	Stateless côté code, l’état vit dans Redis (Upstash)
Exemples	Démontrer comment on utilise réellement Ocarina, à la fois sans IA (canonique) et avec IA (CURA)	Doivent être publics, exécutables, complets, suivis en CI
Documentation	Transmettre le pourquoi, le comment, et l’usage IA	Doit exister en EN + FR + RU (tradition corso-russe), exposer des fichiers adaptés aux LLMs comme `llms.txt`, générer des PDF

Trois licences#

Licence	Dépôts concernés	Pourquoi
MIT	`ocarina`, `ocarina-example`, `ocarina-with-ai-example`, `ocarina-holy-book`	Tout ce qui est code Python ou doc, transmissible « tel quel », souverain — voir `../11-independence/`.
ISC	`tests-workers`	Choix par défaut du scaffold Vercel Edge, conservé.
(aucune licence)	`igoristan`	Application démo publique, hébergée par l’auteur (à considérer comme WTFPL).

Points de friction volontaires entre dépôts#

Le design est volontairement asymétrique sur certains axes ; ces frictions sont des outils de test :

01.01 — Prendre le problème à l'envers

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

01.01 — Prendre le problème à l’envers#

Le constat#

Tous les frameworks de test e2e contemporains ont été construits sur un postulat implicite : il existe une barrière entre ceux qui codent et ceux qui définissent les tests. Cette barrière est tenue pour acquise : méthodologiquement, organisationnellement, parfois contractuellement.

La plupart des frameworks de test ont été conçus dans un monde où la barrière entre « ceux qui codent » et « ceux qui définissent les tests » était réelle et structurelle.

02.01 — Identité technique d'Ocarina

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

02.01 — Identité technique d’Ocarina#

`pyproject.toml`#

[project]
name = "ocarina"
version = "1.1.10"
description = "Websites test framework for Igor"
requires-python = ">=3.14"
authors = [{ name="Igor Casanova", email="[REDACTED]" }]
license = "MIT"
license-files = ["LICEN[CS]E*"]
readme = "README.md"

dependencies = ["python-docx>=1.2.0"]

version = "1.1.10" : le projet est en stable 1.x, pas en pré-version.
requires-python = ">=3.14" : le typage générique PEP 695 est utilisé partout.
dependencies = ["python-docx>=1.2.0"] : une seule dépendance d’exécution. Tout le reste est dans dev.
license = "MIT".
description = "Websites test framework for Igor" : pas « for everyone », pas « for humans », explicitement « for Igor ». Cohérent avec ../01-philosophy/05-political-stance.md : « C’est ma voiture. »

Dépendances `dev`#

[dependency-groups]
dev = [
    "ruff>=0.15.0",
    "mypy>=1.17.0",
    "mypy-extensions>=1.1.0",
    "typing-extensions>=4.14.0",
    "pytest>=9.0.0",
    "pytest-cov>=7.0.0",
    "hypothesis>=6.151.0",
    "pytest-mypy-plugins>=3.1.0",
    "allure-pytest>=2.15.3",
    "allure-python-commons>=2.15.3",
    "pre-commit>=4.5.1",
    "syrupy>=5.1.0",
    "selenium>=4.40.0",
    "playwright>=1.60.0",
    "twine>=6.2.0",
    "build>=1.4.2",
    "prysk>=0.20.0",
]

Outil	Rôle dans Ocarina
`ruff`	Linter + formatter (remplace flake8 + isort + black). `select = ["ALL"]`.
`mypy` (+ extensions)	Type-checker. `strict = true` (cf. `mypy.ini`).
`pytest`	Runner des tests unitaires (le framework est lui-même testé).
`pytest-cov`	Couverture de tests (du framework lui-même). Configurée dans `pyproject.toml#tool.coverage`.
`hypothesis`	Property-based testing (PBT) → `test_invariants_properties.py`.
`pytest-mypy-plugins`	Tests statiques de typage (vérifie les erreurs mypy attendues et tests d’inférence de types avec `reveal_type`).
`allure-pytest` / `allure-python-commons`	Rapport Allure (déployé sur GH Pages).
`pre-commit`	Hooks Git locaux (ruff-format).
`syrupy`	Snapshot testing (sortie de `pretty_print_results`, `results_to_json`).
`selenium`	Présent en `dev` parce qu’Ocarina ne dépend pas de Selenium pour fonctionner, livre juste un adapter Selenium pour être immédiatement opérationnel.
`playwright`	Même logique : un second adapter livré (depuis la `1.1.3`). Ocarina pilote désormais Selenium et Playwright out of the box, derrière les mêmes ports.
`twine` / `build`	Publication PyPI.
`prysk`	Tests CLI au format cram (`.t`). Successeur de `cram`.

`mypy.ini`#

[mypy]
python_version = 3.14
strict = true

# * ... Allow missing annotations (type inference is cool)
disallow_incomplete_defs = false

# * ... Allow missing annotations (type inference is cool)
disallow_untyped_defs = false

strict = true : active --warn-redundant-casts, --warn-unused-ignores, --no-implicit-optional, --check-untyped-defs, etc.
Deux exceptions : disallow_incomplete_defs et disallow_untyped_defs désactivés, car l’auteur estime que l’inférence de type de mypy est suffisante quand on n’a pas besoin d’expliciter. Toutes les annotations explicites sont là où elles comptent.

`pyproject.toml#tool.ruff`#

[tool.ruff.lint]
select = ["ALL"]
ignore = [
    "ANN002", "ANN003", "ANN201",
    "TRY003",
    "C901",
    "D203",    # conflit avec D211
    "D213",    # conflit avec D212
    "COM812",  # conflit avec le formatter ruff (auto-fix)
]

[tool.ruff]
exclude = ["**/.venv/**", "**/bin/**", "**/__init__.py", "**/__bypass_linter__"]

select = ["ALL"] : toutes les règles de ruff sont activées (~800).
Ignore list courte : six règles seulement, toutes justifiées.
B008 NE doit JAMAIS être ignoré (« # "B008", # * ... NEVER ignore this rule without knowing very well what you are doing: https://docs.astral.sh/ruff/rules/function-call-in-default-argument/ »). C’est une note pour ne pas répéter une erreur passée.
****/**bypass_linter**** : convention de répertoire pour héberger du code explicitement non-linté (utile pour des modules expérimentaux internes).

`pyproject.toml#tool.pytest.ini_options`#

testpaths = ["tests"]
python_files = ["test_*.py"]
norecursedirs = [".*", "__pycache__"]
log_cli = true
log_cli_level = "DEBUG"
log_cli_format = "%(asctime)s [%(levelname)s] %(name)s: %(message)s"
log_cli_date_format = "%Y-%m-%d %H:%M:%S"
addopts = """
--cov=src
--cov-branch
--cov-report=term-missing
--cov-report=html
--cov-report=xml:coverage.xml
"""

Réglage	Effet
`log_cli = true`	Tous les logs des tests apparaissent en CLI (utile pour les scénarios qui passent par `ILogger`).
`--cov=src` + `--cov-branch`	Couverture par branche, pas seulement par ligne.
`--cov-report=html` + `xml`	Trois sorties : terminal, HTML local, XML pour ingestion CI.

`pyproject.toml#tool.coverage`#

Voir le détail ici : ../04-internal-tests/07-coverage-policy.md. En bref : tout ce qui est shape (custom_types, ports, errors), ce qui requiert un navigateur réel (adapters Selenium), et ce qui est traversé par les cram tests (cli/store, cli/builder), est explicitement omis. Pour ne pas fausser les métriques.

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.

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

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

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

Type	Sémantique FP	Définition
`Effect`	Effet de bord (déféré)	`() -> None`
`Thunk[T]`	Computation déférée avec valeur	`() -> T` (paresse + valeur)
`Result[T]`	Computation qui peut échouer	Union discriminée `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.

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.

05.01 — Stack de l'Igoristan

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

05.01 — Stack de l’Igoristan#

`package.json`#

{
  "react": "^19.2.3",
  "react-dom": "^19.2.3",
  "vike": "^0.4.258",
  "vike-react": "^0.6.21",
  "valibot": "^1.2.0",
  "react-hook-form": "^7.71.1",
  "@hookform/resolvers": "^5.2.2",
  "react-dropzone": "^14.3.8",
  "lucide-react": "^0.562.0",
  "usehooks-ts": "^3.1.1",
  "throttleit": "^2.1.0",
  "uuid": "^13.0.0",
  "clsx": "^2.1.1",
  "class-variance-authority": "^0.7.1",
  "tailwind-merge": "^3.0.2",
  "tailwindcss-animate": "^1.0.7",
  "@radix-ui/react-slot": "^1.2.4"
}

Lib	Rôle
React 19.2	UI, hooks
Vike 0.4 + `vike-react`	SSG / SSR framework au-dessus de Vite (anciennement « vite-plugin-ssr »)
Valibot 1.2	Validation de schémas TS (alternative légère à Zod)
react-hook-form	Gestion de formulaires
react-dropzone	Composant drag-and-drop pour upload
lucide-react	Icones
usehooks-ts	Hooks utilitaires (`useLocalStorage`, etc.), utilisé par `useAuth`
throttleit	Throttle
uuid	Génération d’IDs
clsx + tailwind-merge + class-variance-authority	Utilitaires Tailwind

`devDependencies`#

{
  "vite": "^7.3.1",
  "@vitejs/plugin-react": "^5.1.2",
  "@tailwindcss/vite": "^4.1.3",
  "@tailwindcss/postcss": "^4.0.17",
  "tailwindcss": "^4.1.1",
  "terser": "^5.39.0",
  "vite-plugin-compression": "^0.5.1",
  "rollup-plugin-visualizer": "^5.14.0",
  "@qalisa/vike-plugin-sitemap": "^1.7.0",

  "typescript": "^6.0.3",
  "typescript-eslint": "^8.59.0",
  "eslint": "^9.18.0",
  "@eslint/js": "^9.39.2",
  "eslint-plugin-import-x": "^4.6.1",
  "eslint-plugin-perfectionist": "^4.6.0",
  "eslint-plugin-react": "^7.37.4",
  "eslint-plugin-react-hooks": "^5.2.0",
  "eslint-plugin-unused-imports": "^4.2.1",
  "globals": "^15.15.0",

  "prettier": "^3.5.3",
  "prettier-plugin-tailwindcss": "^0.6.11",

  "husky": "^9.1.7",
  "lint-staged": "^15.5.0",
  "commitizen": "^4.3.1",
  "@commitlint/config-conventional": "^19.8.0",
  "@commitlint/cz-commitlint": "^19.8.0",
  "is-ci": "^4.1.0",
  "editorconfig": "^2.0.1",
  "minimatch": "^10.1.1",
  "rimraf": "^6.0.1",
  "wireit": "^0.14.11"
}

`engines`#

{
  "node": "^24.x",
  "pnpm": "11.x"
}

→ Node 24, pnpm 11. packageManager: pnpm@11.x verrouille la version.

06.01 — Stack Vercel Edge

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

06.01 — Stack Vercel Edge#

`package.json`#

{
  "name": "tests-workers",
  "version": "1.0.0",
  "scripts": {
    "vercel-build": "echo 'Build skipped'"
  },
  "packageManager": "pnpm@11.2.2",
  "dependencies": {
    "@upstash/redis": "^1.36.2",
    "otplib": "^13.2.1"
  },
  "devDependencies": {
    "@types/node": "^25.2.0",
    "next": "^16.1.6",
    "@vercel/node": "^5.5.28",
    "typescript": "^5.9.3"
  },
  "license": "ISC"
}

Lib	Rôle
`@upstash/redis` (runtime)	Client Redis REST (pas TCP). Compatible Edge.
`otplib` (runtime)	Génération TOTP RFC 6238.
`next` (dev seulement)	Types uniquement (`NextRequest`). Pas d’app Next.js.
`@vercel/node` (dev seulement)	Types Vercel.
`@types/node` (dev seulement)	Types Node 22+.

Note : aucune dépendance runtime au-delà de @upstash/redis + otplib.
Le bundle est microscopique → cold start < 100ms.

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 :

08.01 — Code : 99% Claude, 1% Igor, intelligence : 50-50

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

08.01 — Code : 99% Claude, 1% Igor, intelligence : 50-50#

README#

A note to the reader#

This project is an experiment in AI-driven test engineering. In the interest of honesty about how it was built:

Claude Code Human

Code written 99% 1%

Intelligence 50% 50%

Almost every line was machine-written. The judgement behind it — what to test, what to distrust, when to dig and when to stop — was shared.

	Claude Code	Human
Code written	99%	1%
Intelligence	50%	50%

09.01 — Stack VitePress + Sugar Theme + plugins maison

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

09.01 — Stack VitePress + Sugar Theme + plugins maison#

`package.json`#

{
  "dependencies": {
    "@sugarat/theme": "0.5.17"
  },
  "devDependencies": {
    "@commitlint/config-conventional": "20.5.0",
    "@commitlint/cz-commitlint": "20.5.1",
    "@eslint/js": "10.0.1",
    "@types/node": "25.6.0",
    "commitizen": "4.3.1",
    "editorconfig": "3.0.2",
    "eslint": "10.2.1",
    "eslint-plugin-import-x": "4.16.2",
    "eslint-plugin-perfectionist": "5.9.0",
    "eslint-plugin-unused-imports": "4.4.1",
    "globals": "17.5.0",
    "husky": "9.1.7",
    "inquirer": "9.0.0",
    "is-ci": "4.1.0",
    "lint-staged": "16.4.0",
    "pagefind": "1.5.2",
    "prettier": "3.8.3",
    "sass-embedded": "1.99.0",
    "typescript": "6.0.3",
    "typescript-eslint": "8.59.0",
    "vitepress": "2.0.0-alpha.17",
    "vitepress-plugin-image-optimize": "1.5.1",
    "vue": "3.5.33"
  },
  "engines": {
    "node": "^24.x",
    "pnpm": "11.x"
  }
}

Lib	Rôle
`vitepress 2.0.0-alpha.17`	SSG framework, basé sur Vite
`@sugarat/theme`	Theme blog tier-1 (templates, sidebar auto, cover images)
`vue 3.5.33`	Requis par VitePress
`vitepress-plugin-image-optimize`	Optimisation des images au build
`pagefind 1.5.2`	Moteur de recherche statique (full-text, side-CDN)
`sass-embedded`	Compile SCSS (utilisé par `@sugarat/theme`)
Husky / lint-staged / commitlint	Mêmes outils que les autres dépôts (Conventional Commits)

`docs/.vitepress/config.mts`#

import { defineConfig } from 'vitepress';
import path from 'path';
import fs from 'fs';

import { generateSkills } from './plugins/skills';
import { generateLlms } from './plugins/llm';
import { generatePub } from './plugins/pub';
import { blogTheme } from './blog-theme';
import webpConfig from './plugins/webp';

const base = process.env.GITHUB_ACTIONS === 'true' ? '/ocarina-holy-book/' : '/';

export default defineConfig({
  locales: {
    root: {
      themeConfig: {
        outline: { label: 'Table of content' },
        skipToContentLabel: 'Skip to content',
        sidebarMenuLabel: 'Related articles',
        returnToTopLabel: 'Return to top',
        lastUpdatedText: 'Last update:'
      },
      description: "Ocarina is Igor's automated web browser testing framework.",
      title: 'The Ocarina Holy Book',
      label: 'English',
      lang: 'en'
    },
    fr: {
      themeConfig: {
        outline: { label: 'Sommaire', level: [2, 3] },
        returnToTopLabel: 'Retour en haut de page',
        lastUpdatedText: 'Dernière mise à jour :',
        skipToContentLabel: 'Passer au contenu',
        sidebarMenuLabel: 'Voir aussi'
      },
      title: "Le livre sacré d'Ocarina",
      label: 'Français',
      lang: 'fr'
    }
    ru: {
      themeConfig: {
        outline: {
          label: 'Оглавление',
          level: [2, 3]
        },
        skipToContentLabel: 'Перейти к содержанию',
        lastUpdatedText: 'Последнее обновление:',
        returnToTopLabel: 'Вернуться вверх',
        sidebarMenuLabel: 'Смотрите также'
      },
      title: 'Священная Книга Ocarina',
      label: 'Русский',
      lang: 'ru'
    }
  },
  vite: { ... },
  ...
});

1. `base`#

const base =
  process.env.GITHUB_ACTIONS === "true" ? "/ocarina-holy-book/" : "/";

→ En CI (GitHub Actions) : base = /ocarina-holy-book/ (préfixe GitHub Pages).
→ En local : / (sert depuis la racine du dev server).

09.03.01 — Skills Review

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

09.03.01 — Skills Review#

Lectures statiques, remontent des constats. Une grande famille. Permet à l’IA d’effectuer de la revue sur son projet de manière systématique.

Listing (potentiellement non exhaustif)#

Skill	Cible
`review-spec-gaps`	Questions de clarification sur les SFD
`review-watcher-misuse`	Vérifie le principe « négatif uniquement » de `watcher.report(...)`
`review-compartmentalisation-leaks`	Détecte URLs, sélecteurs, nombres magiques aux mauvais endroits
`review-dead-code`	Détecte connecteurs / POMs / scénarios / suites / fragments / constantes non utilisés
`review-report`	Classifie chaque FAIL / SKIP d’une exécution
`review-type-ignore`	Audite les `# type: ignore` (sont-ils justifiés ?)
`review-match-candidates`	Identifie les endroits où un `match` (Python, pattern matching) pourrait être utilisé plutôt que des `if` `elif` `elif` `if` `if` `elif`
`review-unverified-transitions`	Vérifie qu’à chaque transition de page, il y a un `verify`
`review-submit-dispatchers`	Audite les méthodes de confirmation de saisie (clic vs touche entrée…)
`review-comment-drift`	Détecte les commentaires qui sont désynchronisés avec le code
`review-suite-stability`	Évalue la stabilité d’une suite (proportion de retries, transient_errors hits)
`review-intent-collisions`	Détecte les tests qui s’écrasent mutuellement (intentions contradictoires) et demande/propose des clarifications
`review-watcher-emissions`	Audite les émissions de watchers (volume, déduplication, pertinence)
`review-hierarchy-naming`	Audite le nommage de la hiérarchie (`TestCycle` / `TestCampaign` / `TestSuite` / `Test`) pour repérer l’antipattern où un enfant reprend le nom du parent

`review-dead-code`#

input  : base de tests
output : liste des éléments non utilisés (connectors / POMs / scénarios / fragments / constantes)
         + recommandation par élément :
            - supprimer
            - mettre en incubateur (<racine-source>/incubator/, arbre de dépendances préservé)
            - conserver (justifier)

`review-report`#

input  : une exécution récente (logs + reports)
output : classification de chaque test :
            - PASS                  (rien à faire)
            - SKIP                  (pourquoi ?)
            - intentional gap FAIL  (G-DATA-*, G-SEC-*, ...)
            - cross-browser FAIL    (B-BROWSER-*)
            - transient FAIL        (A-ENV-*)
            - régression            ⚠️ ALERTE

`review-watcher-misuse`#

input  : tous les watcher.report(...)
output : liste des reports qui semblent positifs (« success », « completed », « ok », ...)
         → recommandation : supprimer ou reformuler en négatif

`review-comment-drift`#

input  : tous les commentaires du code
output : liste des commentaires qui semblent ne plus correspondre au code adjacent
         (typique : commentaire mentionne foo, code mentionne bar)

Aide à éliminer les commentaires obsolètes.
« Teach the pattern, not the symptom ».

10.01 — Matrice récapitulative des workflows

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

10.01 — Matrice récapitulative des workflows#

Vue d’ensemble synthétique de tous les workflows de l’écosystème.

Récap.#

Dépôt	Workflow	Trigger	OS	Stack	Effet	Détail
`ocarina`	`main_ci.yml`	push/PR main, dispatch	ubuntu + windows × py 3.14 (option 3.15-dev)	venv cache, make install-on-ci	make check-coding-style + make test + Allure history + Pages deploy	`02-ocarina-workflows.md`
`ocarina`	`dev_ci.yml`	push dev/feature/fix, PR dev, dispatch	ubuntu × py 3.14	venv cache	check-coding-style + test + récap couverture (non bloquant)	`02-ocarina-workflows.md`
`ocarina`	`unstable_python_full_build.yml`	cron (mensuel), dispatch	ubuntu + windows × py 3.15-dev	`PIP_ONLY_BINARY=":all:"`	full build sur Python pré-release	`02-ocarina-workflows.md`
`ocarina-example`	`main_ci.yml`	push/PR main, dispatch	ubuntu + windows × py 3.14	venv cache	check-coding-style	`03-example-workflows.md`
`ocarina-example`	`dev_ci.yml`	push dev, dispatch	ubuntu × py 3.14	venv cache	check-coding-style	`03-example-workflows.md`
`ocarina-example`	`e2e.yml`	dispatch (env `OC`)	ubuntu + service `redis:8.x` + Firefox + geckodriver 0.35.0	venv cache	run complet, upload traces	`03-example-workflows.md`
`ocarina-with-ai-example`	`ai_proof_ci.yml`	push main, PR, dispatch	ubuntu × py 3.14	venv cache	ruff format check + ruff check + mypy	`04-ai-workflows.md`
`ocarina-with-ai-example`	`ai_proof_e2e.yml`	dispatch	ubuntu × matrice firefox+chrome	venv cache, geckodriver 0.36.0 / chromedriver auto-matché	warm-up Heroku dyno, run, filtrage sed des stacktraces ChromeDriver, upload	`04-ai-workflows.md`
`igoristan`	`ci-pr.yml`	PR `**`, dispatch	ubuntu × node 24 + pnpm 11	wireit	format check + lint + typecheck (parallélisés)	`05-igoristan-workflows.md`
`igoristan`	`deploy.yml`	push main, dispatch	ubuntu × node 24 + pnpm 11	concurrency group `pages`	`pnpm install --frozen-lockfile` + `pnpm build` + upload Pages	`05-igoristan-workflows.md`
`ocarina-holy-book`	`deploy.yml`	push main, PR, dispatch	ubuntu × node 24 + pnpm 11	`TZ=Europe/Paris`, concurrency group `pages`	`pnpm install` + `pnpm build` + upload Pages	`06-holy-book-workflow.md`
`tests-workers`	aucun	—	—	Vercel	`vercel deploy`	`07-tests-workers-vercel.md`

Action composite#

Action	Localisation	Usage
`allure-history`	`ocarina/.github/actions/allure-history/action.yml`	Composite : Bun + Allure 3.9.0 + restore/save `history.jsonl` sur branche dédiée

Patterns#

Workflows PR (légers, auto)#

ocarina/main_ci.yml                                       # python 3.14
ocarina/dev_ci.yml
ocarina-example/main_ci.yml
ocarina-example/dev_ci.yml
ocarina-with-ai-example/ai_proof_ci.yml
igoristan/ci-pr.yml

Tous tournent rapidement.

11.01 — Grammaire souveraine

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

11.01 — Grammaire souveraine#

Pas de DSL imposé. Pas d’écosystème de plugins. Extension par composition, jamais par héritage.

Vision#

Citation du Holy Book (chapitre « Qu’est donc Ocarina ? ») :

Et si déléguer sa grammaire à des “standards” n’avait jamais été une bonne idée ?

Le vrai hiatus du test E2E n’est pas d’imposer la “meilleure” novlangue. Réponse simple : Ocarina est extensible.

On y crée les verbes et conjonctions que l’on veut, le tout régi par des règles strictes qui poussent l’ensemble à rester profondément cohérent.

12.01 — Toutes les citations du manifeste, sourcées

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

12.01 — Toutes les citations du manifeste, sourcées#

Le Holy Book est truffé de citations dont la provenance n’est jamais annoncée dans le texte. Ce sont des mots de passe : si tu les reconnais, tu sais d’où vient l’auteur ; sinon, tu lis le slogan sans le sous-texte.

Listing#

#	Citation (Holy Book)	Auteur / Source	Année
1	« In the Lulzboat, salute, bitch, and show some respect. »	YTCracker — `#antisec` (single, theme song officiel d’Operation AntiSec). Track sur Spotify, page Wikipedia YTCracker	22 juin 2011
2	« THE FUCK YOU THINK THIS IS? You HOLLOW! YOU HOLLOW, YOU UNDERSTAND ME? YOU’RE WORTHLESS, YOU’RE FUCKING TRASH! », signé « (btw: RIP, DG descendant…) », puis prolongé en français : « ON VA TE REMPLACER ET TU RETOURNERAS HARCELER TES PAIRS SUR DOTA ET TE BRANLER SUR DES MACROS VBA COMME UNE MERDE ! […] YOU FUCKED WITH US! »	Yung Innanet (kayos) — paroles de `true colors`, SoundCloud — queed-inc/true-colors. Sysadmin originel de VX Underground, profil GitHub. Décédé le 18 octobre 2025. Le DG descendant désigne Digital Gangster, le forum de YTCracker. Cf. `06-yung-innanet-vxug.md`	—
3	« Of currency minted from factoring digits » (en français dans le Holy Book : « ces monnaies forgées de la factorisation des nombres »)	YTCracker — `Cryptoilluminati` (album A Side Quest for Fractional Cents). SoundCloud. La line exacte : « Told you to snap up a modest position / Of currency minted from factoring digits / Which of you listened? »	2022
4	« We Can Do All What You Can’t Do. »	Mantra du collectif indonésien YogyaCarderLink (YCL), un des premiers groupes carding / defacement basé à Yogyakarta. Cf. `05-indonesian-hackers.md`	début 2000s
5	« I’m the bug you can’t kill. » — Holy Book : « Je suis le bug dont tu ne pourras jamais te débarrasser. »	Non attribuable de façon fiable. Idiome de la scène hackers des années 2000s, dans la lignée de « I’m the null at the end of the string » (YTCracker, Nerdlife, 2006). Cf. `03-ytcracker-nerdcore-digital-gangster.md`
6	« HACK THE PLANET »	Slogan emblématique de la scène hackers des années 1990. Origine populaire : film *Hackers* (1995, Iain Softley), cri de guerre du personnage Cereal Killer. Repris par la scène réelle (mailing lists, defaces, conférences).	1995 (popularisation)
7	« YOU FUCKED WITH US! » / « Don’t fuck with us. »	Renvoi direct au mantra `Don't fuck with us`, signature récurrente des pages de deface de YogyaCarderLink et plus largement de la scène carding/defacement des années 2000s. Le passage du futur/présent (« don’t », avertissement) au passé (« you fucked », constat) est le pivot rhétorique : on vous avait prévenu, vous l’avez fait quand même. Cf. `05-indonesian-hackers.md` et `02-lulzsec-lulzboat-antisec.md`	années 2000s
8	« Putains de skids. Putains de normies ! »	Termes natifs IRC : `skid` = abréviation de script kiddie ; `normie` = utilisateur lambda / non-initié. Pas une citation attribuable, c’est du EFnet / 2600 / Digital Gangster. Cf. `04-zoneh-irc-efnet.md`	—
9	« de Zone-H à une vie rangée »	Zone-H = archive publique des defaces, fondée le 2 mars 2002 par Roberto Preatoni (Sys64738). Cf. `04-zoneh-irc-efnet.md`	2002
10	« CODE IS LAW »	Lawrence Lessig, Code and Other Laws of Cyberspace, MIT 1999. Cri d’alerte sur la réglementation par le code. Récupéré comme idéal par la crypto / Ethereum à partir de 2015.	1999 / 2015
11	« Lire aussi : Haters, par Paul Graham. »	Essai de Paul Graham (co-fondateur Y Combinator), `paulgraham.com/fh.html`. Sur les commentaires hostiles en ligne.	—
12	« I won’t let you pay me for my open source — Fuck You »	David Heinemeier Hansson (DHH), créateur de Ruby on Rails. Post du blog Hey.	—
13	« Retry flaky blocks. »	Yegor Bugayenko, Prompt (`github.com/yegor256/prompt`). Auteur de Angry Tests.	—
14	« Un idiot admire la complexité, un génie admire la simplicité… »	Terry Davis (1969–2018), créateur de TempleOS. Considéré par certains comme « le programmeur le plus intelligent qui ait jamais existé ». Programmeur atteint de schizophrénie et ayant été l’une des victimes les plus emblématiques du cyber-harcèlement.	—
15	« Pour avoir de la connaissance, ajouter des choses chaque jour. Pour avoir de la sagesse, enlever des choses chaque jour. »	Lao-Tseu, Tao Te Ching. Alternative pour ceux qui n’osent pas citer Terry A. Davis en raison des polémiques.	6e siècle av. J.-C.
16	« La perfection est atteinte non pas lorsqu’il n’y a plus rien à ajouter, mais lorsqu’il n’y a plus rien à retirer. »	Antoine de Saint-Exupéry, Terre des Hommes (1939).	1939
17	« Le style, pour l’écrivain aussi bien que pour le peintre, est une question non de technique, mais de vision. »	Marcel Proust (entretien).	—
18	« Pour l’instant, vivez les questions… »	Rainer Maria Rilke, Lettres à un jeune poète (1903-1908).	1903-1908
19	« La meilleure façon de résoudre un problème est souvent d’en sortir. »	Attribué à Alan Watts.	—
20	« Bonne continuation. » / « Peace out. » → YTCracker — Robots Will Definitely Take Your Job	YTCracker, SoundCloud. Le titre est la thèse : l’IA va remplacer les codeurs incompétents. L’expression « Peace out » est régulièrement utilisé dans cette communauté comme une manière de saluer, avec une certaine non-chalance/froideur.	—

Lectures connexes#

Axe scène hackers (1, 7, 9, 11) → 02-lulzsec-lulzboat-antisec.md, 04-zoneh-irc-efnet.md
Axe YTCracker / Nerdcore (1, 3, 5, 20) → 03-ytcracker-nerdcore-digital-gangster.md
Axe indonésien (4) → 05-indonesian-hackers.md
Axe Yung Innanet (2) → 06-yung-innanet-vxug.md
Axe philosophique / sagesse (14, 15, 16, 17, 18, 19) → déjà couvert dans ../01-philosophy/04-citations-and-influences.md
Axe politique du code (10, 11, 12, 13) → déjà couvert dans ../01-philosophy/05-political-stance.md

Pourquoi la source compte#

Le Holy Book ne cite jamais ses sources. Pas par négligence, par convention de scène : si tu reconnais, c’est que tu en fais partie ; si tu ne reconnais pas, tu lis le texte surface, ce qui marche aussi. C’est un dispositif littéraire vieux comme les communautés underground. LulzSec le faisaient sur leurs pastebins.

99.01 — Glossaire

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

99.01 — Glossaire#

Terminologie utilisée dans l’écosystème Ocarina. Sources d’origine entre parenthèses.

Railway Oriented Programming (ROP)#

Terme	Définition
ROP (Wlaschin, F#)	Pattern fonctionnel : succès et échec sont deux rails parallèles ; un échec bascule le calcul sur le rail d’échec, où il reste (court-circuit).
`Result[T]`	Union discriminée `Ok[T] \| Fail`. Erreur portée comme valeur, pas comme exception levée.
`Ok[T]`	Wrapper de succès, `value: T`.
`Fail`	Wrapper d’échec, `error: Exception`.
`is_ok`, `is_fail`	`TypeGuard` qui narrowent un `Result[T]` vers `Ok[T]` ou `Fail`.
`Action[T]`	`Thunk[Result[T]]` — fonction sans argument qui rend un `Result[T]`.
`ActionStart[T]`	État initial du builder d’action ROP. Attend `.failure(...)`.
`ActionFailure[T]`	Après `.failure(...)`. Attend `.success(...)`.
`ActionSuccess[T]`	Après `.success(...)`. Attend `.execute()`.
`ActionChain[T]`	Après `.execute()`. Porte `has_failed: bool` et `result: Result[T]`. Permet `.then(...)`.
`NeutralActionStart[T]`, `NeutralActionFailure[T]`, `NeutralActionSuccess[T]`	États inertes du rail d’échec. Bouchonnent en ne faisant plus rien.
`ChainRunner[T]`	Encapsulation paresseuse d’un `ActionChain`. Exécutée par `.run()`.
`drive_page`	Alias sémantique opinionated pour `chain_actions`. « Prendre le contrôle d’une page ».
`match_page` / `when`	Branchement conditionnel. First-match wins.
`create_act`	Primitive de bas niveau pour créer `act` (pas de test). Wrappée par le projet utilisateur.
`act` (côté projet)	Wrapper utilisateur de `create_act` avec hook `on_failure` spécifique au projet. Permet de représenter un pas de test.

ISTQB / vocabulaire professionnels du test#

Terme	Définition
ISTQB	International Software Testing Qualifications Board. Organisme professionnel du test logiciel.
Test cycle	Niveau le plus haut. Une exécution complète.
Test campaign	Niveau sous le cycle. Non défini directement dans l’ISTQB mais reconnu dans le vocabulaire des testeurs de métier.
Test suite	Niveau sous la campagne. Une collection de tests exécutables.
Test case	Un cas de test. Unité atomique.
Test step	Un pas de test. Action atomique dans un test case.
Smoke test	Vérification minimale qui prouve que le système est en marche. Si échec, le reste est inutile.
Setup / Teardown	Pré-condition / post-condition d’un test.

Ocarina (orchestration)#

Terme	Définition
`Test[Driver]`	Test ISTQB. Métadonnées + scenario factory + fragments + skip.
`TestSuite[Driver]`	Suite ISTQB. Parallélisation (thread pool), saturation, filtrage IDs, retries.
`TestCampaign[Driver]`	Campagne. Séquence de suites avec config workers partagée.
`TestCycle[Driver]`	Cycle ISTQB. Smoke (avec modes `fail-fast` vs `wait-for-all`) + main.
`TestExecutor[Driver]`	Exécute une seule tentative d’un test. Stateless.
`TestFlow[Driver]`	Boucle de rejeu (1+max_retries) avec backoff linéaire.
`TestRunner[Driver]`	Sortie de `Test.spawn(driver, logger)`. Agrégateur de chain_runners + setup + teardown + watchers.
`Scenario[Driver]` (frozen dataclass)	Encapsule `test_chain`, `setup`, `teardown`, `watchers`.
`TestChain`	`Sequence[ChainRunner[Any]]`. La séquence à exécuter pour appliquer le test.
`Watcher[Driver]`	Daemon thread pour observer quelque chose en plus sur un test. Callback périodique.
`Saturation`	Mécanisme de clonage aléatoire de tests pour atteindre `max_workers`. Copies nommées `[COPY N] <name>` (ou `[+N]` selon convention).
`Transient errors`	Tuple d’exceptions qui déclenchent un rejeu.
`max_retries_per_test`	Nombre de rejeux. Par défaut, 8 (« 9 vies comme un chat 🐱 »).
`autoscreen_on_fail`	Capture automatique de captures d’écran lors d’un pas de test en échec.

Ocarina (DSL invariants)#

Terme	Définition
`validate(value, name="...")`	Entry-point du DSL d’invariants.
`ValidationStartBlock[T]`	État initial. Attend `.assert_that(...)`.
`ValidationAssertBlock[T]`	Après `.assert_that(...)`. Accepte `.assert_that`, `.otherwise`, `.then`, `.execute`.
`.assert_that(predicate)`	Ajoute un AND logique.
`.otherwise(predicate)`	Ajoute un OR logique. Combine via `_any_of`.
`.then(new_value)`	Change la valeur en cours dans la chaîne. Conserve les erreurs accumulées.
`.execute()`	Exécute la chaîne, retourne un `_ValidationResult` (inerte tant qu’on n’appelle pas `.raise_if_invalid()`).
*`chain_validations()`**	Merge plusieurs `ValidationAssertBlock` en un seul.
`InvariantViolationError`	Exception levée par les prédicats.
`AggregateInvariantViolationError`	Agrégation de plusieurs `InvariantViolationError`. Levée par `.raise_if_invalid()`.
`DuplicatesError`	Sous-classe d’`InvariantViolationError` levée par `has_unique_elements`.
`BusinessInvariantValidator.create`	Factory pour invariants métier.
`FrameworkInvariantValidator.create`	Factory pour invariants framework.

Ocarina (infra + ports)#

Terme	Définition
`POMBase`	ABC framework-agnostic. Méthodes `verify` + `get_current_title`.
`SeleniumTitleMixin`	Mixin Selenium-specific. Implémente `get_current_title` et type `_driver: WebDriver`.
`WebDriversPool[Driver]`	Pool thread-safe de drivers. Sémaphore + Queue (la QUEUE putain !) + warmup avec watchdog.
`WarmupTimeoutError`	Levée par `pool.warmup()` quand ça coince.
`DriverBuilder[Driver]`	Builder qui gère le profile tmp dir et produit `(driver, dispose)`.
`BuiltWebDriver[Driver]`	`tuple[Driver, Effect]` — driver + dispose.
`Screenshotter[TDriver]`	Utilitaire de capture thread-safe. Burst mode, healthcheck.
`ScreenshotterConfig[TDriver]`	Config (frozen dataclass) : output_dir, file_ext, health_check, save_full_page, etc.
`ActCounter`	Interface. Compte les `act` appelés par tentative.
`ThreadsBasedActCounter`	Implémentation thread-local d’`ActCounter`.
`ILogger`	Port (ABC) de logging. Méthodes : `debug`, `info`, `warning`, `error`, `critical`, `success`, `test_name`, `exception`, `raw`, `set_prefix`, `set_domain_taxonomy`, `cleanup`.
`ITakeScreenshot[Driver]`	Protocol `(driver, logger, category) -> None`.
`PrintLogger` / `FileLogger` / `PrintAndFileLogger` / `MutedLogger`	4 implémentations canoniques d’`ILogger`.
`driver_healthcheck(driver)`	Ping `driver.title` ; lève `DriverDiedError` si LE DRIVER EST DEAD.
`DriverDiedError`	Exception levée par `driver_healthcheck`.
`PageVerificationError`	Exception levée par `POM.verify` quand la page n’est pas la bonne.
`NoMatchingBranchError`	Exception levée par `match_page` quand aucun `when` ne match.

Ocarina (opinionated)#

Terme	Définition
`CliBuilder`	Builder déclaratif au-dessus d’argparse. Agrégation des erreurs.
`CliArg`	Déclaration d’un argument CLI.
`CliStore[TKeys]`	Store write-once des valeurs CLI parsées. `TKeys: Literal[...]` pour autocomplétion.
`_CliField[T]`	Field write-once avec validator.
`phantom_validate`	No-op validator pour les fields qui n’ont pas besoin de validation supplémentaire.
`CliStoreSingleton`	Singleton autour de `CliStore`.
`create_selenium_auto_cli_store()`	Factory qui dispatch par OS.
`bootstrap(test_cycle, run_plugins, post_exec)`	Point d’entrée canonique.
*`run_plugins(plugins, exceptions_logger)`**	Exécute les plugins en parallèle si N>1.
`pretty_print_results`	Plugin d’affichage des résultats dans le terminal (ANSI).
`generate_docx_proof`	Plugin de créations de preuves de test au format DOCX.
`generate_json_results`	Plugin qui retranscrit les mêmes résultats que `pretty_print_results`, mais au format JSON.
`timing`	Context manager qui mesure la durée.

Programmation fonctionnelle#

Terme	Définition
`Effect`	`Callable[[], None]` — fonction sans argument ni retour, déférée.
`Thunk[T]`	`Callable[[], T]` — fonction sans argument, déférée.
`Closure`	Fonction qui capture un environnement.
`Fold` / `reduce`	Réduction d’une séquence à une seule valeur (catamorphisme).
`TypeGuard`	PEP 647 — annotation qui narrow un type côté type checker.
`Discriminated union`	Union de types disjoints, discriminée par un test (typiquement `isinstance`).
`Sealed union`	Discriminated union dont tous les variants sont `@final`.
`@final`	PEP 591 — annonce qu’une classe ne peut pas être sous-classée (pas de covariance infinie).
`Self`	PEP 673 — type de retour qui réfère à la classe instanciée (pas la classe déclarée).
`Protocol`	PEP 544 — type structurel ; tout objet avec la bonne shape est utilisable.
`PEP 695`	Generics syntax `class Foo[T]:` (Python 3.12+).

Vocabulaire de l’auteur#

Terme	Sens
Slipologue	Néologisme. Celui qui prétend « tout savoir » sans pratique. Pollue les discussions techniques avec des vues de l’esprit. Nous casse les couilles à utiliser ChatGPT ou Wikipédia pour toujours avoir réponse à tout en faisant comme s’il parlait d’un sujet qu’il maîtrise alors que non.
Vues de l’esprit	Concept imaginaire ; vision théorique inapplicable.
Boîte blanche	Code auditable, lisible, sans logique cachée. Opposé à boîte noire.
Donnée brute	Code source, fichiers, formats simples.
Astrologie de la programmation	Patterns ésotériques sans bénéfice mesurable.
In the Lulzboat, salute, bitch, and show some respect.	Citation de YTCracker — `#antisec` (2011), hymne officiel de l’Operation AntiSec. Voir `../12-manifesto-deciphered/01-sourced-citations.md`
Putains de skids, putains de normies	Marqueur identitaire IRC / EFnet.

Scène hacker (chapitre 12)#

Terme	Définition
AntiSec movement (1999)	Mouvement opposé à l’industrie de la cybersécurité et à la full disclosure. Refus de publier exploits / vulnérabilités. Cibles : SecurityFocus, Packet Storm, mailing list Bugtraq, etc.
Operation AntiSec (2011)	Résurrection du mouvement par LulzSec + Anonymous. 50 jours de hacks (mai-juin 2011).
LulzSec	Groupe d’hackers actif mai-juin 2011. Splinter d’Anonymous. Manifeste « we do it for the lulz ». Arrestations en 2012.
The Lulzboat	Métaphore identitaire de LulzSec. ASCII art de bateau pirate signant leurs communiqués.
Sabu	Hector Monsegur, leader LulzSec, soulevé par le FBI en juin 2011.
Topiary	Jake Davis, spokesperson LulzSec.
YTCracker	Bryce Case Jr. (né 1982). Rappeur nerdcore, ancien black hat (NASA Goddard 1999), fondateur de Digital Gangster (forum, 2005).
Nerdcore	Sous-genre du hip-hop dont les paroles sont réellement pour les nerds (code, hacking, sci-fi, math). Inventé par MC Frontalot (2000).
Digital Gangster	Forum hacker fondé par YTCracker en 2005 (`digitalgangster.com`). 36 000 membres au pic. Source de plusieurs hacks emblématiques (Paris Hilton, Miley Cyrus, Twitter Obama, etc.).
NerdRap Entertainment System	Album fondateur de YTCracker (2005). Beats sur OSTs NES, lyrics Nerdcore.
Darknet Diaries	Podcast de Jack Rhysider sur l’histoire de la cybersécurité. *L’épisode 78 (Nerdcore)* est consacré à YTCracker. Transcript : https://darknetdiaries.com/transcript/78/
Zone-H	Archive publique des defaces de sites web (fondée 2 mars 2002 par Roberto Preatoni / Sys64738, basée en Estonie). Tableau d’affichage de la scène grey hat 2002-2015.
IRC	Internet Relay Chat (1988). Protocole de chat textuel multi-utilisateurs en client/serveur. Médium social central des hackers 1993-2012.
EFnet	Eris-Free Network. Réseau IRC historique (1990). Centre de la scène warez, 0day, phreakers 1996-2008.
Channel (`#name`)	Salon IRC.
`skid` / script kiddie	Hacker qui exécute des scripts qu’il ne comprend pas. Insulte.
`normie`	Utilisateur lambda, non-initié. Insulte.
`lamer`	Variante BBS-era de skid.
`gr33tz`	Greetings, liste du crew, en bas d’un deface.
`zine`	E-zine, magazine underground souvent ASCII.
VX Underground (VXUG)	Repository public de samples de malware (fondé ~2019 par smelly_vx). Sysadmin originel : Yung Innanet / kayos.
Yung Innanet / kayos	Sysadmin originel de VX Underground et musicien. Décédé le 18 octobre 2025. Le Holy Book cite directement les paroles de son morceau `true colors` (SoundCloud), signé « (btw: RIP, DG descendant…) ».
YogyaCarderLink (YCL)	Collectif d’hackers indonésiens (Yogyakarta), début 2000s. Deux mantras récurrents sur leurs defaces : « We Can Do All What You Can’t Do. » et `Don't fuck with us.`
Honker (红客)	Red hacker chinois. Hacker patriote, motivé idéologiquement. Apparu après les émeutes Indonésie 1998.
Vilains but not Monsters	Distinction morale au cœur de la scène hackers : un Vilain confronte le pouvoir, un Monster persécute des faibles. Les véritables passionnés détestent les monsters (qui sont souvent d’anciens harcelés reproduisant le mal subi).
DEF CON	Conférence hacker annuelle à présent à Las Vegas (autrefois au Caesars Forum).
BOFH (Bastard Operator From Hell)	Série de fiction par Simon Travaglia (Nouvelle-Zélande), publiée sur Usenet dans les années 90 puis sur The Register. Archétype du sysadmin qui méprise ses utilisateurs. Source du vocabulaire PEBKAC, RTFM, ID-10-T error.
Usenet	Système distribué de newsgroups. Médium fondateur de la culture hacker.
Shodan	Moteur de recherche pour devices connectés à internet (caméras IP, ICS, IoT, serveurs ouverts). Fondé par John Matherly. `shodan.io`
ViolVocal	Communauté francophone (mi-2000s) de prank callers / harceleurs téléphoniques organisés sur forum + serveur Mumble/TeamSpeak. Pratique du SIP spoofing, streams publics des appels, doxing, usurpations d’agents de police pour consulter des TAJ sans habilitation, etc. Fermé après poursuites. Cas francophone de la cruauté underground.
4chan / /b/	Imageboard fondé par moot (Christopher Poole) en 2003. /b/ = board sans règles, sans archive, anonymat total. Matrice d’Anonymous (2006-2008) et de la culture meme moderne. Communauté orchestrant régulièrement du harcèlement, ayant particulièrement dégradé la santé de Terry A. Davis.
Anonymous	Entité collective émergée de 4chan /b/ vers 2006-2008. Op Chanology (Scientologie 2008), Op Tunisia (2011), Op Sony (2011). Coordination IRC.
Doxing	Publication d’informations personnelles d’une cible dans le but de lui nuire.
Swatting	Faux appel d’urgence (souvent SIP-spoofed) déclarant un crime grave à l’adresse de la victime, déclenchant l’envoi du SWAT. Cas mortels documentés.
OSINT	Open Source Intelligence. Collecte d’informations à partir de sources publiques.
OPSEC	Operations Security. Maintien rigoureux de l’anonymat opérationnel sur la durée.
Honeypot	Faux serveur / faux compte / faux leak appâtant les attaquants pour les détecter. Outil défensif de la scène.
Snitch / Fed	Poucave / agent fédéral undercover. Détection prioritaire dans toute communauté underground.
Prompt injection	Insertion de contenu malveillant dans le contexte d’un LLM pour détourner son comportement. OWASP LLM01:2025. Premier rang du Top 10 LLM.
MCP (Model Context Protocol)	Protocole standard Anthropic (2024) pour exposer tools et resources à un LLM. Chaque MCP server tiers ajoute une surface d’attaque.
Hard-won rules	Conventions internes à un projet documentées dans `CLAUDE.md` après leçons coûteuses. Évite aux LLMs de répéter les erreurs déjà rencontrées.

Idéologie Ocarina#

Terme	Définition
Vilain (au sens hacker)	Identité revendiquée du hacker souverain qui agit hors institutions, par opposition aux conventions et au branding corporate. Le Vilain confronte le pouvoir mais respecte les plus faibles.
Monster (au sens hacker)	Celui qui exploite techniquement sa compétence pour persécuter des personnes vulnérables (harceleur, doxeur, etc.). Ennemi structurel de la vraie scène hackerss.
Culture du tooling	Conviction que les bons outils techniques (Nmap, Wireshark, Metasploit, Burp, sqlmap, et al.) bien écrits par des petites équipes valent mille présentations marketing.
Tribal loyalty (scène hackers)	Loyauté absolue intra-communauté + méfiance extrême envers l’extérieur. Tests d’admission longs, vouching par membres établis, excommunication brutale en cas de trahison.
Eyes everywhere	Hyper-vigilance opérationnelle apprise dans le contexte underground (admin IRC légalement responsable des actions de ses canaux).

Industrie / contre-modèles#

Terme	Définition
Infopreneur	Entrepreneur dont le produit est de l’information vendue : formations, e-books, masterminds. Modèle américain (Dan Kennedy, Russell Brunson), importé en France via Tugan Bara.
Copywriting	Art d’écrire des textes de vente persuasifs. Cœur de métier infopreneur. Largement automatisable par IA depuis 2023.
Funnel	Tunnel de vente : contenu gratuit → produit front-end (97€) → produit phare (997-4997€) → coaching premium.
Marketing Underground	Programme phare de Tugan Bara (2018-2023). Posture « bad guy » assumée.
Tugan Bara / Arnaud Labossière	Archétype français du modèle infopreneur 2018-2024. HEC dropout. Vendu Tugan.ai en 2024. Finalement le seul infopreneur qui a vraiment expliqué la profession à toute une communauté de la scène francophone.
MRR	Monthly Recurring Revenue. Somme mensuelle facturée aux clients sous abonnement. Indicateur SaaS central.
ARR	Annual Recurring Revenue. Somme annuelle récoltée par la vente d’un SaaS.

IA, ML, RL#

Terme	Définition
LLM	Large Language Model. Modèle Transformer pré-entraîné sur un large corpus. Claude, GPT, Gemini, Llama, Mistral.
Transformer	Architecture introduite par Attention Is All You Need.
Foundation model	Modèle pré-entraîné réutilisé pour de multiples tâches via fine-tuning ou prompting.
RL (Reinforcement Learning)	Apprentissage par interaction avec un environnement, guidée par un signal de reward. Sutton & Barto 1998.
Constitutional AI (CAI)	Méthode d’alignement Anthropic (Bai et al., 2022). Le modèle critique et révise ses propres réponses selon une constitution écrite.
Probe	Primitive d’apprentissage empirique pour l’IA.
llms.txt, llms-full.txt	Standard Jeremy Howard (fast.ai), 2024. Index Markdown court (`llms.txt`) + doc full concaténée (`llms-full.txt`) pour ingestion par agent.
SKILL.md	Permet à un agent IA de plugger une compétence projet.
CLAUDE.md	Donne ensemble de règles à Claude Code.

00.02 — Matrice stack / responsabilité / licence

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

00.02 — Matrice stack / responsabilité / licence#

Dépôt	Rôle	Langage	Version	Stack principale	Stack outillage	Distribution	Licence
`ocarina`	Framework de test e2e navigateur	Python	3.14+	`hatchling`, `python-docx` (seule dépendance d’exécution), `selenium` + `playwright` (dev seulement)	`ruff` (ALL), `mypy` strict, `pytest`, `hypothesis`, `pytest-mypy-plugins`, `syrupy`, `prysk` (cram), `allure-pytest`, `pre-commit`, `twine`, `build`	PyPI, v1.1.10	MIT
`ocarina-example`	Suite canonique e2e contre l’Igoristan	Python	3.14+	`ocarina`, `selenium ≥ 4.40`, `python-dotenv`, `dogpile.cache`, `redis`	`ruff`, `mypy`, `pre-commit`	Source uniquement	MIT
`ocarina-with-ai-example`	Suite e2e CURA Healthcare co-écrite par Claude Code	Python	3.14+	`ocarina ≥ 1.0.3`, `selenium ≥ 4.40`	`ruff`, `mypy`, `mypy-extensions`, `typing-extensions`, `pre-commit`	Source uniquement	MIT
`igoristan`	SUT public, application web volontairement chaotique	TypeScript	6.0.x	React 19.2, Vike 0.4.258 (SSG), Vite 7.3, TailwindCSS 4 (alpha), `valibot`, `react-hook-form`, `react-dropzone`, `usehooks-ts`, `throttleit`, `lucide-react`, `uuid`	`pnpm 11`, Node 24, `wireit` (orchestrateur), `eslint 9` (flat), `prettier 3.5`, `husky`, `lint-staged`, `commitlint`, `commitizen`, `terser`, `rollup-plugin-visualizer`, `vite-plugin-compression`, `@qalisa/vike-plugin-sitemap`	GitHub Pages (`/igoristan/`)	aucune
`tests-workers`	Backend OTP / Corsicadex pour exercer la parallélisation et les tests avec appels API	TypeScript	5.9.3	Vercel Edge Functions (`runtime: "edge"`), `@upstash/redis`, `otplib`, types `next` (`NextRequest`)	`pnpm 11.x`, `@vercel/node` (types)	Vercel : `https://tests-workers.vercel.app`	ISC
`ocarina-holy-book`	Documentation publique + skills IA + PDF	TypeScript	6.0.x	VitePress 2 alpha, theme `@sugarat/theme`, `vue 3.5`, `pagefind`, `vitepress-plugin-image-optimize`	`pnpm 11`, Node 24, `eslint 9`, `prettier 3.8`, `husky`, `lint-staged`, `commitlint`, `sass-embedded`	GitHub Pages (`/ocarina-holy-book/`)	MIT

Python early adopter#

Apport Python 3.12+	Utilisation dans Ocarina
PEP 695 (`class Foo[T]:`)	Signature générique partout (`TestSuite[Driver]`, `Watcher[Driver]`, `Test[Driver]`, `Result[T]`, `Ok[T]`, `Thunk[T]`, etc.)
PEP 695 type aliases (`type X = ...`)	Tous les alias : `type Result[T] = Ok[T] \| Fail`, `type Effect = Callable[[], None]`, `type Thunk[T] = Callable[[], T]`, `type Mode = Literal[...]`
`TypeGuard` (Python 3.10+)	`is_ok`, `is_fail`, `is_test_result_ok`, `is_test_result_fail`, `is_test_result_skipped`
`Self` (3.11+)	Retours fluides des POMs, des loggers, des invariants
`@final` (3.8+)	Verrouille les classes critiques (`Watcher`, `Test`, `TestCycle`, `ChainRunner`, `Ok`, `Fail`, …)
`Unpack` (3.11+)	Signature de `HumanizedDriver` côté `ocarina-example`
`Protocol` (3.8+)	`ScreenshotDriver`, `SupportsWrite[str]`
`Literal` (3.8+)	Toutes les énumérations (`SeleniumCliStoreKeys`, `LOGGERS_CHOICES`, `Mode`)
`Never` (3.11+)	Signature de `_SilentArgumentParser.error`

Conséquence pratique : il existe un workflow CI dédié unstable_python_full_build.yml qui pousse Python 3.15-dev mensuellement (cron: "0 3 1 * *"), parce qu’Ocarina veut être prêt pour le prochain interpréteur dès qu’il sort. Voir ../10-cicd/02-ocarina-workflows.md

01.02 — ISTQB vs pytest / Jest / Mocha

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

01.02 — ISTQB vs pytest / Jest / Mocha#

Le constat méthodologique#

Au-delà du pari technique sur la barrière techniques / non-techniques (voir 01-flip-the-problem.md), il y a un second pari : celui du vocabulaire métier.

L’ISTQB et les testeurs professionnels ont construit, depuis des décennies, un vocabulaire précis et éprouvé : cycles de test, campagnes, suites de test, cas de test, pas de test. Une hiérarchie claire, pensée pour organiser, tracer et piloter la qualité logicielle.

02.02 — Arborescence du module ocarina

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

02.02 — Arborescence du module `ocarina`#

Le module Python source contient 134 fichiers .py répartis en quatre couches conceptuelles.

src/ocarina/
├── __init__.py                              # vide — pas de "facade" globale, on importe précisément
├── py.typed                                 # PEP 561 : déclare le package comme "typed"
│
├── railway/                                 # Couche 1 — primitives FP
│   ├── __init__.py
│   └── result.py                            # Ok[T] / Fail / Result[T] / is_ok / is_fail
│
├── custom_types/                            # Couche 2 — types et alias
│   ├── __init__.py
│   ├── effect.py                            # type Effect = Callable[[], None]
│   ├── thunk.py                             # type Thunk[T] = Callable[[], T]
│   ├── tpom.py                              # TypeVar TPOM bound POMBase
│   ├── supports_write.py                    # Protocol SupportsWrite[T], reflète type non exposé par lib standard Python
│   ├── built_web_driver.py                  # type BuiltWebDriver[Driver] = tuple[Driver, Effect]
│   ├── scenario.py                          # Scenario[Driver] (frozen dataclass)
│   ├── test_components.py                   # TestChain / TestSetup / TestTeardown / TestWatchers
│   ├── test_runner.py                       # TestRunner[Driver]
│   ├── oc_test.py                           # TestName / TestScenario / TestScenarioFragment
│   ├── oc_test_layers.py                    # TestResult / TestSuiteResult / TestCampaignResults / TestCycleResults
│   ├── selenium/
│   │   ├── built_web_driver.py              # BuiltSeleniumWebDriver
│   │   ├── oc_test_scenario.py
│   │   ├── supported_browsers.py            # type SupportedSeleniumBrowser = Literal["chrome", "firefox", "edge", "safari"]
│   │   └── web_drivers_pool.py              # type SeleniumWebDriversPool = WebDriversPool[WebDriver]
│   └── playwright/
│       ├── built_web_driver.py              # type BuiltPlaywrightDriver = BuiltWebDriver[PlaywrightDriver]
│       ├── oc_test_scenario.py              # PlaywrightTestScenario / PlaywrightTestScenarioFragment
│       ├── supported_browsers.py            # type SupportedPlaywrightBrowser = Literal["chromium", "firefox", "webkit"]
│       └── web_drivers_pool.py              # type PlaywrightDriversPool = WebDriversPool[PlaywrightDriver]
│
├── custom_errors/                           # Couche 2 : erreurs
│   ├── __init__.py
│   └── test_framework/
│       ├── __init__.py
│       ├── no_matching_branch.py            # NoMatchingBranchError
│       ├── pages.py                         # PageVerificationError
│       ├── driver_died.py                   # DriverDiedError
│       └── campaigns.py
│
├── custom_invariants/                       # Couche 2 : invariants prêts-à-l'emploi
│   ├── __init__.py
│   └── testing/
│       ├── __init__.py
│       ├── workers.py                       # validate_workers_amount
│       ├── oc_test_runners_ids.py           # validate_test_runners_ids
│       ├── oc_test_runners_names.py         # validate_test_runners_names (unique + valid filename)
│       ├── oc_test_suites_names.py
│       ├── oc_test_campaigns_names.py
│       └── oc_test_cycles_names.py
│
├── ports/                                   # Couche 3 : ports (interfaces)
│   ├── __init__.py
│   ├── ilogger.py                           # ILogger (ABC)
│   └── itake_screenshot.py                  # ITakeScreenshot[Driver] (Protocol)
│
├── pom/                                     # Couche 3 : Page Object Model
│   ├── __init__.py
│   ├── base.py                              # POMBase (ABC : verify + get_current_title)
│   ├── selenium/
│   │   ├── __init__.py
│   │   └── muted.py                         # MutedPOM utilitaire
│   └── playwright/
│       ├── __init__.py
│       └── muted.py                         # MutedPlaywrightPOM utilitaire
│
├── aggregates/                              # Couche 3 : agrégats de résultats
│   ├── __init__.py
│   └── tests_layers.py                      # is_test_result_ok / _fail / _skipped (TypeGuard)
│
├── dsl/                                     # Couche 4 : DSL Ocarina
│   ├── __init__.py
│   ├── invariants/
│   │   ├── __init__.py
│   │   ├── validate.py                      # entry-point validate(), BusinessInvariantValidator, FrameworkInvariantValidator
│   │   ├── assertions.py                    # is_str / is_email / is_positive / is_in / has_unique_elements / each / ...
│   │   ├── errors.py                        # InvariantViolationError / DuplicatesError / AggregateInvariantViolationError
│   │   └── internals/
│   │       ├── __init__.py
│   │       └── validation_chain.py          # ValidationStartBlock / ValidationAssertBlock / _ValidationChain / _any_of / chain_validations
│   ├── testing/
│   │   ├── __init__.py
│   │   ├── oc_test.py                       # class Test[Driver]
│   │   ├── oc_test_suite.py                 # class TestSuite[Driver]
│   │   ├── oc_test_campaign.py              # class TestCampaign[Driver] + campaign_has_failed
│   │   ├── oc_test_cycle.py                 # class TestCycle[Driver] + type Mode + has_test_cycle_failed
│   │   ├── filter_tests_by_ids.py
│   │   ├── watcher.py                       # class Watcher[Driver]
│   │   ├── internals/
│   │   │   ├── __init__.py
│   │   │   ├── test_executor.py             # class TestExecutor[Driver] + ExecutionOutcome (frozen, slots)
│   │   │   └── test_flow.py                 # class TestFlow[Driver]
│   │   ├── selenium/
│   │   │   ├── __init__.py
│   │   │   ├── create_test.py               # create_selenium_test(...)
│   │   │   └── create_watcher.py            # create_selenium_watcher(...) + type SeleniumWatcher
│   │   └── playwright/
│   │       ├── __init__.py
│   │       ├── create_test.py               # create_playwright_test(...)
│   │       └── create_watcher.py            # create_playwright_watcher(...) + type PlaywrightWatcher
│   └── testing_with_railway/
│       ├── __init__.py
│       ├── chain_actions.py                 # class ChainRunner[T] + chain_actions
│       ├── match_page.py                    # When + _match_page_builder + create_match_page
│       ├── constructors/
│       │   ├── __init__.py
│       │   └── create_act.py                # primitive de bas niveau (à wrapper côté projet)
│       └── internals/
│           ├── __init__.py
│           └── action_chain.py              # ActionStart → ActionFailure → ActionSuccess → ActionChain
│                                            # + Neutral{Start,Failure,Success}  (rail d'échec)
│
├── infra/                                   # Couche 5 : infrastructure
│   ├── __init__.py
│   ├── drivers_pool.py                      # class WebDriversPool[Driver] + WarmupTimeoutError
│   ├── driver_builder.py                    # class DriverBuilder[Driver]
│   ├── screenshotter.py                     # class Screenshotter[TDriver] + ScreenshotterConfig
│   ├── act_counter.py                       # class ActCounter (interface)
│   ├── selenium/
│   │   ├── __init__.py
│   │   ├── create_driver.py                 # _build_firefox / _build_chrome / _build_edge / _build_safari
│   │   ├── create_drivers_pool.py           # create_selenium_drivers_pool
│   │   ├── create_screenshotter.py          # create_selenium_screenshotter
│   │   ├── driver_healthcheck.py            # driver_healthcheck (ping driver.title)
│   │   └── mixins.py                        # SeleniumTitleMixin (détrompeur de typage)
│   └── playwright/
│       ├── __init__.py
│       ├── create_driver.py                 # create_playwright_driver (chromium / firefox / webkit)
│       ├── create_drivers_pool.py           # create_playwright_drivers_pool
│       ├── create_screenshotter.py          # create_playwright_screenshotter + _playwright_save_full_page
│       ├── driver.py                        # class PlaywrightDriver (wrapper sync)
│       ├── driver_healthcheck.py            # playwright_driver_healthcheck (ping driver.title)
│       └── mixins.py                        # PlaywrightTitleMixin (détrompeur de typage)
│
└── opinionated/                             # Couche 6 : opt-in, tout ce qui est "joli mais remplaçable"
    ├── __init__.py
    ├── consts/loggers_choices.py            # LOGGERS_CHOICES = ("terminal", "file", "terminal+file", "muted")
    ├── infra/
    │   ├── __init__.py
    │   └── act_counter.py                   # ThreadsBasedActCounter (compteur thread-local)
    ├── cli/
    │   ├── __init__.py
    │   ├── builder.py                       # CliBuilder + CliArg + _SilentArgumentParser
    │   ├── store.py                         # CliStore[TKeys] + _CliField[T] + field(...)
    │   ├── phantoms.py                      # phantom_validate (no-op predicate)
    │   ├── selenium/
    │   │   ├── __init__.py
    │   │   ├── cli_store_singleton.py       # SeleniumCliStoreSingleton (push / get)
    │   │   └── create_cli_store.py          # create_selenium_{auto,win,macos,linux}_cli_store
    │   └── playwright/
    │       ├── __init__.py
    │       ├── cli_store_singleton.py       # PlaywrightCliStoreSingleton (push / get)
    │       └── create_cli_store.py          # create_playwright_{,auto_}cli_store
    ├── dsl/
    │   ├── __init__.py
    │   └── drive_page.py                    # drive_page = chain_actions, alias sémantique
    ├── launcher/
    │   ├── __init__.py
    │   └── bootstrap.py                     # bootstrap(...) + run_plugins(*plugins, exceptions_logger)
    ├── loggers/
    │   ├── __init__.py
    │   ├── create_matching_logger.py        # create_matching_logger("terminal"|"file"|...) + get_default_log_dir
    │   ├── print_logger.py                  # PrintLogger (ANSI)
    │   ├── file_logger.py                   # FileLogger (taxonomie -> arbre de fichiers)
    │   ├── print_and_file_logger.py
    │   ├── muted_logger.py
    │   ├── custom_types/supported_loggers.py
    │   └── utils/
    │       ├── __init__.py
    │       └── format_metadata_str.py       # format_utc_date_metadata_str / format_current_thread_metadata_str / concat_metadata
    └── plugins/
        ├── __init__.py
        └── reports/
            ├── __init__.py
            ├── pretty_print_results.py      # rapport ANSI hiérarchique
            ├── results_to_json.py           # générateur JSON
            ├── docx_tests_proofs.py         # générateur DOCX (consomme l'arbre de logs)
            └── timing.py                    # context manager `with timing(prefix="Duration:")`

Schéma en couches#

┌──────────────────────────────────────────────────────────────────────────┐
│ USER PROJECT (e.g. ocarina-example, ocarina-with-ai-example)             │
│  ┌────────────────────┐  ┌────────────────────┐  ┌─────────────────────┐ │
│  │ pages/ (POMBase)   │  │ scenarios/ (Test)  │  │ adapters/ (act, ...)│ │
│  └────────────────────┘  └────────────────────┘  └─────────────────────┘ │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │ imports
┌─────────────────────────────────▼────────────────────────────────────────┐
│ COUCHE 6 — opinionated/  (CLI, loggers, plugins, bootstrap)              │
│   opt-in. Peut être remplacée intégralement.                             │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ COUCHE 5 — infra/  (pool, builder, screenshotter, adapters Selenium)     │
│   I/O. Pas de logique DSL.                                               │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ COUCHE 4 — dsl/  (testing, invariants, testing_with_railway)             │
│   DSL pur, sans I/O. Toute la grammaire.                                 │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ COUCHE 3 — ports/  +  pom/  +  aggregates/                               │
│   Interfaces et abstractions.                                            │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ COUCHE 2 — custom_types/  +  custom_errors/  +  custom_invariants/       │
│   Shapes, alias, types, exceptions, invariants prêts-à-l'emploi.       │
└─────────────────────────────────┬────────────────────────────────────────┘
                                  │
┌─────────────────────────────────▼────────────────────────────────────────┐
│ COUCHE 1 — railway/  (Result, Ok, Fail, is_ok, is_fail)                  │
│   La primitive fonctionnelle. Aucune dépendance.                         │
└──────────────────────────────────────────────────────────────────────────┘

Cette stratification stricte garantit l’absence de cycles d’import et permet de remplacer chaque couche supérieure sans toucher aux couches inférieures :

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

03.02 — Closures comme primitive d'inversion de contrôle

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

03.02 — Closures comme primitive d’inversion de contrôle#

Pas de DI container. Pas de framework d’injection. Une closure est la primitive d’injection d’Ocarina.

L’idée#

Une closure capture des valeurs dans son scope englobant. Quand on retourne une fonction depuis une autre fonction, les paramètres de l’extérieur sont disponibles à l’intérieur, même après que la fonction extérieure ait rendu la main.

def make_handler(logger: ILogger) -> Callable[[str], FailureHandler]:
    def make_failure_handler(msg: str) -> FailureHandler:
        def actual_handler(exc: Exception) -> None:
            logger.error(msg, exc=exc)
        return actual_handler
    return make_failure_handler

C’est aussi du currying : make_handler(logger)(msg)(exc). Chaque appel capture une nouvelle couche d’environnement.

04.02 — Cram tests (prysk)

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

04.02 — Cram tests (`prysk`)#

Tests CLI au format cram : un fichier .t contient des commandes shell et leur sortie attendue. Outil utilisé : prysk (réécriture moderne de cram).

Fichier `.t`#

Valid args produce a deterministic parsed config

  $ touch driver
  $ "$PYTHON" "$TESTDIR/_demo_cli.py" --browser firefox --driver-path driver --workers 3 --wait-timeout 20 --logger terminal
  browser=firefox
  driver_path=driver
  headless=True
  workers=3
  wait_timeout=20
  logger=terminal
  only=()
  exclude=()

Première ligne : titre (commentaire pour l’humain).
Ligne vide.
Lignes commençant par $ : commande shell exécutée.
Lignes suivantes (indent 2) : sortie attendue.

Si la sortie réelle diffère : le test fail.

05.02 — Les routes de l'Igoristan

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

05.02 — Les routes de l’Igoristan#

`src/config/routes.ts`#

const __ROOT = "/igoristan/";
const DASHBOARD = "dashboard";

const __ROUTES = {
  DONKEY_SAUSAGE_DETECTOR: "donkey-sausage-eater-detector",
  DASHBOARD_NESTED: `${DASHBOARD}/nested`,
  RANDOM_LOADERS: "random-loaders",
  SACRED_UPLOAD: "sacred-upload",
  RANDOM_ERROR: "random-error",
  CHAOTIC_FORM: "chaotic-form",
  CORSICAMON: "corsicamon",
  MADNESS: "madness",
  DASHBOARD,
  HOME: "",
} as const satisfies Routes;

const ROUTES = createRoutes(__ROUTES, __ROOT);

Route	URL	Rôle	Chaos volontaire
`HOME`	`/igoristan/`	Page d’accueil avec liens vers les autres pages, autoplay audio	—
`RANDOM_LOADERS`	`/igoristan/random-loaders`	Loaders pseudo-aléatoires	Loaders qui restent affichés un temps variable
`SACRED_UPLOAD`	`/igoristan/sacred-upload`	Formulaire d’upload `react-dropzone`	—
`DASHBOARD`	`/igoristan/dashboard`	Login (mot de passe `figatellu`), MFA OTP optionnel	`useAuth` peut échouer 10% du temps même avec le bon mdp
`DASHBOARD_NESTED`	`/igoristan/dashboard/nested`	Page protégée, requiert MFA	—
`CORSICAMON`	`/igoristan/corsicamon`	« Pokédex corse », 3 picks aléatoires via API key	1/5 chance de lever `Error('lol')` artificiellement
`RANDOM_ERROR`	`/igoristan/random-error`	Page d’erreur factice	Titre matché par `ERROR_PAGE_REGEX` côté tests
`CHAOTIC_FORM`	`/igoristan/chaotic-form`	Formulaire instable	Éléments `.catch-me-if-you-can` apparaissent aléatoirement
`MADNESS`	`/igoristan/madness`	Histoires alternées (Cors, ThisIsBastia)	Rend l’une OU l’autre au hasard
`DONKEY_SAUSAGE_DETECTOR`	`/igoristan/donkey-sausage-eater-detector`	Détecteur de sales siciliens de merde	30% d’échec aléatoire (BSOD-style)

Page par page#

const links = [
  { href: ROUTES.RANDOM_LOADERS, label: "Random loaders" },
  { href: ROUTES.SACRED_UPLOAD, label: "Sacred upload" },
  { href: ROUTES.DASHBOARD, label: "Dashboard" },
  { href: ROUTES.CORSICAMON, label: "Corsicamon" },
  { href: ROUTES.RANDOM_ERROR, label: "Random Error" },
  { href: ROUTES.CHAOTIC_FORM, label: "Chaotic form" },
  { href: ROUTES.MADNESS, label: "Madness" },
  { href: ROUTES.DONKEY_SAUSAGE_DETECTOR, label: "Donkey Sausage Detector" },
];

home#

8 liens vers les autres pages + autoplay audio Angelus de Jérusalem (amen 🙏).

06.02 — GET /api/otp

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

06.02 — `GET /api/otp`#

Fichier source : api/otp.ts

Code#

import { generate } from "otplib";
import type { NextRequest } from "next/server";
import redis from "../lib/redis";
import isAuthorized from "../lib/isAuthorized";

export const config = { runtime: "edge" };

const SECRET_QUERY_PARAM_KEY = "secret";
const OTP_SECRET_MIN_LENGTH = 32;
const OTP_SECRET_MAX_LENGTH = 64;
const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
const OTP_TTL = 60 * 5; // 5 minutes
const OTP_HISTORY_TTL = OTP_TTL + 60; // 6 minutes
const MAX_FREE_PAYLOAD_SIZE = 4096;

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "x-api-key, Content-Type",
} as const;

function generateRandomBase32Secret(length: number = 32): string {
  let secret = "";
  const randomValues = new Uint8Array(length);
  crypto.getRandomValues(randomValues);
  for (let i = 0; i < length; i++) {
    secret += BASE32_ALPHABET[randomValues[i] % 32];
  }
  return secret;
}

function ensureSecretLength(secret: string): string {
  const cleaned = secret.toUpperCase().replace(/\s/g, "");
  if (cleaned.length > OTP_SECRET_MAX_LENGTH) {
    const validLength = Math.floor(OTP_SECRET_MAX_LENGTH / 8) * 8;
    return cleaned.substring(0, validLength);
  }
  if (cleaned.length >= OTP_SECRET_MIN_LENGTH) {
    const validLength = Math.floor(cleaned.length / 8) * 8;
    return cleaned.substring(0, validLength);
  }
  const repetitions = Math.ceil(OTP_SECRET_MIN_LENGTH / cleaned.length);
  const repeated = cleaned.repeat(repetitions);
  const validLength = Math.floor(repeated.length / 8) * 8;
  return repeated.substring(0, Math.max(validLength, OTP_SECRET_MIN_LENGTH));
}

export default async function handler(request: NextRequest) {
  if (request.method === "OPTIONS") {
    return new Response(null, { status: 200, headers: corsHeaders });
  }

  if (!isAuthorized(request)) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  const { searchParams } = new URL(request.url);
  const freePayload: Record<string, string> = {};
  let payloadSize = 0;

  searchParams.forEach((value, key) => {
    if (key === SECRET_QUERY_PARAM_KEY) return;
    const entrySize = new TextEncoder().encode(key + value).length;
    if (payloadSize + entrySize > MAX_FREE_PAYLOAD_SIZE) {
      payloadSize += entrySize;
      return;
    }
    freePayload[key] = value;
    payloadSize += entrySize;
  });

  if (payloadSize > MAX_FREE_PAYLOAD_SIZE) {
    return new Response(
      JSON.stringify({
        error: "Bad Request",
        message: `Free payload exceeds maximum size of ${MAX_FREE_PAYLOAD_SIZE} bytes (got ${payloadSize} bytes)`,
      }),
      {
        status: 400,
        headers: { "Content-Type": "application/json", ...corsHeaders },
      },
    );
  }

  const rawSecret =
    searchParams.get(SECRET_QUERY_PARAM_KEY) ?? generateRandomBase32Secret();
  const secret = ensureSecretLength(rawSecret);
  const otpCode = await generate({ secret });
  const now = Date.now();
  const expiresAtMs = now + OTP_TTL * 1000;
  const createdAtTimestampLackingMsPrecision = new Date(
    now - (now % 1000),
  ).toISOString();

  const event = {
    ...freePayload,
    otpCode,
    secret,
    createdAtTimestampLackingMsPrecision,
    expiresAt: new Date(expiresAtMs).toISOString(),
  };

  const key = `otp:${now}:${crypto.randomUUID()}`;
  await redis.set(key, JSON.stringify(event), { ex: OTP_HISTORY_TTL });

  return new Response(JSON.stringify(event), {
    headers: { "Content-Type": "application/json", ...corsHeaders },
  });
}

Flot#

1. Request arrive
   ↓
2. Si OPTIONS → 200 + CORS headers (preflight)
   ↓
3. isAuthorized(request) ? Non → 401
   ↓
4. Parse searchParams ; tout sauf "secret" est mis dans freePayload
   ↓
5. payloadSize > 4 KB ? → 400
   ↓
6. secret = ?secret=<X> (si fourni) sinon random Base32 32-chars
   ↓
7. ensureSecretLength : assure 32..64 chars, multiple de 8
   ↓
8. otpCode = generate({ secret })   ← otplib TOTP RFC 6238
   ↓
9. createdAt = floor(now / 1000) * 1000  ← amputation des ms
   ↓
10. event = { ...freePayload, otpCode, secret, createdAt, expiresAt }
    ↓
11. key = `otp:<now>:<uuid>`
    ↓
12. redis.set(key, JSON.stringify(event), { ex: 360 })  ← TTL 6 min
    ↓
13. Response = JSON.stringify(event), 200

CORS headers#

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "x-api-key, Content-Type",
} as const;

* origin : permet à l’Igoristan (depuis https://mojo-molotov.github.io) d’appeler le service.
GET, OPTIONS : seuls verbes supportés.
Custom header x-api-key autorisé (sinon le browser bloquerait).

as const rend l’objet readonly côté TypeScript.

07.02 — Les 5 adapters

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

07.02 — Les 5 adapters#

Tout projet Ocarina commence par écrire cinq adapters au-dessus du framework.
Le projet ocarina-example les fournit en référence.

Listing#

Adapter	Statut	Fichier	But
`act`	requis	`lib/ext/ocarina/adapters/agnostic/act.py`	Hook `on_failure` spécifique au projet
`match_page`	facultatif	`lib/ext/ocarina/adapters/agnostic/match_page.py`	Politique d’exceptions partagée
`EnvGetters`	facultatif	`lib/ext/ocarina/adapters/agnostic/env_getters.py`	Accès typé aux env vars
`TestSuite`	requis	`lib/ext/ocarina/adapters/selenium/test_suite.py`	Façade : fige `transient_errors`, `max_retries`, `autoscreen`
`TestCampaign`	requis	`lib/ext/ocarina/adapters/selenium/test_campaign.py`	Façade : `max_workers` depuis CLI

`act`#

# lib/ext/ocarina/adapters/agnostic/act.py
from contextlib import suppress
from ocarina.dsl.testing_with_railway.constructors.create_act import create_act
from ocarina.railway.result import Fail
from lib.custom_errors.http import HttpErrorPageReachedError
from lib.ext.ocarina.regex.error_page import ERROR_PAGE_REGEX


def act(pom: TPOM, action: Callable[[TPOM], TPOM]) -> ActionStart[TPOM]:
    def failure_hook(pom: TPOM, exc: Exception) -> Fail:
        with suppress(Exception):
            title = pom.get_current_title()
            is_http_error_page = title and ERROR_PAGE_REGEX.match(title.strip())
            if is_http_error_page:
                http_error = HttpErrorPageReachedError(f"HTTP error page: {title}")
                http_error.__cause__ = exc
                return Fail(error=http_error)
        return Fail(error=exc)

    return create_act(pom, action, on_failure=failure_hook)

get_current_title() : utilise la méthode obligatoire de POMBase (cf. ../02-ocarina/08-pom-base.md).
ERROR_PAGE_REGEX : regex projet qui détecte un titre type page d’erreur HTTP (par exemple ^\d{3}\s.* pour 500 Internal Server Error).
HttpErrorPageReachedError : exception projet ; sous-classe d’Exception, sera dans transient_errors.

C’est cet adapter qui rend le rejeu automatique pour les pages d’erreur.

08.02 — CURA Healthcare (SUT)

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

08.02 — CURA Healthcare (SUT)#

La première victime d’Ocarina#

Hébergement : https://katalon-demo-cura.herokuapp.com/
Source : https://github.com/katalon-studio/katalon-demo-cura (PHP, open source, MIT)
Hébergeur : Heroku eco-dyno (qui s’endort après inactivité)
Credentials : John Doe / ThisIsNotAPassword (publics, hardcodés sur la page login)

Périmètre#

Page	Fonction
`/`	Marketing homepage
`/profile.php#login`	Login
`/appointment.php`	Form de booking (facility, programs, hospital_readmission, visit_date, comment)
`/confirmation.php`	Confirmation du booking
`/history.php`	Historique des bookings du user
`/profile.php#profile`	Page Profil (placeholder vide — gap §G-SPEC-2)

Pourquoi cibler CURA#

Open source. On peut lire le PHP pour comprendre pourquoi tel comportement.
Beaucoup de gaps. Riche terrain de findings.
Public, démo. Pas d’autorisation à demander. Stable (maintenu par Katalon).

Plus une raison tacite : Katalon est un éditeur de framework de test concurrent (Katalon Studio).
C’est joliment poétique de tester leur app démo avec Ocarina.

09.02 — I18n FR/EN/RU

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

09.02 — I18n FR/EN/RU#

Toutes les pages du Holy Book existent en trois versions. EN à la racine de docs/, FR sous docs/fr/, RU sous docs/ru/. VitePress route automatiquement.

Structure des fichiers#

docs/
├── index.md                                                        # EN home
├── what-is-it.md
├── first-feedbacks.md
├── setup.md
├── scenarios-composability.md
├── datasets-smoke-tests-setup-teardown-proxy-api-and-caching.md
├── handling-flakiness.md
├── extensibility.md
├── using-ocarina-with-ai.md
│
├── fr/
│   ├── index.md                                                    # FR home
│   ├── what-is-it.md
│   ├── first-feedbacks.md
│   ├── setup.md
│   ├── scenarios-composability.md
│   ├── datasets-smoke-tests-setup-teardown-proxy-api-and-caching.md
│   ├── handling-flakiness.md
│   ├── extensibility.md
│   └── using-ocarina-with-ai.md
│
├── ru/
│   ├── index.md                                                    # RU home
│   ├── what-is-it.md
│   ├── first-feedbacks.md
│   ├── setup.md
│   ├── scenarios-composability.md
│   ├── datasets-smoke-tests-setup-teardown-proxy-api-and-caching.md
│   ├── handling-flakiness.md
│   ├── extensibility.md
│   └── using-ocarina-with-ai.md
│
├── public/
│   ├── favicon.ico
│   ├── logo.png
│   ├── robots.txt
│   ├── .nojekyll
│   ├── .spa
│   └── assets/
│       └── content/
│           └── ...                                                 # images partagées EN+FR+RU
│
└── .vitepress/
    ├── config.mts
    ├── blog-theme.ts
    ├── shims.d.ts
    ├── plugins/
    │   ├── llm.ts
    │   ├── pub.ts
    │   ├── skills.ts
    │   └── webp.ts
    └── theme/
        ├── index.ts
        ├── style.css
        ├── user-theme.css
        ├── components/
        │   ├── Pagination.vue
        │   ├── BlogHomeBanner.vue
        │   └── NotFound.vue
        └── assets/
            └── bg.png

Routing#

Page	URL EN	URL FR	URL RU
Page d’accueil	`/`	`/fr/`	`/ru/`
Pitch	`/what-is-it`	`/fr/what-is-it`	`/ru/what-is-it`
Coup de gueule	`/first-feedbacks`	`/fr/first-feedbacks`	`/ru/first-feedbacks`
Setup	`/setup`	`/fr/setup`	`/ru/setup`
…	…	…	…

VitePress crée automatiquement le switcher de langue (en haut à droite). Cliquer sur « FR » depuis /setup → /fr/setup.

09.03.02 — Skills Analyse

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

09.03.02 — Skills Analyse#

Analyses dynamiques : utilisent les logs / les rapports d’une exécution récente pour diagnostiquer un échec. Deux skills de diagnostic de cause racine ouvrent la famille — diagnose-root-cause pour un rouge déterministe, diagnose-flake-root-cause pour un échec intermittent — et aiguillent vers les expériences contrôlées analyse-*.

Listing (potentiellement non exhaustif)#

Skill	Cible
`diagnose-root-cause`	Analyse de cause racine d’un rouge déterministe : repart de zéro, remonte du synthétique vers le réel, cause triée en cinq familles
`diagnose-flake-root-cause`	Analyse de cause racine d’un échec intermittent (un flake) : taux d’échec, signature, corrélation ; orchestre les expériences `analyse-*`
`analyse-flakiness`	Élargit le filet des `transient_errors` ; les morts chroniques sont de vraies flakes
`analyse-fixture-flakiness`	Instrumente setup/teardown ; rend visibles les contaminations entre tests
`analyse-watcher-flakiness`	Analyse la fiabilité des watchers (volume, dedupe, faux positifs)
`analyse-screenshot-flakiness`	Regroupe les captures d’écran par `(test, étape, navigateur)`, détecte les différences

`diagnose-root-cause`#

input  : un rouge déterministe (échoue à chaque exécution)
output : analyse de cause racine structurée :
            - reprend l'analyse de zéro, sans réutiliser les hypothèses précédentes
            - remonte du synthétique vers le réel (faux driver → vrai navigateur)
            - lit la source, confirme avec une sonde
            - cause racine triée en cinq familles
         passe la main à diagnose-flake-root-cause si l'échec se révèle intermittent

`diagnose-flake-root-cause`#

input  : un échec intermittent (un flake)
output : analyse de cause racine fondée sur la distribution :
            - établit un taux d'échec (la distribution est la preuve)
            - fixe la signature, corrèle
            - aiguille vers la bonne expérience analyse-*, augmente le taux pour confirmer
            - classe en cinq familles de flakes
         l'orchestrateur de la famille analyse-*

`analyse-flakiness`#

input  : logs des N dernières exécutions
output : liste de tests qui retry souvent (par % de retries)
         + recommandation :
            - ajouter une exception au tuple transient_errors
            - investiguer un test particulier (peut-être que le problème vient directement du test)

`analyse-fixture-flakiness`#

input  : tests avec setup/teardown
output : tests dont le setup fail souvent
         + recommandation :
            - vérifier l'idempotence du setup
            - voir si teardown propre (sinon contamination entre tests)
            - sortir le seed du setup vers une init manuelle si trop fragile

`analyse-watcher-flakiness`#

input  : logs des watcher.report(...) sur N runs
output : watchers à reporting anormal :
            - trop d'émissions (problème de dedupe)
            - aucune émission (le watcher est inutile)
            - faux positifs (élément attendu reporté comme intrus)

`analyse-screenshot-flakiness`#

input  : screenshots de N runs, groupés par (test, step, browser)
output : flakiness visuelle :
            - tests dont les screenshots varient anormalement entre runs
            - tests qui passent mais dont l'aspect change
            - identifier si la variation est sémantique (vraie diff) ou cosmétique

Utilise des heuristiques (hash, dimensions, palette dominante). Pas une vraie image diff.

10.02 — Workflows ocarina (framework)

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

10.02 — Workflows `ocarina` (framework)#

Trois workflows : main_ci.yml (production), dev_ci.yml (branches dev/feature/fix), unstable_python_full_build.yml (cron mensuel sur Python 3.15-dev).

`main_ci.yml`#

Trigger#

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:
    inputs:
      python_versions:
        description: "Python versions to test"
        type: choice
        required: false
        default: "Stable only"
        options:
          - "Stable only"
          - "Stable + unstable (uses pre-built wheels)"

workflow_dispatch avec un choix de version Python. Permet à l’utilisateur de déclencher un build avec 3.15-dev (pre-built wheels only) sans attendre le cron mensuel.

11.02 — Auditabilité « en une après‑midi »

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

11.02 — Auditabilité « en une après‑midi »#

Engagement opérationnel : un humain doit pouvoir lire tout le framework et le comprendre en quelques heures. Pas de magie cachée.

Engagement#

Citation du Holy Book (chapitre « Qu’est donc Ocarina ? ») :

Pour les équipes bloquées par des politiques de sécurité : le code est petit, auditable en une après‑midi. Rien de caché. Les seules dépendances externes sont dans les plugins post‑exécution et si l’une d’elles ne passe pas, elle se retire sans que le reste ne casse.

12.02 — LulzSec, le Lulzboat, AntiSec

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

12.02 — LulzSec, le Lulzboat, AntiSec#

Trois sujets distincts : (1) LulzSec en tant que groupe, (2) le Lulzboat en tant que métaphore identitaire, (3) AntiSec en tant que mouvement (deux versions : 1999 et 2011). Le Holy Book les invoque d’un même souffle ; ils ont chacun leur histoire.

1. AntiSec (1999) — le mouvement originel#

Origine#

À la fin des années 1990, l’industrie de la sécurité informatique se professionnalise : des entreprises naissent autour de la vente de firewalls, d’antivirus, d’audits. Une norme émerge : la full disclosure, publier publiquement les vulnérabilités, leurs PoC, leurs exploits, avec comme argument que cela force les éditeurs à patcher rapidement.

99.02 — Index des fichiers cités

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

99.02 — Index des fichiers cités#

Par dépôt, les fichiers source explicitement cités dans le précis. URLs GitHub directs.

`mojo-molotov/ocarina` — Framework#

Racine#

`src/ocarina/railway/`#

result.py

`src/ocarina/custom_types/`#

`src/ocarina/custom_errors/test_framework/`#

`src/ocarina/custom_invariants/testing/`#

`src/ocarina/dsl/invariants/`#

`src/ocarina/dsl/testing/`#

`src/ocarina/dsl/testing_with_railway/`#

`src/ocarina/aggregates/`#

tests_layers.py

`src/ocarina/infra/`#

`src/ocarina/ports/`#

`src/ocarina/pom/`#

base.py

`src/ocarina/opinionated/`#

Tests#

tests/cram/cli_help.t
tests/cram/cli_happy_path.t
(autres .t)
tests/scenarios/conftest.py
tests/scenarios/test_railway_and_action_chain.py
(autres test_*.py)
tests/dsl/invariants/test_types.yml
tests/dsl/testing_with_railway/test_types.yml

Workflows#

`mojo-molotov/ocarina-example`#

Code#

Workflows#

`mojo-molotov/ocarina-with-ai-example`#

Docs#

Code#

Workflows#

`mojo-molotov/igoristan`#

Code#

Workflows#

`mojo-molotov/tests-workers`#

Code#

(Pas de workflow GitHub Actions.)

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

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

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

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

USER  ────────────────────────────────────────────────────────────────────
       python -u src/main.py --browser firefox --workers 3 [...]
              │
              ▼
       (1) parse CLI
           CliStoreSingleton.push(create_selenium_auto_cli_store())
              │
              ▼
       (2) build pool
           create_selenium_drivers_pool(max_size=N)
              │
              ▼
       (3) warm-up dépendances externes
           - Redis (ocarina-example)
           - Heroku dyno (ai-example, via curl --retry 6)
              │
              ▼
       (4) bootstrap(
              test_cycle  = create_e2e_test_cycle(drivers_pool),
              run_plugins = lambda results: run_plugins(
                                generate_docx_proof, generate_json_results,
                                exceptions_logger=...),
              post_exec   = pretty_print_results + sys.exit(1) si fail
           )
              │
OCARINA  ─────┼──────────────────────────────────────────────────────────
              │
              ▼
       (5) TestCycle.run_all (saturate_workers=True)
              ├─ smoke_tests_campaigns      [mode : fail-fast | wait-for-all]
              │     └─ TestCampaign.run_all
              │           └─ TestSuite.run (max_workers, saturate_workers)
              │                 └─ ThreadPoolExecutor → TestFlow.run
              │                       └─ pool.acquire() → TestExecutor.execute
              │                             ├─ setup()                  (optionnel)
              │                             ├─ watchers.start()         (daemon threads)
              │                             ├─ chain_runners            (DSL Railway)
              │                             ├─ watchers.stop()
              │                             └─ teardown()               (toujours)
              ├─ campaigns (main)
              │  (skippées si un smoke a fail)
              │
SUT   ────────┼────────────────────────────────────────────────────────────
              │
              ▼
       Selenium WebDriver ⇄ navigateur réel
       parfois : OTP HTTP GET + Redis (côté ocarina-example)
              │
              ▼
       (6) run_plugins(results)
              ├─ generate_docx_proof  (lit l'arbre de logs, fabrique des .docx)
              ├─ generate_json_results (sérialise results en .json)
              ├─ d'autres si déclarés (parallélisés via ThreadPoolExecutor)
              │
              ▼
       (6') post_exec(results)
              ├─ pretty_print_results (ANSI, hiérarchique)
              └─ has_test_cycle_failed → sys.exit(1) le cas échéant

Détail des étapes#

(1) Parse CLI#

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

01.03 — KISS et complexité ostentatoire

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

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.

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.

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

04.03 — Tests scénarios (pytest + allure)

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

04.03 — Tests scénarios (pytest + allure)#

15 fichiers test_*.py du dossier tests/scenarios/ couvrent le DSL, l’orchestration et l’acteur Playwright. Tests dynamiques.

Listing#

tests/scenarios/
├── conftest.py                              # FakeDriver, RecordingPOM, make_*
├── test_railway_and_action_chain.py         # create_act, drive_page, Result, ChainRunner
├── test_match_page.py                       # match_page / when (premières / dernières branches, exceptions)
├── test_validate.py                         # validate, assert_that, otherwise, then, chain_validations
├── test_invariants_properties.py            # hypothesis (cf. 06-hypothesis-properties)
├── test_drivers_pool.py                     # WebDriversPool (acquire, warmup, shutdown, semaphore leaks)
├── test_screenshotter.py                    # Screenshotter (single shot, burst, healthcheck, threadsafety)
├── test_driver_builder.py                   # DriverBuilder (profile tmp dir, dispose)
├── test_watcher.py                          # Watcher (start, stop, callback errors swallowed, dedup cache)
├── test_playwright_driver_actor.py          # acteur PlaywrightDriver (sync_playwright mocké, sans navigateur)
├── test_playwright_adapter.py               # smoke navigateur réel (skip si pas de Chromium installé)
├── test_test_suite.py                       # TestSuite (parallel, saturation, only/exclude, transient_errors)
├── test_test_cycle_and_bootstrap.py         # TestCycle, mode fail-fast vs wait-for-all, bootstrap
├── test_loggers_and_reports.py              # PrintLogger, FileLogger, pretty_print, JSON
├── test_docx_tests_proofs.py                # generate_docx_proof (parse logs, insert images)
└── test_env.py                              # smoke test : versions, Python 3.14+

Exemple de test interne#

@allure.epic("Railway / action chain")
@allure.feature("Action chain")
@allure.tag("act", "handlers", "happy-path")
@allure.severity(allure.severity_level.CRITICAL)
@allure.label("layer", "unit")
@allure.title("A successful act reports success; the success handler fires once")
def test_success_act_fires_success_handler() -> None:
    pom = RecordingPOM()
    calls = {"success": 0, "failure": 0}

    chain = (
        create_act(pom, lambda p: p.step("click"))
        .failure(lambda _: calls.__setitem__("failure", calls["failure"] + 1))
        .success(lambda: calls.__setitem__("success", calls["success"] + 1))
        .execute()
    )

    assert chain.is_ok()
    assert pom.calls == ["click"]
    assert calls == {"success": 1, "failure": 0}

Assertion	Cible
`chain.is_ok()`	API publique
`pom.calls == ["click"]`	comportement observable du POM (recording)
`calls == {"success": 1, "failure": 0}`	bon handler appelé

Annotations Allure#

Catégorie	Valeurs typiques
`epic`	“Railway / action chain”, “Invariants”, “Orchestration”, “Watcher”, “Drivers pool”, “Reports”, “Match page”
`feature`	“Action chain”, “Validate”, “TestSuite”, “TestCycle”, “Bootstrap”, “Pretty print”, “JSON”, “DOCX proofs”
`tag`	“act”, “handlers”, “happy-path”, “error-handling”, “retry”, “transient”, “smoke”, “skip”, “saturation”, “parallel”
`severity`	CRITICAL > NORMAL > MINOR > TRIVIAL
`label("layer", ...)`	“unit”, “integration”

`test_test_suite.py`#

Tests passent en mode séquentiel (max_workers=1).
Tests passent en mode parallèle (max_workers=N).
Filtrage --only / --exclude.
Mutex --only + --exclude.
Saturation : tests clonés avec [COPY N].
Retries sur transient errors.
Setup failure → SKIPPED si tous les attempts ratent dès le setup.
Test skipped=True s’arrête directement.
Garde-fous (noms uniques, IDs uniques).
take_screenshot appelé sur fail si autoscreen_on_fail.
Comptage exact des tentatives sur max_retries (un test couvre le bord de la boucle).

`test_match_page.py`#

Cas	Assertion
Première branche matche → exécutée	`chain.is_ok()`, branches suivantes non évaluées
Deuxième branche matche → exécutée	id.
Aucune branche ne matche	`NoMatchingBranchError` dans le `Fail`
Branche matche, mais son `then` fail	`Fail` propagé
`condition` lève une `Exception` ordinaire	Traité comme `False`, branches suivantes essayées
`condition` lève une exception du tuple `raised_exceptions`	Re-raise
Branche `then=[]` matche	`Ok(None)`
`match_page` au milieu d’un `test_chain`	Court-circuite si fail

`test_drivers_pool.py`#

Note : utilisation d’un FakeDriverFactory qui peut être configuré pour lever / bloquer / dormir, et qui compte ses appels.

05.03 — Le faux useAuth + MFA OTP

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

05.03 — Le faux `useAuth` + MFA OTP#

Le hook useAuth de l’Igoristan est volontairement faux. Il introduit deux mécaniques pour exercer le rejeu et la coordination des workers d’Ocarina : un échec aléatoire de 10% et un MFA OTP optionnel.

Code#

// src/hooks/useAuth.ts
const VALID_PASSWORD = "figatellu";
const NOT_AUTHENTICATED = -1;
const AUTHENTICATED_WITHOUT_MFA = 1;
const AUTHENTICATED_WITH_MFA = 2;

// * ... This is FAKED
export const useAuth = () => {
  const [_isAuthenticated, setIsAuthenticated] = useLocalStorage(
    "isAuthenticated",
    NOT_AUTHENTICATED,
  );
  const [isLoading, setIsLoading] = useState(true);

  const isAuthenticated = useCallback(
    () => _isAuthenticated !== NOT_AUTHENTICATED,
    [_isAuthenticated],
  );
  const isAuthenticatedWithMFA = useCallback(
    () => _isAuthenticated === AUTHENTICATED_WITH_MFA,
    [_isAuthenticated],
  );
  const logout = useCallback(
    () => setIsAuthenticated(NOT_AUTHENTICATED),
    [setIsAuthenticated],
  );

  useEffect(() => {
    const delay = 500 * randint(1, 5); // ◄── délai aléatoire 0.5-2.5s
    const timer = setTimeout(() => setIsLoading(false), delay);
    return () => clearTimeout(timer);
  }, []);

  const login: LoginFn = ({ pre = false, password, withMFA }) => {
    if (password === VALID_PASSWORD && Math.random() < 0.9) {
      // ◄── 10% d'échec malgré bon mdp
      if (!pre) {
        setIsAuthenticated(
          withMFA ? AUTHENTICATED_WITH_MFA : AUTHENTICATED_WITHOUT_MFA,
        );
      }
      return true;
    }
    return false;
  };

  return { isAuthenticatedWithMFA, isAuthenticated, isLoading, logout, login };
};

Mécaniques#

1. `LocalStorage`#

const [_isAuthenticated, setIsAuthenticated] = useLocalStorage(
  "isAuthenticated",
  NOT_AUTHENTICATED,
);

Trois valeurs : -1 (pas authentifié), 1 (sans MFA), 2 (avec MFA).
Persistées dans localStorage, faciles d’accès pour du test/debug manuel.

06.03 — GET /api/otp-history

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

06.03 — `GET /api/otp-history`#

Fichier source : api/otp-history.ts

Code#

import type { NextRequest } from "next/server";
import redis from "../lib/redis";
import isAuthorized from "../lib/isAuthorized";

export const config = { runtime: "edge" };

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "x-api-key, Content-Type",
} as const;

export default async function handler(request: NextRequest) {
  if (request.method === "OPTIONS") {
    return new Response(null, { status: 200, headers: corsHeaders });
  }

  if (!isAuthorized(request)) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  let cursor = "0";
  const allEvents = [];
  const BATCH_SIZE = 100;

  do {
    const [newCursor, keys] = await redis.scan(cursor, {
      match: "otp:*",
      count: BATCH_SIZE,
    });
    cursor = newCursor;

    if (keys.length > 0) {
      const values = await redis.mget(...keys);
      allEvents.push(...values.filter(Boolean));
    }
  } while (cursor !== "0");

  return new Response(JSON.stringify(allEvents), {
    headers: { "Content-Type": "application/json", ...corsHeaders },
  });
}

Mécanique de `SCAN` Redis#

let cursor = "0";
const allEvents = [];
const BATCH_SIZE = 100;

do {
  const [newCursor, keys] = await redis.scan(cursor, {
    match: "otp:*",
    count: BATCH_SIZE,
  });
  cursor = newCursor;

  if (keys.length > 0) {
    const values = await redis.mget(...keys);
    allEvents.push(...values.filter(Boolean));
  }
} while (cursor !== "0");

cursor = "0" (initialisation).
Boucle :
- SCAN <cursor> MATCH otp:* COUNT 100 retourne [newCursor, keys].
- Si keys non vide : MGET k1 k2 ... récupère les valeurs.
- cursor = newCursor.
On s’arrête quand cursor === "0" (cycle terminé).

Pourquoi SCAN plutôt que KEYS ?

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

08.03 — Documentation

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

08.03 — Documentation#

Le projet IA est le plus documenté de l’écosystème d’Ocarina.

Listing#

Document	Statut	Lectorat
`CLAUDE.md`	Contrat de travail Claude ↔ projet	Claude + tout contributeur
`CURA_FRD.md`	Spec reconstruite	Mainteneurs, stakeholders
`CURA_TEST_STRATEGY.md`	Stratégie de test	Mainteneurs
`IDENTIFIED_GAPS.md`	Inventaire technique des gaps	Mainteneurs

`CLAUDE.md`#

Key documents : pointe vers README.md, CURA_FRD.md, CURA_TEST_STRATEGY.md, IDENTIFIED_GAPS.md, CLAUDE.local.md.
Project : 2 phrases sur le projet (CURA, Python 3.14+, demo creds).
Project philosophy : « No tricks or hacks. Teach the pattern, not the symptom. »
CLAUDE.local.md template : ce que doit contenir le fichier gitignored.
Layout : arbre src/ complet, audité (commande shell qui vérifie que CLAUDE.md et l’arbre réel sont synchronisés).
Ocarina hierarchy : rappel Test → Suite → Campaign → Cycle.
Test strategy : structure du cycle, smoke gate, taxonomie.
Running tests : commandes CLI.
Reports and screenshots : règle « un screenshot par drive_page ».
Scenario fragments : quand extraire un fragment.
Data-driven tests : quand utiliser le pattern, conventions de naming.
Mixins partagés : SeleniumBackAndForwardNavigationMixin.
Conventions : 12 règles concrètes (TYPE_CHECKING guard, log factories, etc.).
Hard-won rules : règles tirées de l’expérience, avec exemples du passé.

Hard-won rules#

« Verify SUT behaviour — don’t theorise »#

CURA is open source. Before building on a server-side claim, read the PHP:

09.03.03 — Skills Black-hat

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

09.03.03 — Skills Black-hat (6)#

Idéations de vulnérabilités de logique métier — pas d’exécution : « security testing is functional and static, never active ».

Listing (potentiellement non exhaustif)#

Skill	Cible
`business-logic-vulnerability-ideation`	Faire tomber le produit via des chemins d’usage légitimes mais malicieux
`incoherence-attack-ideation`	Chaque étape prise isolément a l’air innocente ; mais des combinaisons de ces étapes peuvent causer une incohérence dans le système
`persistence-attack-ideation`	Tentatives répétées sur une action bloquée
`permission-appropriateness-audit`	Le modèle d’accès est-il lui-même approprié ?
`bfcache-exposure-ideation`	Attaques BFCache
`lateral-resource-ideation`	IDOR via la barre d’adresse uniquement

Périmètre#

Tous ces skills imaginent des attaques que l’IA pourrait formuler.

10.03 — Workflows ocarina-example

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

10.03 — Workflows `ocarina-example`#

Voir aussi ../07-ocarina-example/11-ci.md

Vue d’ensemble#

Workflow	Trigger	OS	Effet	Note
`main_ci.yml`	push/PR main, dispatch	ubuntu + windows × py 3.14	`make check-coding-style` (mypy + ruff).	Gate PR rapide
`dev_ci.yml`	push dev, dispatch	ubuntu × py 3.14	Idem	Pour branches dev
`e2e.yml`	`workflow_dispatch` (env `OC`)	ubuntu + service Redis + Firefox + geckodriver 0.35.0	Run complet de la suite + upload `.screenshots/` `.ocarina_logs/` `.reports/`	Manuel uniquement

vs `ocarina/main_ci.yml`#

Aspect	`ocarina/main_ci.yml`	`ocarina-example/main_ci.yml`
Tests unitaires	Oui (pytest + cram)	Non
Allure history	Oui	Non
GitHub Pages deploy	Oui (Allure report)	Non
Matrice OS	Oui (ubuntu + windows)	Oui (idem)
Matrice Python	Optionnel (3.14 ou 3.14+3.15)	Non (3.14 seul)

→ ocarina se teste (tests unitaires) en CI. ocarina-example n’est soumis qu’à des tests statiques en CI ; ses tests dynamiques (e2e) sont déclenchés à la demande via e2e.yml.

11.03 — Refus explicites

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

11.03 — Refus explicites#

Synthèse des refus dispersés dans le Holy Book.

Tableau récapitulatif#

Refus	Raison	Référence
`async`/`await`	Selenium synchrone, Requests synchrone ; lisibilité ; aucun intérêt d’introduire une event-loop	Holy Book
Plugin pytest	Indépendance, fidélité ISTQB	`README` Ocarina
DSL textuel (Robot, Gherkin)	Pas de couche de traduction	Holy Book
Programmation réactive	Static scenarios, cache in-memory suffit	Holy Book
Tricks et hacks	« Teach the pattern, not the symptom »	`CLAUDE.md` ai-example
Contributions « stylées »	« C’est ma voiture »	Holy Book
Tests sécurité actifs	Fonctionnel et statique uniquement, jamais d’attaques	`CLAUDE.md` ai-example

1. Refus d’`async`/`await`#

Citation centrale :

12.03 — YTCracker, Nerdcore, Digital Gangster

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

12.03 — YTCracker, Nerdcore, Digital Gangster#

Bryce Case Jr., un seul homme, connecte quatre univers : la scène hackers américaine (1999-2005), la naissance de la Nerdcore (hip-hop de nerd, 2005-2008), Digital Gangster (forum 2005-2017), et la culture crypto (dès 2013, avec notamment Bitcoin Baron). Le Holy Book le cite plusieurs fois.

1. Identité#

Champ	Valeur
Nom	Bryce Case Jr.
Né	23 août 1982, La Mirada, Californie
Alias	YTCracker (prononcé « whitey cracker »)
Statut	Anciennement black hat, désormais white hat (consultant cybersec + musicien)

Le pseudo « YTCracker » se prononce whitey cracker. Il combine « Yours Truly », le nom d’un personnage dans le roman cyberpunk Snow Crash de Neal Stephenson, et le terme cracker — celui qui s’introduit dans des systèmes informatiques. Bryce Case a lui-même expliqué cette étymologie dans plusieurs interviews.

00.04 — Relations entre les six dépôts

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

00.04 — Relations entre les six dépôts#

Chaque arête du graphe est un contrat : un secret, une URL, un type de payload, ou une version. On les détaille ici, par paire.

`ocarina` ↔ `ocarina-example`#

Direction	Mécanisme
`ocarina` → `ocarina-example`	`pip install ocarina` depuis PyPI
`ocarina-example` → `ocarina`	Aucune (l’exemple ne pousse rien)

L’exemple écrit ses propres adapters au-dessus du framework :

lib/ext/ocarina/adapters/agnostic/act.py → ajoute le hook on_failure qui transforme une page d’erreur HTTP (titre matché par ERROR_PAGE_REGEX) en HttpErrorPageReachedError.
lib/ext/ocarina/adapters/agnostic/match_page.py → create_match_page(raised_exceptions=transient_errors).
lib/ext/ocarina/adapters/agnostic/env_getters.py → typed EnvGetters[_CredsKeys, _ValuesKeys].
lib/ext/ocarina/adapters/selenium/test_suite.py → fige max_retries_per_test=8, transient_errors=..., autoscreen_on_fail=True, propage --only/--exclude.
lib/ext/ocarina/adapters/selenium/test_campaign.py → fige max_workers=get_max_workers().

`ocarina` ↔ `ocarina-with-ai-example`#

pip install . ruff mypy mypy-extensions typing-extensions pre-commit car l’exemple IA a la dépendance fixée dans son pyproject.toml : ocarina>=1.0.3.
L’adapter act est minimaliste ici : pas de on_failure (CURA n’a pas de page d’erreur volontairement aléatoire à intercepter). Voir ../08-ai-example/
L’adapter create_drivers_pool est surchargé pour bâtir un Chrome clean (password manager off, leak detection off). Voir ../08-ai-example/06-data-gaps.md

`ocarina-example` ↔ `igoristan`#

Direction	Contrat	Détail
`ocarina-example` → `igoristan`	URLs publiques	Tout passe par `https://mojo-molotov.github.io/igoristan/<route>`
`igoristan` → `ocarina-example`	aucun (le SUT ne sait pas qu’il est testé)	—

src/constants/pages/ :

01.04 — Citations et influences revendiquées

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

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#

Influence	Origine	Rapport avec Ocarina
Railway Oriented Programming (ROP)	Scott Wlaschin (F#), pattern bien connu en programmation fonctionnelle	Le cœur du framework. `Result[T] = Ok[T] \| Fail`, short-circuit, builder fluide. Voir `../02-ocarina/03-railway/`.
λ-calcul (1930)	Alonzo Church	Cité comme l’invention qui rend possible la « formalisation propre » qu’Ocarina poursuit : « Ce que l’on pensait depuis les années 1930, depuis l’invention du λ-calcul, est enfin scalable à l’échelle que l’on aurait toujours voulu lui donner. »
McCulloch & Pitts (1943)	Première formalisation du neurone artificiel	Cité comme rappel que les vrais progrès en IA sont anciens et continus, contre la hype récente.
Système de types Python (PEP 695)	PEP 695 (Python 3.12+)	Pré-requis pour le typage générique paramétrique qui structure Ocarina (`TestSuite[Driver]`, `Result[T]`, etc.). Voir `../03-functional/06-pep-695-generics.md`.

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

Influence	Citation	Pourquoi
Terry Davis (« le programmeur le plus intelligent qui ait jamais existé »)	« Un idiot admire la complexité, un génie admire la simplicité, un physicien essaie de simplifier… »	Argumentaire anti-complexité ostentatoire ; pierre angulaire du chapitre « Premiers retours ».
Lao-Tseu	« Pour avoir de la connaissance, ajouter des choses chaque jour. Pour avoir de la sagesse, enlever des choses chaque jour. »	Démarche de retrait : ce qui reste après élimination.
Antoine de Saint-Exupéry	« La perfection est atteinte non pas lorsqu’il n’y a plus rien à ajouter, mais lorsqu’il n’y a plus rien à retirer. »	Reformulation occidentale du précédent. Clos le chapitre « Premiers scénarios ».
Alan Watts	« La meilleure façon de résoudre un problème est souvent d’en sortir. »	Cité en fin du chapitre « Premiers jutsus » : légitime un design qui refuse certaines fonctionnalités (réactivité, async). Légitime la sortie de l’écosystème des trucs de geeks.
Rainer Maria Rilke	« Pour l’instant, vivez les questions… »	Clos le chapitre « Premiers pas ». Posture envers la pratique : la maîtrise vient par l’usage.
Marcel Proust	« Le style (…) est une question non de technique, mais de vision. »	Clos le chapitre « Extensibilité ». Justifie le refus d’imposer un DSL : la vision (POMs + actions) prime sur la technique (un format).

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

Influence	Origine	Rapport avec Ocarina
*Code is Law*	Lawrence Lessig (1999), repris par Ethereum (2015) comme idéal positif	Cité comme la posture face à la « gouvernance démocratique du code ». Le code est la donnée brute, auditable. Le projet revendique : « De nouveau, avec l’IA, ce maillon qu’il manquait cruellement, crions-le, aussi fort que l’on criait “HACK THE PLANET” en 99 : CODE IS LAW. »
DHH — I won’t let you pay me for my open source	David Heinemeier Hansson, blog perso	Cité pour légitimer le refus de contributions non alignées (« Fuck You » fait référence à la célèbre slide de DHH.)
Paul Graham — Haters	Essai PG (`paulgraham.com/fh.html`)	Justifie la décision de « ne JAMAIS perdre [son] temps à argumenter lorsque ce n’est pas la peine ».
Yegor Bugayenko — Prompt	Citation « Retry flaky blocks. »	Fond la politique `transient_errors` + retries linéaires (`TestFlow`). Lire aussi : Angry Tests.
The DAO hack (2016)	Hack de The DAO sur Ethereum	Cité pour pointer que ce sont les bugs (« des satanés bugs, à cause de satanés dévs ») qui ont fait reculer l’idée de Code is Law, d’où l’importance du typage et de la rigueur.
Lee Robinson (ex-Vercel)	Décembre 2025 : remplacement de Sanity par des fichiers Markdown + IA chez Cursor	Soutient le « retour à la donnée brute ».
Cluely (Roy Lee)	Cité pour illustrer le bullshit entrepreneurial à éviter	Contraste explicite avec la philosophie Ocarina.

Axe identitaire / underground#

Influence	Origine
Lulzsec — « In the Lulzboat, salute, bitch, and show some respect. »	Antisec (YTCracker, 2011)
*« We Can Do All What You Can’t Do* »**	YogyaCarderLink
YTCracker — Robots Will Definitely Take Your Job	Lien SoundCloud, musique de fond du chapitre « Premiers retours »
*« HACK THE PLANET* » (1999)**	Slogan emblématique de la scène hackers des années 1990 + Antisec (YTCracker, 2011)
Zone-H	Site historique de defaces web
r/unixporn, r/AntiTaff	Subreddits

Axe IA / outillage moderne#

Influence	Origine	Rapport avec Ocarina
Claude Code	Anthropic	Outillage de référence du projet IA (`ocarina-with-ai-example`). Cité plusieurs fois comme « pont » remplaçant les DSLs.
IntelliCode (2018)	Microsoft	Cité comme repère temporel (« on y avait déjà goûté, avant même IntelliCode »).
R., savant fou du silo	Anecdote personnelle (un collègue de 2013, plugin Emacs IA privé)	Rappel que l’IA générative (« 15 000 lignes à supprimer pour éviter d’en écrire 1000 ») existait avant la hype publique.
Prisma, Vercel, Cursor	Écosystème SaaS	Cités comme cas pratiques de retour à la donnée brute assisté par IA.

Cohérence d’ensemble#

Toutes ces influences pointent vers trois axes convergents :

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.

03.04 — reduce / fold dans Ocarina

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

03.04 — `reduce` / fold dans Ocarina#

Un seul reduce dans toute la base de code. Mais c’est le réducteur central : il fait fonctionner chain_actions.

Code#

# src/ocarina/dsl/testing_with_railway/chain_actions.py
from functools import reduce

def chain_actions[T](
    first: ActionSuccess[T], *rest: ActionSuccess[T]
) -> ChainRunner[T]:

    def thunk() -> ActionChain[T]:
        def reducer(chain: ActionChain[T], step: ActionSuccess[T]) -> ActionChain[T]:
            if chain.has_failed():
                return chain
            return (
                chain.then(step.__action__)
                .failure(step.__failure_handler__)
                .success(step.__success_handler__)
                .execute()
            )
        return reduce(reducer, rest, first.execute())

    return ChainRunner(thunk=thunk)

Anatomie#

Concept FP	Réalisation Python
Type accumulator	`ActionChain[T]`
Type element	`ActionSuccess[T]`
Reducer	`reducer(chain, step) -> ActionChain[T]`
Initial value	`first.execute()`
Iterable	`rest` (le tuple de `*rest`)
Short-circuit	`if chain.has_failed(): return chain`
Result	`ActionChain[T]` (le dernier)

Flot d’exécution#

initial = first.execute()                                          # → ActionChain(ok=True, result=Ok(...))

step 1 : reducer(<initial>, act2) :
  chain.has_failed() = False
  chain.then(act2.__action__).failure(...).success(...).execute()
  → action lève → Fail
  → failure_handler(exc)  ❌ FIRE
  → ActionChain(ok=False, result=Fail(exc))

step 2 : reducer(<failed>, act3) :
  chain.has_failed() = True
  return chain                                                     ⚠️  short-circuit

result du reduce = <failed ActionChain>

Pourquoi `reduce`#

# Approche impérative (équivalente)
def thunk() -> ActionChain[T]:
    chain = first.execute()
    for step in rest:
        if chain.has_failed():
            break
        chain = (
            chain.then(step.__action__)
            .failure(step.__failure_handler__)
            .success(step.__success_handler__)
            .execute()
        )
    return chain

Reduce	Boucle impérative
Une seule valeur circule (le `chain`)	Un état + une mutation
Reducer = fonction pure (testable en isolation)	Logique inline
Sémantique « accumulateur » explicite	Logique implicite
Standard fonctionnel	Standard impératif

C’est une expression d’intention : on replie une liste sur un accumulator. La sémantique est claire dès la première lecture. C’est ce qu’on appelle un catamorphisme.

04.04 — Tests du typage statique (pytest-mypy-plugins)

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

04.04 — Tests du typage statique (`pytest-mypy-plugins`)#

Cinq fichiers *test_types.yml qui testent le comportement du checker. C’est une dimension de tests unique à Ocarina dans son genre : on s’assure que ce qui devrait être une erreur mypy en est bien une.

Listing#

tests/
├── dsl/
│   ├── invariants/test_types.yml
│   └── testing_with_railway/test_types.yml
└── opinionated/
    ├── cli/test_types.yml
    ├── infra/test_types.yml
    └── plugins/reports/...   (snapshots — pas YAML)

YAML#

- case: compatible_predicate_types
  description: Predicates should accept values of compatible types
  main: |
    from ocarina.dsl.invariants.validate import validate
    from ocarina.dsl.invariants.assertions import is_email, is_positive

    validate(1234).assert_that(is_positive)
    validate("a@a.com").assert_that(is_email)

Sans out: → on attend que mypy passe sans erreur sur le code donné.

05.04 — Composants UI clés

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

05.04 — Composants UI clés#

Les composants src/components/ et leur rôle dans le terrain de jeu.

Listing#

src/components/
├── BackToHome.tsx              # bouton de retour à HOME
├── BackToSicily.tsx            # variante
├── Button.tsx                  # button stylisé Tailwind
├── ChaoticForm.tsx             # ⭐ formulaire avec éléments .catch-me-if-you-can
├── Dropzone.tsx                # ⭐ react-dropzone wrapper pour SACRED_UPLOAD
├── ErrorCode.tsx               # composant affichant un code HTTP (utilisé par RANDOM_ERROR)
├── FakeUpload/                 # composant fake d'upload (animation, pas de vrai POST)
├── InternalErrorMsg.tsx        # message d'erreur générique
├── Label.tsx                   # label de formulaire
├── Link.tsx                    # wrapper de <a> avec styles
├── Loading.tsx                 # spinner générique
├── LoginForm.tsx               # ⭐ formulaire login + MFA OTP
├── PlusButton.tsx              # bouton + (corsicamon : ajouter à la collection)
├── RandomBibleVerse.tsx        # verset biblique aléatoire
├── RandomLoader.tsx            # ⭐ loader random
├── UploadPreview.tsx           # preview d'un fichier uploadé
└── XButton.tsx                 # bouton X de fermeture

⭐ = composant clé pour les scénarios Ocarina.

06.04 — GET /api/corsicadex?id=N

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

06.04 — `GET /api/corsicadex?id=N`#

Fichier source : api/corsicadex.ts

Code#

import type { NextRequest } from "next/server";
import isAuthorized from "../lib/isAuthorized";
import { corsicaDexData } from "../consts/corsicadexData";

export const config = { runtime: "edge" };

const corsHeaders = {
  "Access-Control-Allow-Origin": "*",
  "Access-Control-Allow-Methods": "GET, OPTIONS",
  "Access-Control-Allow-Headers": "x-api-key, Content-Type",
} as const;

export default async function handler(request: NextRequest) {
  if (request.method === "OPTIONS") {
    return new Response(null, { status: 200, headers: corsHeaders });
  }

  if (!isAuthorized(request)) {
    return new Response(JSON.stringify({ error: "Unauthorized" }), {
      status: 401,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  const url = new URL(request.url);
  const id = url.searchParams.get("id");

  if (!id) {
    return new Response(JSON.stringify({ error: "Missing id parameter" }), {
      status: 400,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  const corsicamonId = parseInt(id, 10);

  if (isNaN(corsicamonId)) {
    return new Response(JSON.stringify({ error: "Invalid ID" }), {
      status: 400,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  const corsicamon = corsicaDexData.find((p) => p.id === corsicamonId);

  if (!corsicamon) {
    return new Response(JSON.stringify({ error: "Corsicamon not found" }), {
      status: 404,
      headers: { "Content-Type": "application/json", ...corsHeaders },
    });
  }

  return new Response(JSON.stringify(corsicamon), {
    headers: { "Content-Type": "application/json", ...corsHeaders },
  });
}

Mécanique#

Lookup statique dans un array TypeScript.

07.04 — Scénarios Corsicamon

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

07.04 — Scénarios Corsicamon#

La page « Pokédex corse (Corsicadex) » de l’Igoristan. Saisie d’API key, tirage au sort avec 1/5 d’échec, transient_errors pour Error('lol'), et retries internes au POM face aux états « Corsicamons chargés / erreur réseau ».

Campagne#

# src/tests/campaigns/corsicamon.py
def create_igoristan_corsicamon_campaign(*, drivers_pool) -> TestCampaign:
    return TestCampaign(
        name="Corsicamon",
        suites=[
            create_corsicamon_happy_paths_test_suite(drivers_pool=drivers_pool),
            create_corsicamon_unhappy_paths_test_suite(drivers_pool=drivers_pool),
        ],
    )


def create_igoristan_corsicamon_smoke_campaign(*, drivers_pool) -> TestCampaign:
    return TestCampaign(
        name="Corsicamon - Smoke",
        suites=[create_corsicamon_smoke_tests_suite(drivers_pool=drivers_pool)],
    )

Smoke test#

# tests/scenarios/corsicamon/enter_api_key.py
def scenario_enter_api_key_smoke(driver, logger):
    page = CorsicamonEnterApiKeyPage(driver=driver)
    ...
    return [
        drive_page(
            act(page, open_corsicamon_page)...,
            act(page, verify_enter_api_key_screen)...,
        ),
    ]


test_enter_api_key_smoke = create_selenium_test(
    name="Corsicamon - Smoke - enter API key screen visible",
    test_scenario=lambda driver, logger: Scenario(
        test_chain=scenario_enter_api_key_smoke(driver, logger)
    ),
)

Vérifie juste que la page d’entrée d’API key s’affiche. Si elle ne s’affiche pas → smoke fail → main campaigns skippées.

08.04 — Stratégie de test

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

08.04 — Stratégie de test#

Six types de tests, six rôles distincts. Documentés dans CURA_TEST_STRATEGY.md §3.

Types de test#

Type	Statut attendu	Source d’autorité
Happy path (cas passant)	PASS	Parcours nominaux décrits d’après les SFD
Unhappy path (cas non passant)	PASS (le test passe quand l’application refuse de “laisser passer”)	Validations existantes correctes
Edge case / boundary (tests aux limites)	PASS ou FAIL	Selon le test, souvent accompagné d’une note ajoutée sur les SFD
Business logic vulnerability / gap test (tests fonctionnels pour essayer de faire “tomber” le produit et d’identifier des gaps)	FAIL intentionnel	Comportements qu’un système devrait empêcher mais que CURA n’empêche pas
Exploratory / observed-behaviour (exploratoire)	PASS	Documente le comportement actuel quand la spec ne le couvre pas
Permanent security regression fixture (non-régression)	PASS (= la sécurité tient)	Vérifie qu’un correctif de sécurité tient (correctifs qui resteront définitivement dans le patrimoine de test)

Happy path#

Exercises the nominal flow with valid inputs and an authenticated user. Verifies that the system produces the correct output (confirmation, history entry, etc.).

09.03.04 — Skills Comprehend

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

09.03.04 — Skills Comprehend#

Skills qui aident l’IA à comprendre un projet ou un écosystème avant d’agir.

Listing (potentiellement non exhaustif)#

Skill	Cible
`assess-test-base`	Catalogue la base de test existante
`assess-ecosystem`	Recherche publique bornée, plafonnée par budget de tokens
`assess-impact`	Analyse d’impact : ce qu’un changement touche en aval, à travers le graphe de dépendances
`understand-sut-constraints`	Comprend les “bornes” du SUT pour ne pas les dépasser
`understand-ocarina`	Aiguille selon la classe de question : le Holy Book pour la référence, le livre from-ocarina-to-igor pour l’intention ; puis la source d’Ocarina + l’exemple correspondant à l’adaptateur en place

`understand-ocarina`#

input  : question de l'utilisateur — aiguillée selon sa classe :
            - "comment fait-on un match_page ?"   (référence : ce qu'est une primitive) → Holy Book
            - "pourquoi la suite est-elle bâtie sur Railway ?" (intention / cartographie / pourquoi) → le livre from-ocarina-to-igor
output : Claude charge, selon la classe de question :
            - référence    → les pages Holy Book pertinentes (https://mojo-molotov.github.io/ocarina-holy-book)
            - intention    → les chapitres pertinents du livre from-ocarina-to-igor (https://mojo-molotov.github.io/from-ocarina-to-igor/)
            - comportement → la source d'Ocarina (clone), si la doc ne le couvre pas
            - forme        → l'exemple correspondant à l'adaptateur du projet :
                              Selenium   → ocarina-example, ocarina-with-ai-example
                              Playwright → ocarina-with-playwright-example
         puis répond avec citations (tier + URL de page/chapitre ou file:line)

SKILL.md :

09.04 — CLAUDE.md et CLAUDE.slim.md

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

09.04 — `CLAUDE.md` et `CLAUDE.slim.md`#

Le Holy Book publie activement les fichiers CLAUDE.md. Cela permet à un LLM de récupérer la doc projet sans passer par le repo.

Les deux fichiers#

ai/
├── CLAUDE.md       # version complète (règles + organisation projet)
└── CLAUDE.slim.md  # version courte (règles uniquement)

URLs publiques#

https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.md
https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.slim.md

Citation du Holy Book (chapitre « Utiliser Ocarina avec l’IA ») :

Slim quand le contexte est chargé ; complet pour l’onboarding et les revues. En cas de divergence, le complet l’emporte.

10.04 — Workflows ocarina-with-ai-example

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

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

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

Vue d’ensemble#

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

Différences avec `ocarina-example`#

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

warm-up Heroku#

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

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

12.04 — Zone-H, IRC, EFnet

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

12.04 — Zone-H, IRC, EFnet#

Trois infrastructures sans lesquelles la scène hackers 1998-2012 n’aurait jamais été la même : Zone-H (archive de defaces), IRC, EFnet (le réseau IRC historique). Le Holy Book ne cite Zone-H qu’une fois, mais c’est un mot-clé qui ouvre toute une infrastructure.

1. Zone-H — archive des defaces (2002 → aujourd’hui)#

Fondation#

Date : 2 mars 2002.
Siège : Estonie.
Fondateur : Roberto Preatoni (alias Sys64738).
URL : zone-h.org

Fonction#

Un attaquant deface un site (remplace la homepage par sa propre version, signée).
L’attaquant (ou un témoin) soumet l’URL à Zone-H.
Zone-H modère : vérifie que le deface est authentique.
Si OK : le site défiguré (deface) est archivé pour toujours sur Zone-H (snapshot du HTML+CSS+assets).
L’auteur du deface signe avec son alias. Le sourçage est public.

Impact#

Pendant 10-15 ans, Zone-H a été le tableau d’affichage public de la scène grey hat mondiale. Chaque deface notable était archivé. Pour un script kiddie, monter dans le classement Zone-H était le but pour prouver :

01.05 — Posture politique du projet

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

01.05 — Posture politique du projet#

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

1. Incorruptibilité#

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

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

02.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é.

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 :

04.05 — Snapshot testing (syrupy)

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

04.05 — Snapshot testing (`syrupy`)#

syrupy est un plugin pytest qui sérialise la sortie d’un test dans un fichier .ambr et compare aux runs suivants. Utilisé pour la sortie de pretty_print_results et results_to_json.

`.ambr`#

tests/opinionated/plugins/reports/__snapshots__/
├── test_pretty_print_results.ambr
└── test_results_to_json.ambr

Généré et géré par syrupy.

Exemple#

# tests/opinionated/plugins/reports/test_pretty_print_results.py
def test_pretty_print_results_renders_campaign_suite_test(snapshot, capsys):
    results = {
        "Dashboard": {
            "Login happy paths": {
                "Login - without OTP": (Ok(None), 5, "login_no_otp"),
                "Login - with OTP": (Fail(error=RuntimeError("OTP missed")), 8, "login_otp"),
                "Skipped one": (None, -1, "skipped_one"),
            },
        },
    }
    pretty_print_results(results, with_colors=False)
    out = capsys.readouterr().out
    assert out == snapshot

Le snapshot (fixture de syrupy) :

05.05 — Pipelines wireit

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

05.05 — Pipelines `wireit`#

wireit est un orchestrateur de scripts NPM avec cache incrémental. L’Igoristan l’utilise pour enchaîner format-check, lint, typecheck, prebuild, build, dev, preview, le tout avec un cache fin par tâche.

`package.json#wireit`#

"wireit": {
  "ci:format-check": {
    "command": "prettier . --check",
    "files": ["*.{js,ts,jsx,tsx,json,md,mdx,html,css,scss,yml,yaml}"],
    "output": []
  },
  "clean:dist": {
    "command": "rimraf dist",
    "files": ["dist/"],
    "output": []
  },
  "prebuild": {
    "files": ["src/**/*.*", "package.json", "packages/**/*.*", "packages/**/package.json", "vite.config.ts"],
    "dependencies": ["lint", "typecheck"]
  },
  "preview": {
    "command": "vike preview",
    "dependencies": ["build"]
  },
  "dev": {
    "command": "vike dev",
    "files": ["src/**/*.*", "packages/**/*.*"],
    "dependencies": ["prebuild"],
    "output": ["dist/"],
    "packageLocks": ["pnpm-lock.yaml"]
  },
  "build": {
    "command": "vike build",
    "files": ["src/**/*.*", "packages/**/*.*"],
    "dependencies": ["prebuild"],
    "output": ["dist/"],
    "packageLocks": ["pnpm-lock.yaml"]
  },
  "lint": {
    "command": "eslint \"./{src,packages}/**/*.{js,jsx,ts,tsx}\" --max-warnings 0 --cache",
    "files": ["src/**/*.*", "package.json", "packages/**/*.*", "eslint.config.ts"],
    "output": []
  },
  "typecheck": {
    "command": "tsc --build --pretty tsconfig.json",
    "files": ["src/**/*.*", "package.json", "tsconfig.app.json", "tsconfig.json", "tsconfig.node.json"],
    "output": ["typecheck-dist/"]
  }
}

DAG#

                 ┌─────────────────┐
                 │ ci:format-check │ ────► prettier . --check
                 └─────────────────┘
                 ┌─────────────────┐
                 │     lint        │ ────► eslint (max-warnings 0, --cache)
                 └─────┬───────────┘
                       │
                 ┌─────▼───────────┐
                 │   typecheck     │ ────► tsc --build --pretty
                 └─────┬───────────┘
                       │
                 ┌─────▼───────────┐
                 │   prebuild      │ ────► deps: [lint, typecheck]
                 └─────┬───────────┘
                       │
            ┌──────────┴──────────┐
            ▼                     ▼
   ┌─────────────────┐    ┌─────────────────┐
   │   build         │    │   dev           │
   │   vike build    │    │   vike dev      │
   └────┬────────────┘    └─────────────────┘
        ▼
   ┌─────────────────┐
   │   preview       │
   │   vike preview  │
   └─────────────────┘

Avec pnpm dev :

06.05 — isAuthorized.ts

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

06.05 — `isAuthorized.ts`#

Fichier source : lib/isAuthorized.ts

Vérifie qu’une requête contient le bon x-api-key.

Code#

import type { NextRequest } from "next/server";

const API_SECRET = process.env.API_SECRET;

function isAuthorized(request: NextRequest): boolean {
  if (typeof API_SECRET !== "string") {
    console.error("[CONFIG ERROR] API_SECRET is not defined");
    return false;
  }

  const { searchParams } = new URL(request.url);
  const apiKey = searchParams.get("apiKey") ?? request.headers.get("x-api-key");
  return apiKey === API_SECRET;
}

export default isAuthorized;

Approche#

1. `API_SECRET`#

const API_SECRET = process.env.API_SECRET;

Lu une seule fois, au démarrage du worker Edge (cold start).
Stocké en tant que variable de module.

07.05 — Scénarios randomness (4 levels)

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

07.05 — Scénarios randomness (4 levels)#

Quatre niveaux de chaos progressifs. On commence simple, on monte en complexité, on stresse de plus en plus Ocarina.

Campagne#

# src/tests/campaigns/randomness.py
def create_igoristan_randomness_campaign(*, drivers_pool) -> TestCampaign:
    return TestCampaign(
        name="Randomness",
        suites=[create_randomness_test_suite(drivers_pool=drivers_pool)],
    )

Suite#

# src/tests/suites/randomness.py
def create_randomness_test_suite(*, drivers_pool) -> TestSuite:
    return TestSuite(
        name="Randomness",
        tests=[
            test_random_error_page,                     # level 1
            test_random_loaders_page,                   # level 1
            test_dsed,                                  # level 2
            test_madness,                               # level 2
            test_chaotic_form,                          # level 3
            test_walkthrough,                           # level 4
        ],
        drivers_pool=drivers_pool,
    )

Levels#

Level	Mécanique exercée	Difficulté
1	DSL de base (`drive_page`, `act`)	facile
2	`match_page` / `when`	moyen
3	`HumanizedDriver` + `Watcher`	difficile
4	Walkthrough multi-pages chaotiques	difficile

Level 1 — Random Error Page#

# tests/scenarios/randomness/level_1/random_error_page.py
def scenario_random_error_page(driver, logger):
    page = RandomErrorPage(driver=driver)
    return [
        drive_page(
            act(page, open_random_error_page)...,
            act(page, verify_random_error_page)...,
        ),
    ]


test_random_error_page = create_selenium_test(
    name="Random Error Page - smoke",
    test_scenario=lambda driver, logger: Scenario(test_chain=scenario_random_error_page(driver, logger)),
)

Test volontairement flaky, exerce le hook on_failure.

08.05 — Gaps sécurité (G-SEC-1 à G-SEC-3)

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

08.05 — Gaps sécurité (G-SEC-1 à G-SEC-3)#

Trois gaps de sécurité documentés. Pas exploités activement (cf. règle « security testing is functional and static, never active »), mais observés via tests fonctionnels.

G-SEC-1 — Pas de jeton CSRF sur les formulaires côté front-end#

Symptôme#

Le <form> rendu côté Heroku ne contient pas de CSRF token.

Source#

views/page_appointment.php du repo GitHub appelle $antiCSRF->insertHiddenToken() avant le bouton submit. Mais sur la version déployée, ce token n’apparaît pas dans le HTML.

09.03.05 — Skills Pick

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

09.03.05 — Skills Pick#

Sélection d’artefacts (screenshots, logs, reports). Toujours par mtime, jamais par nom de fichier.

Listing (potentiellement non exhaustif)#

Skill	Cible
`pick-screenshots`	Pioche les screenshots les plus récents (par mtime), en les contextualisant à l’aide de logs si possible
`pick-logs`	Pioche les logs les plus récents (par mtime)
`pick-reports`	Pioche les reports DOCX/JSON les plus récents (par mtime)

« mtime »#

Citation du Holy Book :

09.05 — Génération de PDF (generate-books)

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

09.05 — Génération de PDF (`generate-books`)#

Les PDFs publics (ocarina-ru.pdf, ocarina-en.pdf, ocarina-fr.pdf…) sont générés par IA à partir du dossier docs/, d’un script Python et d’un prompt Markdown.

Arborescence#

prompts/generate-books/
├── prompt.md                     # spec (lu par l'IA)
├── script.py                     # implémentation Python
├── NotoSans-Regular.ttf
├── NotoSans-Bold.ttf
├── NotoSans-Italic.ttf
├── NotoSans-BoldItalic.ttf
├── NotoSansMath-Regular.ttf
├── NotoSansMono-Regular.ttf
├── NotoSansSymbols2-Regular.ttf
├── NotoNaskhArabic-Regular.ttf
└── NotoColorEmoji-Regular.ttf

1. Un `prompt.md` + un `script.py`#

prompt.md :

Ocarina PDF Generator#

What this is#

A system that turns a VitePress docs/ folder (Markdown + images) into three polished A4 PDFs — one Russian, one English, one French. The system is two files: this prompt (the spec) and script.py (the implementation). They are designed to be used together in an agentic environment.

10.05 — Workflows igoristan

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

10.05 — Workflows `igoristan`#

Voir aussi ../05-igoristan/07-ci-deploy.md

Vue d’ensemble#

Workflow	Trigger	OS	Effet	Note
`ci-pr.yml`	PR `**`, dispatch	ubuntu × node 24 + pnpm 10	3 jobs parallélisés : `wireit ci:format-check` + `wireit lint` + `wireit typecheck`	Gate PR
`deploy.yml`	push main, dispatch	ubuntu × node 24 + pnpm 10	`pnpm install --frozen-lockfile` + `pnpm build` + upload Pages	Production

`ci-pr.yml`#

jobs:
  format-check:
    env:
      WIREIT_CACHE: github
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v5
        with: { version: 11 }
      - uses: actions/setup-node@v6
        with: { node-version: 24, cache: "pnpm" }
      - uses: google/wireit@setup-github-actions-caching/v2
      - run: make install
      - name: Formatcheck
        run: make ci:format-check

  lint:
    env:
      WIREIT_CACHE: github
    steps:
      # ... idem setup ...
      - uses: actions/cache@v5
        with:
          path: .eslintcache
          key: eslint-cache-${{ hashFiles('eslint.config.ts', 'src/**/*.*', 'package.json') }}
      - name: Lint
        run: pnpm lint

  typecheck:
    env:
      WIREIT_CACHE: github
    steps:
      # ... idem setup ...
      - name: Typecheck
        run: pnpm typecheck

Job	Cache supplémentaire
`format-check`	wireit
`lint`	wireit + `.eslintcache` (actions/cache)
`typecheck`	wireit + `tsbuildinfo` (via wireit)

`WIREIT_CACHE: github`#

env:
  WIREIT_CACHE: github
steps:
  - uses: google/wireit@setup-github-actions-caching/v2

Active le cache wireit. Les runs successifs réutilisent les artefacts wireit.

12.05 — Les hackers indonésiens début 2000s

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

12.05 — Les hackers indonésiens début 2000s#

Le Holy Book cite « le premier groupe d’hackers indonésiens » sans le nommer dans le texte principal, mais le mantra cité (« We Can Do All What You Can’t Do ») est bien celui de YogyaCarderLink (YCL). Reste à expliquer pourquoi la scène indonésienne de cette époque mérite d’être citée dans un manifeste de framework de test en 2026.

1. Les émeutes de mai 1998#

Le déclencheur#

En mai 1998, l’Indonésie traverse une crise économique majeure (impact de la crise asiatique de 1997) et une crise politique (fin du régime Suharto). Des émeutes éclatent à Jakarta, Medan, Surakarta, ciblant notamment la minorité chinoise indonésienne (commerçants, classe moyenne). Estimations : ~1000 morts, centaines de viols documentés.

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

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 :

03.06 — Generics PEP 695 dans Ocarina

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

03.06 — Generics PEP 695 dans Ocarina#

Ocarina exploite à fond la syntaxe générique introduite par PEP 695 (Python 3.12+). C’est ce qui rend tout l’écosystème typé sans que ce soit le foutoir.

Trois formes de PEP 695#

1. Classes génériques#

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

class TestSuite[Driver]:
    ...

class Watcher[Driver]:
    ...

class ChainRunner[T]:
    ...

class ValidationStartBlock[T]:
    ...

class CliStore[TKeys: str]:  # avec bound
    ...

Avant PEP 695 :

04.06 — Property-based testing (hypothesis)

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

04.06 — Property-based testing (`hypothesis`)#

Un seul fichier (test_invariants_properties.py), mais le pattern est intéressant : on génère des inputs et on vérifie des propriétés universelles des prédicats d’invariants.

Le concept#

hypothesis génère automatiquement des cas de test qui satisfont des contraintes données, puis vérifie qu’une propriété est vraie pour tous les cas générés. En cas d’échec, hypothesis fait du shrinking pour trouver le plus petit contre-exemple.

from hypothesis import given, strategies as st

@given(st.integers())
def test_is_positive_passes_on_positive(value):
    if value >= 0:
        is_positive(value)             # ne doit pas lever
    else:
        with pytest.raises(InvariantViolationError):
            is_positive(value)         # doit lever

→ hypothesis génère des entiers (typiquement 100 par défaut), vérifie la propriété pour chacun. Si une exception inattendue surgit, c’est un fail. Le shrinker trouve le plus petit cas qui fail (0 ? -1 ? MIN_INT ?).

05.06 — Husky + lint-staged + commitlint + commitizen

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

05.06 — Husky + lint-staged + commitlint + commitizen#

Discipline de commits stricte. Conventionnels, signés, format-checkés.

Outils#

Outil	Rôle
Husky	Installe les hooks Git locaux (`pre-commit`, `commit-msg`)
lint-staged	Lance des outils seulement sur les fichiers staged
commitlint	Vérifie que le message de commit suit la convention
commitizen + cz-commitlint	CLI interactive pour composer un message conforme

Config#

`.husky/`#

Dossier contenant les hook scripts :

.husky/
├── pre-commit
└── commit-msg

pre-commit :

06.06 — lib/redis.ts + Upstash

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

06.06 — `lib/redis.ts` + Upstash#

Fichier source : lib/redis.ts

Code#

import { Redis } from "@upstash/redis";

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
});

export default redis;

Pourquoi `@upstash/redis` plutôt que `ioredis`#

Critère	`ioredis`	`@upstash/redis`
Protocole	TCP / RESP	HTTP / REST
Edge runtime	❌ Non	✅ Oui
Connexion	Persistante	Per-request
Latence (warm)	< 1ms	50-100ms
Latence (cold)	200ms+	50-100ms
Coût	Variable	Pay-per-request
Setup	Self-hosted Redis	Upstash dashboard (managed)

L’Edge runtime n’accepte pas de connexions TCP persistantes (chaque worker est éphémère).
Donc : Upstash REST.

07.06 — Scénarios sacred upload

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

07.06 — Scénarios sacred upload#

La page /igoristan/sacred-upload permet de glisser-déposer un fichier. Exerce le pattern d’upload de fichiers côté Ocarina.

Campagne#

# src/tests/campaigns/sacred_upload.py
def create_igoristan_sacred_upload_campaign(*, drivers_pool) -> TestCampaign:
    return TestCampaign(
        name="Sacred upload",
        suites=[
            create_sacred_upload_happy_paths_test_suite(drivers_pool=drivers_pool),
            create_sacred_upload_unhappy_paths_test_suite(drivers_pool=drivers_pool),
        ],
    )

Scénario : upload files#

# tests/scenarios/sacred_upload/upload_files.py
def scenario_upload_files(driver, logger):
    page = SacredUploadPage(driver=driver)
    fixture_dir = Path(__file__).parent.parent.parent.parent / "pages" / "sacred_upload" / "fixtures"
    file_to_upload = fixture_dir / "sample.png"

    return [
        drive_page(
            act(page, open_sacred_upload_page)...,
            act(page, verify_sacred_upload_page)...,
            act(page, upload_file(file_to_upload))...,
            act(page, verify_file_uploaded(file_to_upload.name))...,
        ),
    ]


test_upload_files = create_selenium_test(
    name="Sacred upload - upload a file",
    test_scenario=lambda driver, logger: Scenario(test_chain=scenario_upload_files(driver, logger)),
)

`<input type="file">`#

class SacredUploadPage(SeleniumTitleMixin, POMBase):
    _file_input = (By.CSS_SELECTOR, "input[type='file']")
    _uploaded_preview = (By.CSS_SELECTOR, ".upload-preview")

    def upload_file(self, file_path: Path) -> SacredUploadPage:
        file_input = self._driver.find_element(*self._file_input)
        file_input.send_keys(str(file_path.resolve()))     # ← Selenium pattern: send_keys sur input[type=file]
        return self

    def verify_file_uploaded(self, filename: str) -> SacredUploadPage:
        WebDriverWait(self._driver, get_timeout()).until(
            ec.text_to_be_present_in_element(self._uploaded_preview, filename)
        )
        return self

Le pattern Selenium standard : send_keys(<path absolu>) sur un input[type=file] même si l’input est invisible. Selenium contourne la sécurité du navigateur pour les inputs file uniquement.

08.06 — Gaps data (G-DATA-1, G-DATA-2)

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

08.06 — Gaps data (G-DATA-1, G-DATA-2)#

Deux gaps majeurs sur l’intégrité des données.

G-DATA-1 — Pas de validation serveur de `visit_date`#

Source#

// appointment.php
array_diff_key($_POST, array(
    "facility" => "",
    "hospital_readmission" => "",
    "programs" => "",
    "visit_date" => "",
    "comment" => ""
))

Cette ligne fait juste une vérification de présence des clés.
Elle ne valide jamais la valeur de visit_date.

Symptôme#

Empty visit_date : si on supprime l’attribut HTML5 required via JS et qu’on submit avec une date vide → prise de RDV acceptée.
Past visit_date : si on envoie une réservation antidatée → prise de RDV acceptée.
La réservation est bien ajoutée à l’historique telle quelle.

Tests associés#

Test	Manière
`Appointment - Server accepts empty date when client bypass applied`	Retire l’attribut `required`, envoie avec date de réservation vide → s’attend à être rejeté par le système (FAIL)
`Appointment - Past date booking accepted`	Envoie une demande de RDV pour hier → s’attend à être rejeté par le système (FAIL)

Les deux tests sont intentionnellement en échec.
Ils documentent le gap.

09.03.06 — Skills Author

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

09.03.06 — Skills Author#

Skills qui produisent un livrable. Tests, sondes, docs, rapports.

Listing (potentiellement non exhaustif)#

Skill	Cible
`empiricism`	Vérifier avant d’encoder ; ne pas écraser un test gap en échec intentionnel
`write-a-probe`	Script de “sonde” jetable, gitignored
`write-test-strategy`	Génère le document de stratégie de test à partir de la suite
`extend-coverage`	Étend la couverture à partir du patrimoine existant
`update-frd-and-tests`	Propage une mise à jour de spec
`manual-reproduction-guide`	Rédige un scénario de reproduction exécutable par un humain
`manage-backlog`	`BACKLOG.md`
`pr-report`	Rapport de PR adapté
`plan-test-effort`	Chiffrage de l’effort de test, première passe : exigences graduées, registre de risques allégé, poids relatifs (S / M / L), questions ouvertes

`empiricism`#

input  : intention de l'utilisateur (« écris un test qui assert X »)
output : avant d'encoder X :
            1. vérifier empiriquement que X est vrai
                - sonde
                - gh api du code source
                - curl -v pour inspecter réponses HTTP
                - ...
            2. si X est confirmé → encoder
            3. si X est faux → corriger l'intention
            4. si X est ambigu → demander à l'humain

« Juste remarque, je suppose. Je vérifie empiriquement. »

09.06 — Ressources publiques

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

09.06 — Ressources publiques#

Tableau complet des URLs publiques exposées par le Holy Book. Pour les humains, les LLMs, les scrapers.

Listing (potentiellement non exhaustif)#

URL	Contenu	Public cible
`https://mojo-molotov.github.io/ocarina-holy-book/`	Page d’accueil (EN)	Humain
`https://mojo-molotov.github.io/ocarina-holy-book/fr/`	Page d’accueil (FR)	Humain
`https://mojo-molotov.github.io/ocarina-holy-book/ru/`	Page d’accueil (RU)	Humain
`https://mojo-molotov.github.io/ocarina-holy-book/what-is-it`	Article (EN)	Humain
`https://mojo-molotov.github.io/ocarina-holy-book/fr/what-is-it`	Article (FR)	Humain
`https://mojo-molotov.github.io/ocarina-holy-book/ru/what-is-it`	Article (RU)	Humain
… (autres pages doc en EN+FR+RU)	…	Humain
`https://mojo-molotov.github.io/ocarina-holy-book/llms.txt`	Index minimaliste pour LLMs	LLM
`https://mojo-molotov.github.io/ocarina-holy-book/llms-full.txt`	Tout le contenu en plaintext	LLM, scraper
`https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.md`	Règles projet complètes	LLM, humain (onboarding)
`https://mojo-molotov.github.io/ocarina-holy-book/CLAUDE.slim.md`	Règles projet courtes	LLM (context budget)
`https://mojo-molotov.github.io/ocarina-holy-book/ocarina-en.pdf`	Doc en PDF A4 (EN)	Humain (offline)
`https://mojo-molotov.github.io/ocarina-holy-book/ocarina-fr.pdf`	Doc en PDF A4 (FR)	Humain (offline)
`https://mojo-molotov.github.io/ocarina-holy-book/ocarina-ru.pdf`	Doc en PDF A4 (RU)	Humain (offline)
`https://mojo-molotov.github.io/ocarina-holy-book/skills/<name>`	Page d’un skill IA	Humain, LLM
`https://mojo-molotov.github.io/ocarina-holy-book/assets/content/...`	Images, sons (covers d’articles, illustrations)	Humain (rendu inline)

`llms.txt` (standard émergent)#

Spec : https://llmstxt.org/ (proposé en 2024).

10.06 — Workflow ocarina-holy-book

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

10.06 — Workflow `ocarina-holy-book`#

Un seul workflow : deploy.yml. Sur push main → build VitePress → upload Pages.

Code#

name: Deploy Ocarina Holy Book

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

env:
  TZ: Europe/Paris

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0 # ← full clone

      - uses: pnpm/action-setup@fcf821c621167805dd63a29662bd7cb5676c81a8
        name: Install pnpm
        with:
          version: 11

      - name: Use Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: "pnpm"

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Build
        run: pnpm build

      - uses: actions/upload-pages-artifact@v4
        with:
          path: docs/.vitepress/dist

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

Analyse#

1. `TZ: Europe/Paris`#

env:
  TZ: Europe/Paris

Force la timezone du runner à Europe/Paris.
Les dates rendues par VitePress (« Last update: 18/05/2026 11h42 ») sont à l’heure de Paris, pas en UTC.

12.06 — Yung Innanet (kayos) + VX Underground

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

12.06 — Yung Innanet (`kayos`) + VX Underground#

Le passage le plus violent du Holy Book reprend des paroles de true colors, morceau de Yung Innanet (alias kayos), sysadmin originel de VX Underground. Yung Innanet est mort le 18 octobre 2025 d’un suicide à l’arme à feu.

1. Identité#

Champ	Valeur
Alias musical	Yung Innanet
Pseudonyme tech	kayos (prononcé /kɛjəʊs/)
Twitter	`@yunginnanet`
GitHub	`yunginnanet/yunginnanet`
Rôle reconnu	Sysadmin originel de VX Underground
Décès	18 octobre 2025, suicide à l’arme à feu
Profil Last.fm	Yung Innanet — Last.fm
SoundCloud	vxug.fakedoma.in — SoundCloud

L’information sur le décès n’a pas fait la une des médias mainstream, ce qui est cohérent avec le profil underground de Yung Innanet. Elle est néanmoins publique au sein de sa scène : confirmée notamment par des tweets de YTCracker et de la veuve de Yung Innanet. Il n’y a pas matière à épiloguer, cette mention existe uniquement pour expliquer une citation du Holy Book qui n’aurait pas de sens sans elle.

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.07 — Watcher[Driver]

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

02.07 — `Watcher[Driver]`#

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

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

Le problème#

Citation du Holy Book (handling-flakiness) :

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

03.07 — Unions discriminées + TypeGuard + @final = unions « sealed »

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

03.07 — Unions discriminées + TypeGuard + @final = unions « sealed »#

Le combo qui rend Result[T] et TestResult à la fois typés et utilisables sans cast.

Union discriminée#

@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

Deux constructeurs : Ok[T] et Fail.
Le discriminant est l’isinstance check (pas un champ comme tag: Literal["ok", "fail"]).
Les deux sont @final : aucun sous-type possible. → l’union est exhaustive, donc « sealed ».

Narrowing, `TypeGuard`#

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)

def handle_result(result: Result[int]) -> str:
    if is_ok(result):
        return f"Got: {result.value}"          # mypy : result est Ok[int], donc .value existe
    if is_fail(result):
        return f"Error: {result.error}"        # mypy : result est Fail, donc .error existe
    # mypy peut détecter que cette branche est inatteignable (exhaustivité)

`_BaseResult`#

class _BaseResult:
    error: Exception | None

Cette base permet d’accéder à result.error sans narrower :

04.07 — Politique de couverture : ce qui est testé, ce qui ne l'est pas, pourquoi

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

04.07 — Politique de couverture : ce qui est testé, ce qui ne l’est pas, pourquoi#

La couverture par ligne est explicitement scopée au DSL pur et à l’infra agnostique. Le reste est testé par d’autres moyens (cram, types, snapshots, e2e) ou hors scope (shapes inertes).

`pyproject.toml#tool.coverage.run`#

[tool.coverage.run]
omit = [
    "*/__init__.py",
    "*/tests/*",
    "*/test_*.py",
    "src/ocarina/custom_errors/*",
    "src/ocarina/custom_types/*",
    "src/ocarina/ports/*",
    "src/ocarina/opinionated/loggers/custom_types/*",
    "src/**/*singleton.py",
    "src/**/consts/**",
    # Selenium adapter layer — exercised only against a real browser.
    "src/ocarina/infra/selenium/*",
    "src/ocarina/dsl/testing/selenium/*",
    "src/ocarina/opinionated/cli/selenium/*",
    "src/ocarina/pom/selenium/muted.py",
    # Playwright adapter layer — exercised only against a real browser.
    "src/ocarina/infra/playwright/*",
    "src/ocarina/dsl/testing/playwright/*",
    "src/ocarina/opinionated/cli/playwright/*",
    "src/ocarina/pom/playwright/*",
    "src/ocarina/opinionated/cli/phantoms.py",
    # Opinionated loggers — only file_logger.py stays in scope.
    "src/ocarina/opinionated/loggers/create_matching_logger.py",
    "src/ocarina/opinionated/loggers/muted_logger.py",
    "src/ocarina/opinionated/loggers/print_logger.py",
    "src/ocarina/opinionated/loggers/print_and_file_logger.py",
    "src/ocarina/opinionated/loggers/utils/*",
    # Traversed by cram tests
    "src/ocarina/opinionated/cli/store.py",
    "src/ocarina/opinionated/cli/builder.py",
]

Catégories#

1. Exclusions évidentes#

Pattern	Justification
`*/__init__.py`	Modules vides (Python 3 n’en a souvent pas besoin)
`/tests/`, `/test_.py`	Les tests ne se testent pas eux-mêmes

2. Types / errors / ports / shapes#

Chemin	Justification
`src/ocarina/custom_types/*`	Juste des `type X = ...` et frozen dataclasses. Pas de logique runtime.
`src/ocarina/custom_errors/*`	Juste des sous-classes d’Exception. Pas de logique.
`src/ocarina/ports/*`	ABCs et Protocols. Pas de comportement.
`src/ocarina/opinionated/loggers/custom_types/*`	id.
`src//consts/`	Constantes (`LOGGERS_CHOICES = (...)`).
`src/*/singleton.py`	Wrappers Singleton triviaux.

3. Couches Selenium et Playwright (e2e seulement)#

Chemin	Justification
`src/ocarina/infra/selenium/*`	Code Selenium réel (`Chrome()`, `Firefox()`). Ne s’exécute qu’avec un vrai navigateur.
`src/ocarina/dsl/testing/selenium/*`	`create_selenium_test`, `create_selenium_watcher` (factory triviales sur `Test` / `Watcher`).
`src/ocarina/opinionated/cli/selenium/*`	`create_selenium_*_cli_store` (lit `platform.system`, instancie).
`src/ocarina/pom/selenium/muted.py`	`MutedPOM` utilitaire (presque vide).
`src/ocarina/infra/playwright/*`	Code Playwright réel + l’acteur `PlaywrightDriver`. Le test de bout en bout ne se prouve qu’avec un vrai navigateur.
`src/ocarina/dsl/testing/playwright/*`	`create_playwright_test`, `create_playwright_watcher` (mêmes factory triviales).
`src/ocarina/opinionated/cli/playwright/*`	`create_playwright_cli_store` (CLI Playwright).
`src/ocarina/pom/playwright/*`	`MutedPlaywrightPOM` + `mixins` (Null Object, presque vide).

Ces fichiers sont couverts par :

05.07 — CI/CD de l'Igoristan

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

05.07 — CI/CD de l’Igoristan#

Deux workflows : ci-pr.yml sur PR (3 jobs parallèles), deploy.yml sur push main (GitHub Pages).

`ci-pr.yml`#

name: CI/PR

on:
  pull_request:
    branches: ["**"]
  workflow_dispatch:

defaults:
  run:
    shell: bash

jobs:
  format-check:
    runs-on: ubuntu-latest
    env:
      WIREIT_CACHE: github
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v5
        with: { version: 11 }
      - uses: actions/setup-node@v6
        with: { node-version: 24, cache: "pnpm" }
      - uses: google/wireit@setup-github-actions-caching/v2
      - name: Install project
        run: make install
      - name: Formatcheck
        run: make ci:format-check

  lint:
    runs-on: ubuntu-latest
    env:
      WIREIT_CACHE: github
    steps:
      # ... idem ...
      - uses: actions/cache@v5
        with:
          path: .eslintcache
          key: eslint-cache-${{ hashFiles('eslint.config.ts', 'src/**/*.*', 'package.json') }}
      - name: Lint
        run: pnpm lint

  typecheck:
    runs-on: ubuntu-latest
    env:
      WIREIT_CACHE: github
    steps:
      # ... idem ...
      - name: Typecheck
        run: pnpm typecheck

Job	Commande	Cache
`format-check`	`pnpm exec prettier . --check` (via wireit)	wireit + node_modules
`lint`	`pnpm exec eslint ... --max-warnings 0 --cache`	wireit + `.eslintcache` (actions/cache)
`typecheck`	`tsc --build --pretty tsconfig.json`	wireit + `tsbuildinfo`

                          PR opened / push
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
        ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
        │ format-check │ │     lint     │ │  typecheck   │
        │ (1-2 minutes)│ │ (1-2 minutes)│ │ (1-2 minutes)│
        └──────────────┘ └──────────────┘ └──────────────┘
                │                 │                 │
                └─────────────────┴─────────────────┘
                                  ▼
                             PR mergeable

`deploy.yml`#

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: pnpm/action-setup@v5
        with: { version: 11 }
      - uses: actions/setup-node@v6
        with: { node-version: 24, cache: "pnpm" }
      - name: Install dependencies
        run: pnpm install --frozen-lockfile
      - name: Build
        run: pnpm build
      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v4
        with: { path: dist/client }

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v5

Job	Effet
`build`	`pnpm install --frozen-lockfile` → `pnpm build` (= `wireit build` = `lint → typecheck → vike build`) → upload `dist/client`
`deploy`	`actions/deploy-pages@v5` → publie l’artifact → URL = https://mojo-molotov.github.io/igoristan/

`concurrency: pages` + `cancel-in-progress: false`#

concurrency:
  group: "pages"
  cancel-in-progress: false

Empêche deux déploiements simultanés (race condition).
Le second attend (cancel-in-progress: false → on ne cancel pas le run en cours).

06.07 — Flux de coordination OTP + l'anti-précision volontaire

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

06.07 — Flux de coordination OTP + l’imprécision volontaire#

La raison d’être du backend : permettre à N workers parallèles d’Ocarina de récupérer le bon OTP pour leur user, même quand plusieurs OTP sont générés.

Flux#

   ┌───────────────────────────────────────────────────────────────────┐
   │               Worker (parmi --workers 3 d'Ocarina)                │
   └───────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Selenium ouvre la page de connexion au Dashboard                  │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Acquisition du lock distribué Redis (OTP_SEND_LOCK_KEY)           │
   │   → seul ce worker peut cliquer "Send OTP" pendant ACQ            │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ min_utc_date = datetime.now(UTC)                                  │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Cache L1 : enregistre min_utc_date + username dans le cache       │
   │   (clés réservées par reserve_free_cache_key)                     │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Selenium tape username + password + cocher OTP + click "REQ OTP"  │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ IGORISTAN UI : fetch /api/otp?_user=<username>                    │
   │   (x-api-key tapé par Selenium dans l'UI)                         │
   └─────────────────────────────────┬─────────────────────────────────┘
                                     ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ TESTS-WORKERS /api/otp :                                          │
   │   generate(secret) → otpCode                                      │
   │   createdAt = floor(now/1000)*1000  ← amputation ms               │
   │   event = { _user, otpCode, createdAt, expiresAt, ... }           │
   │   redis.set("otp:<now>:<uuid>", JSON, EX 360)                     │
   │   return event                                                    │
   └──────────────────────────────────┬────────────────────────────────┘
                                      ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ IGORISTAN UI : affiche écran OTP                                  │
   └──────────────────────────────────┬────────────────────────────────┘
                                      ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Release du lock Redis OTP_SEND_LOCK_KEY                           │
   └──────────────────────────────────┬────────────────────────────────┘
                                      ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Selenium : retrieve_dashboard_otp_code(min_utc_date, _user)       │
   │   ↓                                                               │
   │   GET /api/otp-history  (x-api-key = IGOR_API_KEY)                │
   │   ↓                                                               │
   │   TESTS-WORKERS : SCAN otp:* + MGET → all events                  │
   │   ↓                                                               │
   │   filtre côté client par _user                                    │
   │   filtre createdAt >= min_utc_date - 1s                           │
   │   tri ASC sur createdAt                                           │
   │   return first.otpCode                                            │
   └──────────────────────────────────┬────────────────────────────────┘
                                      ▼
   ┌───────────────────────────────────────────────────────────────────┐
   │ Selenium tape l'OTP dans l'UI Igoristan                           │
   │   → AUTHENTICATED_WITH_MFA                                        │
   └───────────────────────────────────────────────────────────────────┘

Races conditions#

Worker A : min_utc_date_A = 13:27:53.123, génère OTP_A à 13:27:53.250.
Worker B : min_utc_date_B = 13:27:53.130, génère OTP_B à 13:27:53.470.

Sans coordination, A pourrait récupérer OTPB (au lieu de OTP_A) parce que les timestamps sont _très proches (et tronqués à la seconde près).

07.07 — HumanizedDriver

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

07.07 — `HumanizedDriver`#

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

Proxy pattern : wrappe un WebDriver Selenium et intercepte uniquement find_element* pour retourner des WebElement qui font des send_keys humanisés (frappe lente avec typos, hésitations, corrections).

Code#

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

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

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

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

1. Hérite de `WebDriver`#

class HumanizedDriver(WebDriver):

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

08.07 — Gaps spec (G-SPEC-1 à G-SPEC-3)

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

08.07 — Gaps spec (G-SPEC-1 à G-SPEC-3)#

Trois gaps sur le comportement métier vs la spec attendue d’un système de santé.

G-SPEC-1 — History trié par ordre de soumission, pas par date#

Source#

// views/page_history.php
foreach ($_SESSION['history'] as $appointment) {
    // ... render ...
}

Pas de usort. Pas de tri. Aucune étape de tri n’existe nulle part.

appointment.php push avec array_push($_SESSION['history'], $_POST) — append en queue (c’est un pushback).

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 :

10.07 — tests-workers : pas de CI GitHub, déploiement Vercel auto

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

10.07 — `tests-workers` : pas de CI GitHub, déploiement Vercel auto#

Le seul dépôt de l’écosystème sans workflow GitHub Actions. Tout passe par Vercel.

Le contenu du `.github/`#

tests-workers/
└── (aucun .github/ — pas de workflows)

Pas de ci.yml. Pas de deploy.yml. Pas d’action GitHub.

`vercel.json`#

{
  "version": 2,
  "buildCommand": "echo 'No build required'",
  "outputDirectory": ".",
  "framework": null
}

Vercel détecte le projet comme TypeScript Edge Functions, build à la volée (transpile TS au runtime).

12.07 — Le mouvement de fond

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

12.07 — Le mouvement de fond#

Trois trajectoires possibles pour qui était dans la scène hackers 1999-2012 : (1) rester black hat et finir en prison (au mieux), (2) décrocher complètement, (3) se reconstruire seul par la Recherche. Le Holy Book parle de la troisième. C’est de là qu’Ocarina vient.

1. Le passage clé du Holy Book#

De l’Enfer à là où nous en sommes aujourd’hui. Sauvés par la Recherche, par de belles valeurs, par le travail ingrat. Pas celui qui fait briller. Celui transmis par ceux qui savent détecter un potentiel et le sauver avant qu’il ne soit trop tard.

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

02.08 — POMBase

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

02.08 — `POMBase`#

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

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

Code#

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

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

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

Pourquoi deux méthodes#

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

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

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

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

04.08 — Allure + action composite allure-history + déploiement GH Pages

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

04.08 — Allure + action composite `allure-history` + déploiement GH Pages#

Le rapport Allure est généré à chaque CI, historisé sur une branche Git dédiée, puis publié sur GitHub Pages. Live URL : https://mojo-molotov.github.io/ocarina/allure-report/.

Pipeline#

┌────────────────────────────────────────────────────────┐
│ main_ci.yml (push/PR main, ou dispatch)                │
└──────────────────┬─────────────────────────────────────┘
                   ▼
   ┌───────────────────────────────────┐
   │ job : test                        │
   │  - matrix (ubuntu / windows × py) │
   │  - make test (cram + pytest)      │
   │  - upload-artifact allure-results │
   └───────────────┬───────────────────┘
                   ▼
   ┌───────────────────────────────────┐
   │ job : allure-history              │
   │  - download all allure-results    │
   │  - action composite locale :      │
   │       allure-history/action.yml   │
   │  - upload-artifact allure-report  │
   └───────────────┬───────────────────┘
                   ▼
   ┌───────────────────────────────────┐
   │ job : deploy                      │
   │  - download allure-report         │
   │  - prepare pages-root/            │
   │  - actions/upload-pages-artifact  │
   │  - actions/deploy-pages           │
   └───────────────────────────────────┘

`allure-history`#

.github/actions/allure-history/action.yml : action composite locale au repo (uses: ./.github/actions/allure-history).

07.08 — Cache L1 + clés réservées + locks Redis distribués

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

07.08 — Cache L1 + clés réservées + locks Redis distribués#

Mécanique de coordination interne : un cache in-memory pour partager des valeurs au sein d’un test, un lock Redis pour sérialiser un click entre plusieurs workers.

Cache L1#

# src/caches/l1.py
from dogpile.cache import make_region

in_memory_cache_with_30m_ttl = make_region().configure(
    "dogpile.cache.memory", expiration_time=30 * 60
)

Un seul cache, global, dogpile.cache.memory backend, TTL 30 minutes.

Choix « memory » → tout vit en RAM, pas de Redis pour ce cache local.

08.08 — BFCache Chrome (B-BROWSER-1) + artefacts d'environnement

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

08.08 — BFCache Chrome (B-BROWSER-1) + artefacts d’environnement#

Chrome restore une page no-store après logout, depuis le BFCache, alors qu’il s’agit d’une page protégée par authentification.

B-BROWSER-1 — Chrome nous emmerde avec son BFCache#

Symptôme#

Après déconnexion, cliquer sur le bouton “précédent” afin d’être redirigé vers une page qui était protégée par authentification (par exemple : history.php) :

Chrome : la page reste affichée avec son contenu tel qu’il est affiché à un utilisateur encore authentifié. L’URL reste history.php, le serveur n’est pas recontacté pour valider ou invalider l’accès.
Firefox : une nouvelle requête est envoyée au serveur, ce dernier voit que la session est morte, il redirige.

Gap très ennuyeux#

history.php envoie correctement :

09.03.08 — Skill State

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

09.03.08 — Skill State#

Un seul skill : question-state. Interroge l’environnement avant de croire un résultat.

Le skill#

input  : un résultat surprenant (« le test fail »)
output : une série de questions sur l'état :
            - sur quel browser tourne-t-on ?
            - quel commit ?
            - le SUT est-il warm ou cold ?
            - le Redis est-il disponible ?
            - quel est le wait-timeout configuré ?
            - quelle est la version du driver ?
            - le ChromeDriver a-t-il son fix password-manager-off ?
            - est-ce un run isolé ou un run en parallèle ?
            - est-ce que d'autres tests touchent les mêmes ressources SUT ?

Approche#

CLAUDE.md :

12.08 — Ocarina dans l'industrie du test

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

12.08 — Ocarina dans l’industrie du test#

Ocarina n’est pas un meilleur pytest, pas un meilleur Robot Framework, pas un meilleur Cypress. Il est structurellement ailleurs. Ce chapitre essaie d’expliquer le shift qu’il représente, et la longueur d’avance qu’il prend.

1. La cartographie actuelle de l’industrie#

Trois grandes familles d’outils e2e#

Famille	Exemples	Modèle
DSL textuels	Robot Framework, Cucumber + Gherkin	Couche de traduction permanente entre texte et code
Plugins de runner	pytest-selenium, pytest-playwright, pytest-bdd	Greffés sur pytest, héritent de son lifecycle
Vendor SaaS	BrowserStack, Sauce Labs, LambdaTest, Cypress Dashboard	Test runner local + cloud d’exécution payant

Trois grandes surfaces de friction communes#

Friction	Manifestation
Marketing > Technique	Outils vendus sur démos, conferences et certifications orientées. La hype pilote l’adoption.
Vendor lock-in	Une fois adopté, refactor coûteux, prise d’otage.
Effort cognitif déplacé	Comprendre l’outil prend plus de temps que de faire son travail.

2. Le pari technique d’Ocarina#

Pas de DSL textuel → Python pur, embedded DSL.
Pas de plugin pytest → runner intégré, fidélité ISTQB absolue.
Pas d’async/await → simplicité, compatibilité Selenium synchrone, pas de « trucs de geeks ».
Pas de SaaS → tout en local, noyau dur très dense, boîte blanche.

Voir aussi : ../11-independence/03-explicit-refusals.md

02.09 — Ports : ILogger, ITakeScreenshot

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

02.09 — Ports : `ILogger`, `ITakeScreenshot`#

Dossier source : src/ocarina/ports/

Deux ports seulement. C’est tout. Le reste (WebDriversPool, Screenshotter, etc.) vit dans infra/, pas dans ports/. La distinction est claire : un port est une abstraction au-dessus de laquelle vit le DSL ; une infra est l’implémentation des adapters.

`ILogger`#

class ILogger(ABC):
    @abstractmethod
    def set_prefix(self, prefix_thunk: Thunk[str]) -> Self: ...

    @abstractmethod
    def set_domain_taxonomy(self, taxonomy: tuple[str, ...]) -> Self: ...

    @abstractmethod
    def raw(self, *args: object, stream: SupportsWrite[str] | None = None, **kwargs: object) -> None: ...

    @abstractmethod
    def critical(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def error(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def warning(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def info(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def debug(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def test_name(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def success(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def exception(self, msg: str, *args, exc: Exception | None = None, **kwargs) -> None: ...

    @abstractmethod
    def cleanup(self) -> None: ...

Méthode	Sémantique
`set_prefix(thunk)`	Préfixe paresseux appliqué à chaque log (pour timestamps, threads…). Retourne `Self` pour chaining.
`set_domain_taxonomy(taxonomy)`	Définit la hiérarchie de domaine (`(cycle, campaign, suite, test)`). Crucial pour le `FileLogger` qui crée une arborescence de fichiers.
`raw(*args, stream=None)`	Écriture brute, sans format (utilisé par les plugins de rapport).
`critical / error / warning / info / debug`	Niveaux standards. Chaque méthode accepte `exc=` pour passer une exception et la formatter.
`test_name(msg)`	Niveau custom : annonce le test en cours (`logger.test_name(test.name)`).
`success(msg)`	Niveau custom : assertion réussie (utilisé par les `.success(...)` handlers).
`exception(msg, exc=)`	Logue une exception avec traceback complet.
`cleanup()`	Fin de vie : flush + close (pour le `FileLogger`). Recycle le fichier de log entre les retries.

Trois choses qui ne sont pas dans `ILogger`#

Pas de set_level() : le niveau est géré par l’implémentation (ex. MutedLogger filtre tout).
Pas de add_handler() : pas d’API à la logging.Logger du stdlib. La composition se fait par instanciation de loggers différents (PrintAndFileLogger wrappe les deux).
Pas de child(name) : la taxonomy est passée en bloc avec set_domain_taxonomy.

`set_prefix(thunk)`#

logger.set_prefix(lambda: f"[{datetime.now().isoformat()}]")

Si on passait une str, ce serait calculé au moment du set_prefix, donc figé. Avec un Thunk, le préfixe est calculé à chaque appel de log. Idéal pour les timestamps.

07.09 — catch_me_if_you_can

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

07.09 — `catch_me_if_you_can`#

Détecte les éléments parasites qui pop sur la page pendant que le test tourne, et les trace.

Callback#

# src/lib/ext/selenium/watchers/catch_me_if_you_can_watcher.py
def catch_me_if_you_can_cb(watcher: SeleniumWatcher) -> None:
    elements = watcher.driver.execute_script(
        "return Array.from(document.querySelectorAll('.catch-me-if-you-can'));"
    )

    if not elements:
        return

    raw = watcher.driver.execute_script(
        """
        return arguments[0].map(el => ({
            tag:       el.tagName.toLowerCase(),
            text:      el.innerText.trim(),
            id:        el.id,
            cls:       el.className,
            name:      el.getAttribute('name') || '',
            testid:    el.getAttribute('data-testid') || '',
        }));
        """,
        elements,
    )

    for attrs in raw:
        fingerprint = ":".join(
            filter(
                None,
                [
                    attrs["tag"],
                    attrs["text"],
                    attrs["id"],
                    attrs["cls"],
                    attrs["name"],
                    attrs["testid"],
                ],
            )
        )

        if fingerprint in watcher.cache:
            continue

        watcher.cache.add(fingerprint)
        watcher.report(
            f"catch-me-if-you-can element detected: <{attrs['tag']}> {attrs['text']!r}",
            label="CATCH_ME_IF_YOU_CAN",
        )

Mécaniques#

1. Javascript pour bypass implicit wait#

elements = watcher.driver.execute_script(
    "return Array.from(document.querySelectorAll('.catch-me-if-you-can'));"
)

Pas de find_elements(By.CSS_SELECTOR, ...).

08.09 — CI : ai_proof_ci.yml + ai_proof_e2e.yml

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

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

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

`ai_proof_ci.yml`#

name: ai_proof CI

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

defaults:
  run:
    shell: bash

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

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

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

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

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

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

`ai_proof_e2e.yml`#

name: ai_proof e2e

on:
  workflow_dispatch:

defaults:
  run:
    shell: bash

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

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

      # --- Firefox ---

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

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

      # --- Chrome ---

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

      # --- Warm-up ---

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

      # --- Run ---

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

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

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

      # … upload logs, reports similar ...

Analyse#

`fail-fast: false`#

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

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

09.03.09 — Skills Setup

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

09.03.09 — Skills Setup#

Deux skills : setup-environment (onboarding d’un nouveau contributeur, humain ou IA) et profile-environment (cadre la latitude laissée à l’IA pour une mission donnée). Tous deux alimentent le CLAUDE.md assemblé de la suite.

Le skill#

input  : un repo frais
output : étapes d'onboarding :
            1. venv
            2. pip install (deps dev + ocarina)
            3. ruff / mypy / pre-commit installés
            4. CLAUDE.local.md créé (avec demande paths à l'utilisateur)
            5. smoke-check du runner (un test minimal qui valide que tout marche)
            6. boucle pré-commit testée

Étape 1 : venv#

python -m venv .venv
source .venv/bin/activate

Étape 2 : pip install#

pip install . ruff mypy mypy-extensions typing-extensions pre-commit

Étape 3 : outillage de dev#

pre-commit install --config .pre-commit-config.yaml

Étape 4 : `CLAUDE.local.md`#

CLAUDE.local.md est gitignored et contient les paths machine-specifiques.

12.09 — Cohérence de l'écosystème

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

12.09 — Cohérence de l’écosystème#

Six dépôts, plusieurs langages, plusieurs technologies, plusieurs licences, plusieurs plateformes de déploiement. À première vue, hétérogène. À deuxième lecture, rigoureusement cohérent : chaque pièce sert exactement le même pari.

1. Vue d’ensemble : six dépôts, une éthique#

┌────────────────────────────────────────────────────────────────────────┐
│         L'ÉCOSYSTÈME COMME UN TOUT COHÉRENT                            │
└────────────────────────────────────────────────────────────────────────┘

  ┌──────────────┐    Le framework. ROP, types stricts, refus de plugin
  │   ocarina    │    pytest. UNE seule dep d'exécution. Auditable en
  └─────────────┬┘    une après-midi. — PROUVE que la rigueur est légère.
                │
                │
                ▼
  ┌─────────────────┐ La référence d'usage. Adapters projet. Patterns
  │ ocarina-example │ canoniques. Démontre comment on rétrécit la surface
  └─────────────┬───┘ d'API du framework pour son contexte. — PROUVE que
                │     le framework est utilisable « par n'importe qui ».
                │
                ▼
  ┌─────────────────────────┐ Le pari IA. Co-écrit par Claude 99%. CURA
  │ ocarina-with-ai-example │ Healthcheck comme SUT. Findings sourcés jusqu'au PHP.
  └─────────────┬───────────┘ — PROUVE que l'IA + Ocarina peut faire un
                │               vrai travail de testeur senior.
                ▼
       ┌──────────────┐ Le SUT volontairement chaotique. Le terrain.
       │  igoristan   │ — PROUVE qu'on peut tester une appli pathologique
       └────────┬─────┘   sans tricher.
                │
                ▼
       ┌────────────────┐ Le backend de coordination. Vercel Edge,
       │ tests-workers  │ Upstash Redis, anti-précision volontaire.
       └────────┬───────┘ — PROUVE qu'on peut faire de la coordination
                │           distribuée sans plateforme propriétaire.
                │
                ▼
       ┌───────────────────┐ La documentation publique. VitePress + FR/EN/RU
       │ ocarina-holy-book │ + LLM-first (llms.txt, CLAUDE.md, skills).
       └───────────────────┘ — PROUVE qu'on peut écrire de la doc qui sert
                               humain ET IA, sans plateforme tierce.

2. Un dépôt = un type de défi#

Dépôt	Type de défi	Pari prouvé
`ocarina`	Construire un framework petit et profond	« La rigueur n’est pas une usine à gaz »
`ocarina-example`	Démontrer un usage canonique	« Tu peux vraiment écrire des tests rigoureux comme ça »
`ocarina-with-ai-example`	Faire collaborer un humain et une IA	« L’IA est le pont, pas le DSL »
`igoristan`	Bâtir un SUT chaotique	« Pas de démo sur un site qui fait vingt lignes d’HTML, une démo sur un vrai bordel »
`tests-workers`	Être le substrat par lequel les tests se coordonnent	« On peut être stateless côté code »
`ocarina-holy-book`	Documenter pour humains et IA	« La documentation est avant tout de la donnée brute pour les LLMs »

Si on enlève l’un de ces dépôts, l’écosystème perd un argument.
Les six sont solidaires.

07.10 — EnvGetters

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

07.10 — `EnvGetters`#

Accesseur typé aux variables d’environnement. Évite les typos, refuse les clés inconnues à la compilation, apporte l’autocomplétion dans l’IDE.

Code#

# src/lib/ext/ocarina/adapters/agnostic/env_getters.py
from typing import Literal
from types import MappingProxyType
from ocarina.opinionated.infra.env import EnvGetters, Effects

type _CredsKeys = Literal["dashboard"]
type _ValuesKeys = Literal["igor_api_key", "redis_url"]


def _load_env() -> None:
    from dotenv import load_dotenv
    load_dotenv()


_DEFAULT_EFFECTS = (_load_env,)


class _EnvGetters(EnvGetters[_CredsKeys, _ValuesKeys]):
    def __init__(self, *, effects: Effects) -> None:
        for effect in effects:
            effect()
        super().__init__(
            credentials={
                "dashboard": MappingProxyType({
                    "login": os.environ["DASH_USERNAME"],
                    "password": os.environ["DASH_PASSWORD"],
                }),
            },
            values={
                "igor_api_key": os.environ["IGOR_API_KEY"],
                "redis_url": os.environ["REDIS_URL"],
            },
        )


def create_env_getters(*, effects: Effects | None = None) -> _EnvGetters:
    if effects is None:
        effects = _DEFAULT_EFFECTS
    return _EnvGetters(effects=effects)

`_CredsKeys` et `_ValuesKeys`#

type _CredsKeys = Literal["dashboard"]
type _ValuesKeys = Literal["igor_api_key", "redis_url"]

Credentials : paires login/password (dict immutable via MappingProxyType).
Values : valeurs brutes.

`MappingProxyType`#

"dashboard": MappingProxyType({
    "login": os.environ["DASH_USERNAME"],
    "password": os.environ["DASH_PASSWORD"],
}),

MappingProxyType est un wrapper read-only autour d’un dict :

09.03.10 — Skills Run

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

09.03.10 — Skills Run#

Faire remonter les choix à trancher avant un lancement local, composer la commande, et la rendre. Le skill ne lance jamais l’exécution lui-même.

Listing (potentiellement non exhaustif)#

Skill	Cible
`propose-visual-review`	Propose fenêtré (`--not-headless`) vs headless (façon CI) avant une exécution, puis compose la commande

`propose-visual-review`#

input  : une exécution locale à venir
output : le choix fenêtré vs headless :
            - --not-headless : on regarde le navigateur, utile pour déboguer un flux flaky
            - headless (façon CI) : plus rapide, identique à ce que fait la CI
         + le compromis et ce qu'il faut surveiller pendant une exécution fenêtrée
         + la commande composée, rendue à l'utilisateur pour qu'il la lance

Rôle#

Faire remonter le choix d’avant-exécution ; expliquer le compromis.
Composer la commande.
Ne pas la lancer : c’est l’utilisateur qui exécute.

12.10 — Infopreneurs, Tugan Bara, IA

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

12.10 — Infopreneurs, Tugan Bara, IA#

L’écosystème opposé à Ocarina. Pas un autre framework de test : un autre modèle culturel. Il faut nommer ce que combat le Holy Book pour comprendre pourquoi il combat. Et pourquoi l’IA est en train de tuer ce modèle.

1. Qu’est-ce que l’« infopreneuriat »#

Définition#

Infopreneur = entrepreneur dont le produit est de l’information vendue : formations en ligne, programmes de coaching, e-books, masterminds, abonnements à une « newsletter premium ». Le produit n’est pas physique.

07.11 — CI

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

07.11 — CI#

Trois workflows : main_ci.yml (rapide, lint + typecheck), dev_ci.yml (idem pour branches dev/feature/fix), e2e.yml (manuel, service Redis + Firefox).

Vue d’ensemble#

Workflow	Trigger	Plateforme	Effet
`main_ci.yml`	push/PR main	ubuntu + windows × py 3.14	`make check-coding-style` (mypy + ruff). Pas de browser.
`dev_ci.yml`	push dev / feature/_ / fix/_	ubuntu × py 3.14	id., mais Ubuntu seul
`e2e.yml`	`workflow_dispatch` (manuel)	ubuntu + service Redis + Firefox + geckodriver	Run complet de la suite e2e. Upload `.screenshots/`, `.ocarina_logs/`, `.reports/`.

`main_ci.yml`#

name: Main branch CI

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

defaults:
  run:
    shell: bash

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        python-version: ["3.14"]
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-python@v6
        with: { python-version: "3.14" }
      - uses: actions/cache@v5
        with:
          path: .venv
          key: venv-${{ runner.os }}-py3.14-${{ hashFiles('pyproject.toml') }}
      - name: Install
        run: make install-on-ci
      - name: Check coding style
        run: |
          . .venv/bin/activate
          make check-coding-style

Matrice OS : ubuntu + windows. Vérifie la portabilité Python du code projet.
Pas de browser : on lance juste make check-coding-style (= mypy + ruff). Rapide, pas besoin de Selenium / Redis / OTP.
Cache .venv : reuse entre runs.

`dev_ci.yml`#

on:
  push:
    branches: [dev, "feature/**", "fix/**"]
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    # … identique à main_ci.yml, juste Ubuntu seul …

Identique au main_ci.yml mais Ubuntu seul (Windows ne run que sur main).

12.11 — L'industrie SaaS, la fraude à l'ARR, jeu de dupes

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

12.11 — L’industrie SaaS, la fraude à l’ARR, jeu de dupes#

Ocarina rejette le SaaS. L’industrie du SaaS est un écosystème circulaire où chaque outil vend à chaque autre outil, où le revenu déclaré est gonflé par convention, et où chaque étage de la chaîne capitalistique (LP, VC, founder) entretient sciemment une plausible deniability pour pouvoir attaquer les autres en justice le moment venu.

1. Le SaaS contemporain#

Couche	Fournisseurs (échantillon)	Modèle
Hosting & CDN	Vercel, Netlify, Cloudflare, Fly.io, Render	Abonnement par projet / par bandwidth
DB	Supabase, Neon, PlanetScale, Upstash, MongoDB Atlas	Abonnement par compute / par GB
Auth	Clerk, Auth0, WorkOS, Stytch	Abonnement par MAU
Mail	Resend, SendGrid, Postmark, Mailgun	Abonnement par mail envoyé
Analytics	PostHog, Mixpanel, Amplitude, Plausible, Vercel Analytics	Abonnement par event
Error tracking	Sentry, BugSnag, Rollbar, Highlight	Abonnement par event
Observability	Datadog, New Relic, Honeycomb, Grafana Cloud, Axiom	Abonnement par metric volume
Feature flags	LaunchDarkly, GrowthBook, Statsig, ConfigCat	Abonnement par MAU
Test e2e	BrowserStack, Sauce Labs, LambdaTest, Cypress Dashboard	Abonnement par run / par parallel
CI	GitHub Actions, CircleCI, Buildkite, Vercel CI	Abonnement par minute
Code review	Graphite, Codeball, CodeRabbit, Sourcery	Abonnement par PR / par dev
Comms internes	Slack, Linear, Notion, Figma, Loom, Pitch	Abonnement par seat
Billing	Stripe, Lago, Orb, Metronome	% du revenu traité
CRM	HubSpot, Salesforce, Attio, Pipedrive	Abonnement par seat
Support	Intercom, Zendesk, Plain, Help Scout	Abonnement par seat + par message
AI tooling	OpenAI, Anthropic, Cursor, Vercel AI SDK, Replicate	Abonnement par token + par seat

2. Abonnements croisés#

   ┌──────────┐ paie     ┌──────────┐
   │ Vercel   │─────────>│ Stripe   │
   │          │<─────────│          │
   └──────────┘     paie └──────────┘
        │                     │
   paie │                     │ paie
        v                     v
   ┌──────────┐          ┌──────────┐
   │ Linear   │<────────>│ Notion   │
   └──────────┘  paient  └──────────┘
        │                     │
        v                     v
   ┌───────────────────────────────┐
   │ Slack, Figma, Loom, Sentry,   │
   │ Datadog, Clerk, Cursor, …     │
   │ tous abonnés à tous           │
   └───────────────────────────────┘

Vercel paie un abonnement à Stripe (billing), Datadog (obs), Linear (planning), Figma (design), Loom (présentations internes), Slack (comms), Notion (docs).
Stripe paie un abonnement à Vercel (hosting pour ses dashboards), Linear, Figma, Slack…
Linear paie un abonnement à Vercel, Stripe, Notion, Figma, Slack.
Notion paie un abonnement à Linear, Stripe, Slack, Figma.

Et ainsi de suite. Tout le monde paie tout le monde.

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

12.12 — DHH, Paul Graham, Haters, Mean People Fail

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

12.12 — DHH, Paul Graham, Haters, Mean People Fail#

Le Holy Book cite deux grands noms : David Heinemeier Hansson (DHH) et Paul Graham (pg). Ces deux auteurs ne sont pas cités au hasard, chacun incarne une posture rhétorique précise. Ce fichier explique qui ils sont, ce qu’ils ont écrit, et pourquoi l’essai Haters de Paul Graham (et son frère cadet Mean People Fail) sont le précédent intellectuel direct du chapitre « Premiers retours ».

12.13 — Lambda-calcul, ROP, Haskell / F# / OCaml, monades

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

12.13 — Lambda-calcul, ROP, Haskell / F# / OCaml, monades#

Ocarina n’invente rien sur le plan théorique. Il applique : du lambda-calcul d’Alonzo Church (1936) aux monades d’Eugenio Moggi (1989) et Philip Wadler (1992-95), formalisé en tant que Railway Oriented Programming par Scott Wlaschin (2014).

1. Lambda-calcul (Church, 1936)#

Définition#

Le lambda-calcul (λ-calcul) est un système formel inventé par Alonzo Church (1903-1995) pour étudier la calculabilité.

12.14 — L'IA, et comment Ocarina l'applique pour de vrai

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

12.14 — L’IA, et comment Ocarina l’applique pour de vrai#

« AI-powered » est devenu en 2023-2026 un slogan marketing complètement débile : 99 % des produits qui le revendiquent enrichissent un produit existant avec un endpoint chat.completions. Ocarina propose, à l’opposé, une infrastructure logicielle pensée pour qu’une IA puisse contribuer comme un développeur senior. ocarina-with-ai-example étant la preuve par l’exemple.

1. Ce qu’est l’IA aujourd’hui#

Couche	Exemple	Date d’apparition
Statistical learning	Régression, k-means, decision trees	1960s-1990s
Deep learning	CNN (vision), RNN/LSTM (texte)	2012 (AlexNet — adoption mainstream)
Transformer-based foundation models	GPT, Claude, Gemini, Llama	2017 (papier), 2018 (BERT), 2022 (ChatGPT)
Workflows agentiques	AutoGPT, LangChain, Claude Code, Cursor agents	2023+

Note : le CNN est inventé par Yann LeCun dès 1989 (MNIST). AlexNet (Krizhevsky, Sutskever, Hinton, Toronto, 2012) en est la percée industrielle. LeCun, Hinton et Bengio partagent le Turing Award 2018 pour leurs contributions fondatrices au deep learning.

12.15 — Typage, ISTQB, Reinforcement Learning, probes : pourquoi l'IA marche dans Ocarina

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

12.15 — Typage, ISTQB, Reinforcement Learning, probes : pourquoi l’IA marche dans Ocarina#

Pourquoi tant d’obsession pour le typage strict, la formalisation de chaque interface, l’alignement sur l’ISTQB, le refus d’exécuter une assertion sans avoir observé ? Le mécanisme est emprunté au Reinforcement Learning : un agent ne progresse que sous contrainte + signal de récompense.

1. Un LLM nu n’est qu’un mauvais collaborateur#

Un LLM sans environnement structuré est :

12.16 — L'internet souterrain des années 1995-2010 : forums, outils, banalisation de la cruauté

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

12.16 — L’internet souterrain des années 1995-2010 : forums, outils, banalisation de la cruauté#

Pour comprendre la rage qui traverse le Holy Book d’Ocarina, il faut comprendre ce qu’était vraiment internet avant Facebook (2006-2008), avant que Cloudflare ne devienne le gardien des portes (2010+), avant que la modération ne soit prise au sérieux. C’était un Far West où des compétences étatiques se développaient dans des chambres d’adolescents, où la vie privée d’un adversaire pouvait être démolie en 48 heures, et où les recours juridiques classiques étaient inopérants. Cette page décrit la mécanique, sans complaisance, sans héroïsation.

12.17 — La psyché du survivant : « ennemis », « narcissisme », « enfer », « survie », et comment ça remonte jusque dans le code

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

12.17 — La psyché du survivant : « ennemis », « narcissisme », « enfer », « survie », et comment ça remonte jusque dans le code#

L’auteur du Holy Book d’Ocarina utilise des mots forts : ennemis, narcissisme, enfer sur terre, survie. Ces mots ne sont pas des effets de style. Ce sont les descripteurs précis d’une expérience vécue par toute une cohorte qui a traversé l’internet souterrain 2000s décrit dans 16-underground-internet-2000s.md. Cette page explique pourquoi ces mots sont exacts, ce que produit ce vécu sur la psyché, et comment ces adaptations psychologiques s’inscrivent profondément dans la façon de programmer, d’architecturer, de toujours se tenir à jour.

12.18 — « Vilains but not Monsters », DEF CON, « live as a white hat or die as a black hat », et l'idéologie d'Ocarina

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

12.18 — « Vilains but not Monsters », DEF CON, « live as a white hat or die as a black hat », et l’idéologie d’Ocarina#

Ocarina n’est ni une lubie esthétique ni un OVNI hors-sol. C’est l’expression technique d’une idéologie cohérente héritée du mouvement hacker : l’éthique Vilain, mais pas un monstre, la culture tribale des conférences (DEF CON en tête), et la devise de YTCracker prononcée sur scène : « live as a white hat, or die as a black hat ».

12.19 — It's over

Sun, 31 May 2026 00:00:00 +0000

12.19 — It’s over#

Je n’écris pas du code « qui implémente des specs ».
J’écris du code avec une âme.
Du vrai code de passionné. Tu sais ce que ça veut dire ? Pendant que toi, tu prends ça de haut, que tu nous traites d’autistes ?

On ne demande rien, si ce n’est du respect et qu’on nous laisse travailler normalement.
La situation actuelle de l’informatique est épuisante.

Ocarina — précis

00.01 — Cartographie de l'écosystème

00.01 — Cartographie de l’écosystème#

Schéma d’ensemble (big picture)#

Responsabilités#

Trois licences#

Points de friction volontaires entre dépôts#

01.01 — Prendre le problème à l'envers

01.01 — Prendre le problème à l’envers#

Le constat#

02.01 — Identité technique d'Ocarina

02.01 — Identité technique d’Ocarina#

pyproject.toml#

Dépendances dev#

mypy.ini#

pyproject.toml#tool.ruff#

pyproject.toml#tool.pytest.ini_options#

pyproject.toml#tool.coverage#

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#

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

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

Triplet#

Distinction Effect vs Thunk#

04.01 — Stratégie « dehors comme un utilisateur »

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

tests/scenarios/conftest.py#

FakeDriver#

05.01 — Stack de l'Igoristan

05.01 — Stack de l’Igoristan#

package.json#

devDependencies#

engines#

06.01 — Stack Vercel Edge

06.01 — Stack Vercel Edge#

package.json#

07.01 — Arborescence

07.01 — Arborescence#

Sémantique des dossiers#

lib/ vs pages/#

08.01 — Code : 99% Claude, 1% Igor, intelligence : 50-50

08.01 — Code : 99% Claude, 1% Igor, intelligence : 50-50#

README#

A note to the reader#

09.01 — Stack VitePress + Sugar Theme + plugins maison

09.01 — Stack VitePress + Sugar Theme + plugins maison#

package.json#

docs/.vitepress/config.mts#

1. base#

09.03.01 — Skills Review

09.03.01 — Skills Review#

Listing (potentiellement non exhaustif)#

review-dead-code#

review-report#

review-watcher-misuse#

review-comment-drift#

10.01 — Matrice récapitulative des workflows

10.01 — Matrice récapitulative des workflows#

Récap.#

Action composite#

`pyproject.toml`#

Dépendances `dev`#

`mypy.ini`#

`pyproject.toml#tool.ruff`#

`pyproject.toml#tool.pytest.ini_options`#

`pyproject.toml#tool.coverage`#

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

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

`tests/scenarios/conftest.py`#

`FakeDriver`#

`package.json`#

`devDependencies`#

`engines`#

`package.json`#

`lib/` vs `pages/`#

`package.json`#

`docs/.vitepress/config.mts`#

1. `base`#

`review-dead-code`#

`review-report`#

`review-watcher-misuse`#

`review-comment-drift`#

02.02 — Arborescence du module `ocarina`#

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

04.02 — Cram tests (`prysk`)#

Fichier `.t`#

`src/config/routes.ts`#

06.02 — `GET /api/otp`#