mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-05-18 08:18:15 +02:00
capitalisation: intégration ~60 entrées RL799_V2 (triage 2026-05-02)
Triage du 95_a_capitaliser.md (~75 propositions) : - 60 entrées intégrées dans knowledge/ (backend, frontend, workflow) - 4 nouveaux fichiers : backend/patterns/tests.md, backend/risques/tests.md, frontend/patterns/general.md, workflow/patterns/general.md - 6 doublons rejetés - Mise à jour des READMEs index pour refléter les nouvelles entrées - 95_a_capitaliser.md restauré à sa structure initiale - 40_decisions_et_archi.md : décision mono-tenant déployable vs SaaS multi-tenant - 90_debug_et_postmortem.md : sub-agents Write indisponible, effet iceberg CI, prisma migrate diffs cosmétiques Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
MaksTinyWorkshop
@@ -149,6 +149,22 @@ source_projects: [app-alexandrie, app-template-resto, RL799_V2]
|
||||
|
||||
- Contexte technique : Vue 3 / node:test — RL799_V2 02-04-2026
|
||||
|
||||
### Cas additionnel : obsolescence silencieuse après refacto structurel
|
||||
|
||||
Au-delà du faux garde-fou de non-régression, un test en `readFileSync(path) + content.includes(...)` devient obsolète sans alarme dès qu'une réorganisation structurelle déplace le code visé. Trois variantes vécues :
|
||||
|
||||
1. **Fichier déplacé par scoping** (ex: `pages/X.vue` → `pages/<module>/X.vue`) → `ENOENT` au runtime, le test crashe au lieu de signaler une régression métier
|
||||
2. **Logique extraite dans un composable / sous-composant** → la chaîne attendue ne vit plus dans le `.vue` mais dans `composables/use<X>.ts` ; le `.vue` existe encore mais ne contient plus le pattern, donc le test échoue sur une assertion sans rapport avec la vraie cause
|
||||
3. **Variable supprimée du `<script setup>` mais conservée dans le template** → string-match passe (le template contient toujours la string), crash JS au mount du composant
|
||||
|
||||
**Mitigations spécifiques** :
|
||||
|
||||
- Centraliser le `path` du fichier visé dans une constante en tête de fichier de test (pas `resolve(...)` inline) — facilite le rerouting en cas de refacto
|
||||
- Lors d'une extraction de logique dans un composable / sous-composant, grep les tests structurels qui pointaient le fichier d'origine et les rediriger vers le nouveau chemin
|
||||
- Pour les composants interactifs (formulaires, modales, listes avec actions), compléter le string-match par au moins un test de mount via `@vue/test-utils` qui vérifie le render sans crash — c'est le seul moyen de valider la cohérence script ↔ template
|
||||
|
||||
- Contexte technique : Vue 3 / vitest — RL799_V2 30-04-2026 (3 cas observés sur la même session)
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-catch-false-test-skip-e2e"></a>
|
||||
@@ -171,3 +187,129 @@ source_projects: [app-alexandrie, app-template-resto, RL799_V2]
|
||||
- **Signal review** : `.catch(() => false)` suivi de `test.skip` dans un test E2E
|
||||
|
||||
- Contexte technique : Playwright / E2E — RL799_V2 08-04-2026
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-tests-e2e-6-causes-racines"></a>
|
||||
## Tests E2E qui rotent — 6 causes-racines récurrentes
|
||||
|
||||
### Risques
|
||||
|
||||
- Sur une suite E2E mature, les fails ne viennent presque jamais d'un bug applicatif : ils viennent d'un désalignement test ↔ code de prod
|
||||
- Conclure à une régression métier alors que c'est du test obsolète fait perdre du temps et masque les vraies régressions
|
||||
|
||||
### Symptômes
|
||||
|
||||
Les 6 patterns observés sur RL799_V2 (Playwright + Vue 3 + refactors UI fréquents) :
|
||||
|
||||
1. **Testid changé sans MAJ tests** : `getByTestId('library-entries')` timeout, mais le composant expose `data-testid="document-list"`. Cause : refactor d'un composant qui fusionne plusieurs vues en un composant générique avec un testid neutre.
|
||||
|
||||
2. **Labels métier qui changent** : `await expect(badge).toHaveText('Publiée')` échoue, le badge affiche désormais 'Convoquée'. Cause : refactor lifecycle qui renomme les labels affichés sans toucher aux testids structurels.
|
||||
|
||||
3. **Menus / dropdowns conditionnels** : `getByTestId('odj-insert-menu').click()` timeout aléatoire — parfois le menu s'ouvre, parfois pas. Cause : UX qui adapte le flow selon l'état (1 seul type → bouton direct, plusieurs → menu).
|
||||
|
||||
4. **Features supprimées** : `await page.goto('/secretaire?soireeId=xxx')` charge la page mais ne sélectionne plus la soirée. Cause : query param retiré au profit d'une navigation par onglets + click sur card.
|
||||
|
||||
5. **Refactor visuel** : `await expect(badge).toHaveText('A∴')` échoue, le badge affiche désormais une icône SVG. Cause : refactor de représentation (texte → icône) sans toucher au testid.
|
||||
|
||||
6. **Cleanup post-test** : test métier passe en 2 s, mais le `finally { await restoreEntry() }` timeout à 30 s. Cause : le PATCH de cleanup tape sur une route lente (audit log, notif, validation).
|
||||
|
||||
### Bonnes pratiques / mitigations
|
||||
|
||||
À chaque diagnostic E2E, vérifier d'abord ces 6 hypothèses avant de conclure à une régression métier :
|
||||
|
||||
- **Cause 1** : grep `data-testid` dans le composant cible avant de modifier le test. Ne jamais "deviner" le testid à partir du nom de la page.
|
||||
- **Cause 2** : préférer asserter sur des classes CSS modifier (`.badge--published`) ou des testids d'état (`data-testid="status-published"`) plutôt que sur du texte humain (cf. `pattern-asserter-classe-css-modifier-vs-texte` dans `frontend/patterns/tests.md`).
|
||||
- **Cause 3** : guard conditionnel via `isVisible({ timeout: 1_000 }).catch(() => false)` pour gérer les deux branches.
|
||||
- **Cause 4** : quand un test commence par une URL avec query param, vérifier en premier que ce param est encore consommé par la page (grep `useRoute` / `route.query` dans le composant).
|
||||
- **Cause 5** : asserter la classe CSS modifier (plus stable que innerHTML qui contiendrait le SVG).
|
||||
- **Cause 6** : cleanup best-effort avec timeout court (cf. `pattern-cleanup-e2e-best-effort` dans `frontend/patterns/tests.md`).
|
||||
|
||||
### Méta-leçon
|
||||
|
||||
Quand on découvre N fails E2E après une période de refactor intense :
|
||||
|
||||
1. Lancer la suite complète une fois pour avoir la liste exhaustive
|
||||
2. Trier par cause-racine plutôt que par fichier
|
||||
3. Fixer en lots cohérents (1 commit par cause-racine) plutôt qu'1 commit par fail
|
||||
4. Capitaliser les patterns dès qu'ils se répètent (> 2 occurrences)
|
||||
|
||||
- Contexte technique : Playwright / Vue 3 — RL799_V2 25-04-2026
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-tests-string-match-repointer-composant"></a>
|
||||
## Tests `string-match .vue` — limites et compléments après extraction
|
||||
|
||||
### Risques
|
||||
|
||||
- Quand on extrait une section/onglet vers un sous-composant, les assertions `readFileSync + content.includes('Ordre du jour')` échouent — la string est maintenant dans le sous-composant, pas dans la page
|
||||
- Mauvaises réactions : supprimer le test (perd la garantie), `.skip()` (dette accumulée), inverser en `toBeFalsy()` (régression masquée), repointer aveuglément (peut camoufler un problème)
|
||||
|
||||
### Symptômes
|
||||
|
||||
```
|
||||
AssertionError: expected false to be truthy
|
||||
expect(tenuesPage.includes('Ordre du jour')).toBeTruthy();
|
||||
^
|
||||
```
|
||||
|
||||
### Bonnes pratiques / mitigations
|
||||
|
||||
**Diagnostic** : lire l'assertion et identifier ce qu'elle garantit (présence d'un comportement métier, d'un data-testid critique, d'un ordre visuel).
|
||||
|
||||
**Repointer correctement** :
|
||||
|
||||
```typescript
|
||||
const here = dirname(fileURLToPath(import.meta.url));
|
||||
const root = resolve(here, '../../../..');
|
||||
|
||||
// Page coquille (ce qui reste : layout, tabs, rendu conditionnel)
|
||||
const tenuesPage = readFileSync(
|
||||
resolve(root, 'src/pages/tenues/TenuesPage.vue'),
|
||||
'utf-8',
|
||||
);
|
||||
// Sous-composant qui incarne désormais le markup d'un onglet
|
||||
const prochaineView = readFileSync(
|
||||
resolve(root, 'src/pages/tenues/components/ProchaineTenueView.vue'),
|
||||
'utf-8',
|
||||
);
|
||||
// Composable qui incarne désormais la logique d'un onglet
|
||||
const useProchaine = readFileSync(
|
||||
resolve(root, 'src/pages/tenues/composables/useProchaineTenue.ts'),
|
||||
'utf-8',
|
||||
);
|
||||
|
||||
test('TenuesPage utilise le modèle de vue testable pour tab/titre', () => {
|
||||
expect(tenuesPage.includes('resolveTenuesTab')).toBeTruthy();
|
||||
expect(useProchaine.includes('getProchaineTenueTitle')).toBeTruthy();
|
||||
});
|
||||
```
|
||||
|
||||
**Renommer aussi le test si pertinent** :
|
||||
|
||||
```typescript
|
||||
// Avant
|
||||
test('TenuesPage redirige vers une page dédiée en cas de 403...', () => { /* … */ });
|
||||
|
||||
// Après — le nom devient un index sémantique
|
||||
test('usePastTenues redirige vers une page dédiée en cas de 403...', () => { /* … */ });
|
||||
```
|
||||
|
||||
### Anti-pattern : tests structurels qui bougent en cascade
|
||||
|
||||
Si tes tests doivent être systématiquement mis à jour à chaque refactor, c'est que beaucoup de garanties sont vérifiées par string-match plutôt que par comportement. Pour les composants interactifs critiques (formulaires, listes avec actions, modales), **doubler** avec un test de mount `@vue/test-utils` qui survit aux refactors.
|
||||
|
||||
### Trois variantes vécues
|
||||
|
||||
1. **Fichier déplacé par scoping** (`pages/X.vue` → `pages/<module>/X.vue`) → `ENOENT` au runtime, le test crashe au lieu de signaler une régression métier
|
||||
2. **Logique extraite dans un composable / sous-composant** → la chaîne attendue ne vit plus dans le `.vue` ; le test échoue sur une assertion sans rapport avec la vraie cause
|
||||
3. **Variable supprimée du `<script setup>` mais conservée dans le template** → string-match passe (le template contient toujours la string), crash JS au mount du composant
|
||||
|
||||
**Mitigations spécifiques** :
|
||||
|
||||
- Centraliser le `path` du fichier visé dans une constante en tête de fichier de test — facilite le rerouting en cas de refacto
|
||||
- Lors d'une extraction, grep les tests structurels qui pointaient le fichier d'origine et les rediriger vers le nouveau chemin
|
||||
- Pour les composants interactifs, compléter par au moins un test de mount via `@vue/test-utils` qui vérifie le render sans crash
|
||||
|
||||
- Contexte technique : Vue 3 / Vitest — RL799_V2 29-04-2026
|
||||
|
||||
Reference in New Issue
Block a user