Big-Picture on Ocarina — manual

00.01 — Ecosystem cartography

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

00.01 — Ecosystem cartography#

The Ocarina ecosystem is six public repos under the mojo-molotov GitHub account. They cover five distinct roles:

Role	Repo	Form
Framework	`ocarina`	Python library on PyPI
Public System Under Test (SUT)	`igoristan`	React + Vike SPA, GitHub Pages
Coordination backend	`tests-workers`	Vercel Edge API + Upstash Redis
Example suites	`ocarina-example` (canonical), `ocarina-with-ai-example` (AI)	Python e2e suites driving Igoristan / CURA
Public documentation	`ocarina-holy-book`	VitePress site (EN + FR + RU), PDFs, AI skills

The big picture#

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

   ┌──────────────────────────────┐         ┌──────────────────────────────────┐
   │  [PACKAGE]  ocarina          │ ──────► │  [PACKAGE]  ocarina-example      │
   │  Python framework 3.14+      │   pip   │  e2e suite against the Igoristan │
   │  ROP / DSL / orchestration   │ install │  (Selenium + Firefox + Redis)    │
   └──────────────────────────────┘         └──────────────────────────────────┘
            │  │                                       │  ▲   │
            │  │                                       │  │  uses
            │  │ pip install ocarina                   │  │  IGOR_API_KEY
            │  ▼                                       ▼  │   │
            │  ┌────────────────────────────────────┐  drives │
            │  │ [PACKAGE]  ocarina-with-ai-example │  ┌──────┴──────────────────┐
            │  │ e2e suite against CURA Healthcare  │  │ [WEBSITE]  igoristan    │
            │  │ Claude Code, 99% machine-written   │  │ React 19 + Vike         │
            │  └────────────────────────────────────┘  │ GitHub Pages            │
            │              │                           └──────┬──────────────────┘
            │              │ drives                           │ fetches OTP
            │              ▼                                  ▼
            │   ┌──────────────────────────────┐    ┌──────────────────────────────┐
            │   │ [WEBSITE]  CURA Healthcare   │    │ [BACKEND]  tests-workers     │
            │   │ Heroku, open-source PHP      │    │ Vercel Edge Functions        │
            │   └──────────────────────────────┘    │ + Upstash Redis              │
            │                                       │ /api/otp, /otp-history,      │
            │                                       │ /api/corsicadex              │
            │                                       └──────────────────────────────┘
            │                                                 ▲
            │                                                 │ x-api-key
            │                                                 │ (IGOR_API_KEY ≡ API_SECRET)
            │                                                 │
            ▼
   ┌──────────────────────────────┐
   │  [DOCS]  ocarina-holy-book   │
   │  VitePress EN + FR + RU      │
   │  AI skills, PDFs, llms.txt   │
   │  GitHub Pages                │
   └──────────────────────────────┘

ocarina → example suites: plain pip dependency (pip install ocarina).
Example suites → SUT (Igoristan / CURA): browser automation through Selenium.
Igoristan suite ↔ tests-workers: HTTP calls (OTP, Corsicadex). Shared secret: IGOR_API_KEY client-side ≡ API_SECRET server-side.

Responsibilities#

Role	Contract	Constraint
Framework	Ships the DSL, the orchestration, the driver pool, the reporters	Stays small, auditable, no hidden deps
Public SUT	A deliberately chaotic playground (random errors, OTP, finicky forms)	Lives on GitHub Pages forever, no heavy backend
Coordination backend	Coordinates workers on OTP, surfaces data for parallel tests	Stateless code, state in Redis (Upstash)
Example suites	Show how Ocarina actually gets used — without AI (canonical) and with AI (CURA)	Public, runnable, complete, in CI
Documentation	The why, the how, and the AI part	EN + FR + RU (Corso-Russian tradition), LLM-friendly files like `llms.txt`, plus PDFs

Three licenses#

License	Where	Why
MIT	`ocarina`, `ocarina-example`, `ocarina-with-ai-example`, `ocarina-holy-book`	Python code or docs. Transmissible as-is. Sovereign. See `../11-independence/`.
ISC	`tests-workers`	Vercel Edge scaffold default. Kept as-is.
(unlicensed)	`igoristan`	Public demo app. Treat it as WTFPL.

Deliberate friction between repos#

The design is intentionally asymmetric along certain axes. The friction is the testing tool:

00.02 — Stack / responsibility / license matrix

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

00.02 — Stack / responsibility / license matrix#

