08.03 — Documentation#

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

Listing#

CLAUDE.md#

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

gh api repos/katalon-studio/katalon-demo-cura/contents/<file>.php --jq '.content' | base64 -d

→ Pas d’inférence. C’est à l’humain d’être « assertif ».

« Inspect the SUT for security / spec gaps »#

This is the encouraged use of source inspection.

→ Lecture du code encouragée pour trouver des gaps.

« Security testing is functional and static — never active »#

Forbidden, no exceptions:

• Crafted attack payloads of any kind: SQL injection strings, XSS / HTML / JS payloads, command injection, header/parameter pollution, path traversal, deserialisation payloads.
• Token tampering, signature stripping, cookie forgery, session-fixation attempts, forced-browsing fuzzers.
• Cross-origin POSTs constructed outside the suite, scripted directory enumeration, DOS, rate-floods.

→ Tests de sécurité fonctionnels uniquement (« utiliser l’app comme un utilisateur »), jamais actifs (« attaquer l’app comme un adversaire [acteur malveillant] »).

« Throwaway probes — when source-reading and the suite don’t agree »#

A probe is a one-off script that drives the browser (or raw HTTP) through a suspect flow and prints concrete runtime state. It bypasses the Ocarina workflow entirely — no create_selenium_test, no suites, no campaigns, no assertions. Probes live in a gitignored directory, are never committed or pushed, and are deleted once the answer lands in a durable artifact.

→ On peut écrire un script jetable pour explorer, mais on ne le commit jamais. Une trouvaille atterrit dans un artefact (gap, SFD update, test).

« A probe must exercise the exact target the code under test will use »#

“Exact target” means all of: exact locator, exact screen / page state, exact wait condition, exact action.

→ Une sonde sur autre chose ne prouve rien pour ce qui est à tester : c’est de l’empirisme. On fait et on refait.

« Probe sequences vs ritual workarounds — multi-action “dances” »#

Probe sequence (legitimate). The dance is the test. Ritual workaround (not legitimate). Glue around a hypothesis about SUT behaviour.

→ Une séquence d’actions peut être le test ou une solution de contournement. Si on enlève une étape et que le test change ce qu’il teste → sonde. Sinon (juste « pour que ça marche ») → solution de contournement à éliminer.

« A cross-browser behavioural difference is a finding, not a test to route around »#

Never skip a test on the browser where it fails.

→ Si un test fail sur Chrome mais passe sur Firefox → il s’agit d’une trouvaille, à documenter et à garder en tant que test en échec sur Chrome. Pas à skipper.

« Functional testing simulates a real human — ask “would a real person hit this?” »#

Every test here stands in for a person clicking through CURA in a browser.

→ Un test automatisé = une simulation du parcours d’un humain. Si le test échoue mais qu’un humain réussirait dans les mêmes conditions → le problème vient du test. Sinon → c’est une anomalie.

« Confirming a back-forward-cache exposure — the back-then-reload check »#

→ Recette précise pour confirmer un problème avec le BFCache : back() puis refresh() ; si back() affiche une page qu’il ne devrait pas, sans redirection, mais qu’on est tout de même redirigé après un refresh() → BFCache hit, anomalie.

« Scenario file structure »#

One scenario per file. (…) Top docstring gives the flow as arrows. A reader must know exactly what the file exercises before reading any code.

→ Discipline de structure. Un docstring en flèches (open → fill → submit → verify) en haut de chaque fichier de test. Un fichier de test par scénario de test.

« POM selectors live at the top of the class »#

→ Tous les sélecteurs sont groupés en haut de leur POM respectif. On ne les disperse pas.

« Always use WebDriverWait — never raw find_element »#

→ Tableau précis de quel expected_conditions utiliser pour quel cas avec Selenium.
Ne pas utiliser find_element directement.

« Widget-decorated inputs: drive the widget’s API, don’t fight its intercepts »#

→ Pour les datepickers par exemple : contourner les sorcelleries UX/UI du composant web, interagir via JS, appeler l’API du composant. Exemple cité : AppointmentPage.enter_visit_date (Bootstrap 3 datepicker).

« Setup/teardown actions: prefer the URL, save the UI click for the test that owns it »#

→ Utiliser le chemin le plus direct pour préparer un test (URL, API, session injectée, fixtures). Ne faire des clics sur l’interface utilisateur que si le test vérifie réellement cette interface utilisateur.

CURA_FRD.md#

1. Executive Summary
2. System Overview (purpose, stakeholders, deployment)
3. User Roles & Personas (authenticated, unauthenticated, demo)
4. Functional Requirements (Auth, Appointment, History, Profile) — c’est le cœur
5. Element IDs (DOM selectors)
6. URL map
7. Business rules
8. Error handling
9. Known bugs / gaps (§9.1 à §9.11)

C’est une documentation reconstruite par IA afin de rendre vérifiable le travail qui a été co-construit.

CURA_TEST_STRATEGY.md#

1. Scope (functional e2e, out: perf/accessibility/email/etc.)
2. Test objectives
3. Test types : happy / unhappy / edge / business logic vulnerability / exploratory / permanent security regression
4. Coverage tables (REQ-AUTH-N × test_X)
5. Suite/campaign tree
6. Expected pass/fail breakdown
7. Categories of results (cf. README : intentional gap, cross-browser, real regression, transient)
8. Run notes

IDENTIFIED_GAPS.md#

• Where : file:line du PHP responsable.
• Symptom : ce qu’on observe.
• GitHub source vs deployment : la différence éventuelle.
• Bonus bug (si présent) : variantes / bugs en cascade.
• Impact : conséquences exploitables.
• Test(s) : nom des tests qui matérialisent.
• SFD ref : pointeur vers §9.X.

→ Format forensique standard. Tout est vérifiable.