Étude de cas : marble-minotaur

1. Contexte et objectifs

Problématique

Automatiser les audits qualité web. Plutôt que d'auditer manuellement chaque page d'une application, le Minotaure explore le labyrinthe (l'app) et rapporte chaque problème trouvé.

• Crawl automatique de toutes les pages accessibles
• Audit multi-critères : SEO, accessibilité, performance, sécurité, formulaires, i18n, images
• Rapports HTML interactifs avec screenshots
• Mode CI/CD avec scoring et quality gates
• Alimentation de Granit Golem pour le monitoring continu

Pourquoi Playwright comme library ?

2. Architecture modulaire

Structure du projet

src/
├── cli.ts                    # CLI entry (Commander)
├── engine.ts                 # Core orchestrator
├── auditors/                 # 7 auditors pluggables
│   ├── accessibility.auditor.ts  # axe-core + ARIA
│   ├── seo.auditor.ts           # title, meta, h1, og:tags
│   ├── performance.auditor.ts    # Core Web Vitals (LCP, CLS)
│   ├── security-headers.auditor.ts # HSTS, CSP, X-Frame
│   ├── forms.auditor.ts          # Form field validation
│   ├── i18n.auditor.ts           # Translation key check
│   └── images.auditor.ts         # src/alt validation
├── services/
│   ├── crawler.service.ts    # BFS traversal engine
│   ├── auth.service.ts       # Automatic login detection
│   ├── gate.service.ts       # Quality gate scoring
│   └── llm-scenario-planner.service.ts  # GPT form workflows
├── scenarios/
│   └── granit-golem.scenario.ts  # Pre-configured crawl
└── report/
    ├── console.reporter.ts   # Terminal output
    └── html.reporter.ts      # Interactive HTML reports

Interface Auditor

Chaque auditor implémente la même interface. Facile d'en ajouter de nouveaux sans toucher au code existant :

export interface Auditor {
  name: string;
  audit(page: Page, url: string): Promise<AuditResult>;
}

export interface AuditResult {
  auditor: string;
  score: number;        // 0-100
  issues: AuditIssue[];
  metadata?: Record<string, unknown>;
}

Les 7 auditors

3. BFS Crawler

Le crawler parcourt l'application en largeur d'abord (BFS), garantissant une couverture de surface optimale :

4. Mode CI/CD

marble-minotaur s'intègre dans les pipelines CI/CD avec un mode dédié : score global, seuil configurable, et exit code pour bloquer les déploiements si la qualité n'est pas au rendez-vous.

# Utilisation CI
npx tsx src/cli.ts https://app.example.com \
  --ci --ci-threshold 70 \
  --output json --output-path report.json
# Exit 0 si score >= 70, exit 1 sinon

5. Intégration Granit Golem

marble-minotaur est conçu pour alimenter la plateforme de monitoring Granit Golem. Les scénarios pré-configurés génèrent des rapports qui deviennent des audits dans le système de monitoring.

6. LLM Scenario Planner

Utilisation optionnelle de GPT-4o-mini pour planifier les scénarios de remplissage de formulaires lors du crawl. Quand le crawler rencontre un formulaire, le LLM génère un plan de remplissage intelligent basé sur le contexte de la page.

7. Configuration CLAUDE.md

Le CLAUDE.md de marble-minotaur contient un piège important spécifique à l'utilisation de Playwright comme library avec esbuild/tsx :

## Playwright rules (MANDATORY)

### page.evaluate()
- MUST receive a string, NEVER a closure/arrow function
- tsx/esbuild injects `__name` that breaks browser context

BAD:
```typescript
await page.evaluate(() => document.title);
```

GOOD:
```typescript
await page.evaluate('document.title');
```

### Playwright usage
- Playwright is used as a LIBRARY, not a test runner
- Do NOT use expect() from @playwright/test
- Use Playwright browser automation APIs only

### Testing
- Run `vitest run` before considering code done
- Target: maintain 55%+ coverage
- Track technical debt via `// DEBT:` comments

8. Métriques

Fonctionnalités clés

9. Enseignements