Repository	Role	Language	Version	Primary stack	Tooling stack	Distribution	License
`ocarina`	Browser e2e test framework	Python	3.14+	`hatchling`, `python-docx` (sole runtime dependency), `selenium` + `playwright` (dev only)	`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`	Canonical e2e suite against the Igoristan	Python	3.14+	`ocarina`, `selenium ≥ 4.40`, `python-dotenv`, `dogpile.cache`, `redis`	`ruff`, `mypy`, `pre-commit`	Source only	MIT
`ocarina-with-ai-example`	e2e suite against CURA Healthcare, co-written with Claude Code	Python	3.14+	`ocarina ≥ 1.0.3`, `selenium ≥ 4.40`	`ruff`, `mypy`, `mypy-extensions`, `typing-extensions`, `pre-commit`	Source only	MIT
`igoristan`	Public SUT, deliberately chaotic web app	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` (orchestrator), `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/`)	none
`tests-workers`	OTP / Corsicadex backend, the substrate that exercises parallelization and API tests	TypeScript	5.9.3	Vercel Edge Functions (`runtime: "edge"`), `@upstash/redis`, `otplib`, `next` types (`NextRequest`)	`pnpm 11.x`, `@vercel/node` (types)	Vercel: `https://tests-workers.vercel.app`	ISC
`ocarina-holy-book`	Public documentation + AI skills + PDFs	TypeScript	6.0.x	VitePress 2 alpha, `@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#

Python 3.12+ feature	Use in Ocarina
PEP 695 (`class Foo[T]:`)	Generic signatures everywhere (`TestSuite[Driver]`, `Watcher[Driver]`, `Test[Driver]`, `Result[T]`, `Ok[T]`, `Thunk[T]`, etc.)
PEP 695 type aliases (`type X = ...`)	Every 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+)	Fluent returns from POMs, loggers, invariants
`@final` (3.8+)	Locks critical classes (`Watcher`, `Test`, `TestCycle`, `ChainRunner`, `Ok`, `Fail`, …)
`Unpack` (3.11+)	`HumanizedDriver` signature in `ocarina-example`
`Protocol` (3.8+)	`ScreenshotDriver`, `SupportsWrite[str]`
`Literal` (3.8+)	All enums (`SeleniumCliStoreKeys`, `LOGGERS_CHOICES`, `Mode`)
`Never` (3.11+)	`_SilentArgumentParser.error` signature

Practical consequence: there is a dedicated CI workflow unstable_python_full_build.yml that pushes Python 3.15-dev monthly (cron: "0 3 1 * *"), because Ocarina aims to be ready for the next interpreter as soon as it ships. See ../10-cicd/02-ocarina-workflows.md

00.03 — End-to-end execution flow of an e2e campaign

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

00.03 — End-to-end execution flow of an e2e campaign#

Run python -u src/main.py … on either suite (ocarina-example or ocarina-with-ai-example) and this chain kicks off:

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 external dependencies
           - 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) on 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()                  (optional)
              │                             ├─ watchers.start()         (daemon threads)
              │                             ├─ chain_runners            (Railway DSL)
              │                             ├─ watchers.stop()
              │                             └─ teardown()               (always)
              ├─ campaigns (main)
              │  (skipped if a smoke failed)
              │
SUT   ────────┼────────────────────────────────────────────────────────────
              │
              ▼
       Selenium WebDriver ⇄ real browser
       sometimes: OTP HTTP GET + Redis (on the ocarina-example side)
              │
              ▼
       (6) run_plugins(results)
              ├─ generate_docx_proof  (reads the log tree, builds .docx files)
              ├─ generate_json_results (serializes results to .json)
              ├─ others if declared (parallelized via ThreadPoolExecutor)
              │
              ▼
       (6') post_exec(results)
              ├─ pretty_print_results (ANSI, hierarchical)
              └─ has_test_cycle_failed → sys.exit(1) if applicable

Step-by-step#

(1) Parse CLI#

create_selenium_auto_cli_store() detects the OS via platform.system():

00.04 — Relations between the six repositories

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

00.04 — Relations between the six repositories#

Every edge of the graph is a contract — a secret, a URL, a payload type, or a version. One pair per section below.

`ocarina` ↔ `ocarina-example`#

Direction	Mechanism
`ocarina` → `ocarina-example`	`pip install ocarina` from PyPI
`ocarina-example` → `ocarina`	None (the example pushes nothing)

The example writes its own adapters on top of the framework:

lib/ext/ocarina/adapters/agnostic/act.py → adds an on_failure hook that turns an HTTP error page (title matched by ERROR_PAGE_REGEX) into 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 → pins max_retries_per_test=8, transient_errors=..., autoscreen_on_fail=True, propagates --only/--exclude.
lib/ext/ocarina/adapters/selenium/test_campaign.py → pins max_workers=get_max_workers().

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

pip install . ruff mypy mypy-extensions typing-extensions pre-commit — the AI example pins its dep in pyproject.toml: ocarina>=1.0.3.
act adapter is minimal here. No on_failure (CURA doesn’t throw deliberately random HTTP error pages). See ../08-ai-example/
create_drivers_pool adapter is overridden to build a clean Chrome (password manager off, leak detection off). See ../08-ai-example/06-data-gaps.md

`ocarina-example` ↔ `igoristan`#

Direction	Contract	Detail
`ocarina-example` → `igoristan`	Public URLs	Everything goes through `https://mojo-molotov.github.io/igoristan/<route>`
`igoristan` → `ocarina-example`	none (the SUT doesn’t know it’s being tested)	—

src/constants/pages/:

Big-Picture on Ocarina — manual

00.01 — Ecosystem cartography

00.01 — Ecosystem cartography#

The big picture#

Responsibilities#

Three licenses#

Deliberate friction between repos#

00.02 — Stack / responsibility / license matrix

00.02 — Stack / responsibility / license matrix#

Python early adopter#

00.03 — End-to-end execution flow of an e2e campaign

00.03 — End-to-end execution flow of an e2e campaign#

Step-by-step#

(1) Parse CLI#

00.04 — Relations between the six repositories

00.04 — Relations between the six repositories#

ocarina ↔ ocarina-example#

ocarina ↔ ocarina-with-ai-example#

ocarina-example ↔ igoristan#

`ocarina` ↔ `ocarina-example`#

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

`ocarina-example` ↔ `igoristan`#