Chapter 07 — ocarina-example, the canonical suite

20 May 2026

Chapter 07 — `ocarina-example`#

E2E suite designed to test Igoristan. The reference example: every Ocarina project starts by reading this repo and copying its adapters.

#	File	Topic
01	`01-tree.md`	The full `src/` tree: pages/, lib/, api/, caches/, constants/, tests/.
02	`02-adapters.md`	The 5 adapters (`act`, `match_page`, `TestSuite`, `TestCampaign`, `EnvGetters`).
03	`03-scenarios-login.md`	Dashboard login scenarios: happy / unhappy / data-driven.
04	`04-scenarios-corsicamon.md`	Corsicamon scenarios: api_key, draw, add, back.
05	`05-scenarios-randomness.md`	Randomness scenarios (4 levels): random_error, random_loaders, dsed, madness, chaotic_form, walkthrough.
06	`06-scenarios-sacred-upload.md`	Sacred upload scenarios: upload_files, back_to_igoristan.
07	`07-humanized-driver.md`	`HumanizedDriver`: Selenium proxy to simulate human typing.
08	`08-caches-locks.md`	L1 cache (`dogpile.cache.memory`) + reserved keys + distributed Redis locks.
09	`09-watcher-catch-me.md`	The `catch_me_if_you_can` watcher for the chaotic form.
10	`10-env-getters.md`	`EnvGetters[_CredsKeys, _ValuesKeys]` strictly typed via `Literal`.
11	`11-ci.md`	CI: `main_ci.yml` + `dev_ci.yml` (lint+typecheck) + `e2e.yml` (Redis + manual Firefox).

Holy Book quote (chapter “First steps”):

20 May 2026

Ocarina’s shape layer. No logic — types, aliases, exceptions, protocols. What makes the DSL typed without adding runtime logic.

File	Contents
`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]`

All these files are excluded from coverage (pyproject.toml#tool.coverage):