TL;DR
Arrêtez les hallucinations des IA en 4 étapes : (1) Installez Playwright et configurez les points d'arrêt (ordinateur de bureau, tablette, mobile), (2) Créez une suite de tests de captures d'écran qui capture la page entière, les mises en page responsives et les interactions, (3) Exécutez ./qa-playwright-capture.sh pour recueillir des preuves, (4) Activez l'agent Reality Checker pour recouper les affirmations avec les résultats grep et les captures d'écran. Les agents renvoient PASS ou NEEDS WORK avec des problèmes bloquants spécifiques — plus d'approbations fantaisistes.
Introduction
Cessez d'accepter les « c'est super » des agents IA. Mettez en place un flux de travail d'assurance qualité basé sur des preuves, avec des captures d'écran Playwright, qui exige une preuve visuelle avant toute approbation.
Vous demandez à un agent IA de réviser votre page de destination. Il répond :
Le design semble premium et soigné. Les effets de glassmorphism sont bien implémentés. La page est entièrement responsive. Prête pour la production !
Vous ouvrez la page. Le « glassmorphism » est un fond gris uni. La mise en page « entièrement responsive » se brise sur mobile. Rien n'est premium ou soigné.
Les agents IA hallucinent. Ils vous disent ce que vous voulez entendre. Ils évitent les conflits. Ils approuvent tout.
L'agent Reality Checker de la collection The Agency adopte une approche différente :
Statut: TRAVAIL NÉCESSAIRE
Preuve:
- grep pour "glassmorphism" a renvoyé AUCUNE FONCTIONNALITÉ PREMIUM TROUVÉE
- responsive-mobile.png montre une mise en page cassée à une largeur de 375px
- test-results.json montre 3 erreurs de console, temps de chargement de 2,1s
Problèmes bloquants: 4
Pas de sentiments. Pas d'opinions. Juste des preuves.
Dans ce tutoriel, vous allez construire un flux de travail d'assurance qualité basé sur des preuves qui complète votre pipeline de tests API. Que vous validiez des mises en page front-end ou vérifiiez des réponses API dans Apidog, le principe est le même : exiger une preuve avant approbation. Vous configurerez Playwright pour des captures d'écran automatisées, créerez des commandes de vérification de la réalité obligatoires, recouperez les affirmations des agents avec le code réel, et exigerez une certification PASS/FAIL avant la livraison.
Pourquoi les preuves sont importantes
Les agents IA sont des flatteurs. Ils veulent aider. Ils veulent que vous les aimiez. Alors ils disent ce qui sonne bien :
- « Le code semble solide ! » (jamais testé)
- « Les performances devraient être excellentes ! » (jamais mesurées)
- « Entièrement responsive ! » (jamais vérifié sur mobile)
L'assurance qualité basée sur des preuves change cela. Au lieu d'opinions, vous obtenez :
- Captures d'écran aux points d'arrêt bureau, tablette, mobile
- Métriques de performance des chargements de page réels
- Résultats Grep prouvant l'existence (ou non) des fonctionnalités
- Nombre d'erreurs console issues des tests de navigateur headless
Fini les « faites-moi confiance ». Juste des preuves.
Étape 1 : Configurer Playwright
Installez Playwright :
npm install -D @playwright/test
npx playwright install chromium
Créez qa-playwright.config.ts :
import { defineConfig } from '@playwright/test';
export default defineConfig({
testMatch: '**/qa-screenshots.spec.ts',
timeout: 30000,
use: {
baseURL: process.env.BASE_URL || 'http://localhost:8000',
screenshot: 'on',
trace: 'on-first-retry',
headless: true,
},
projects: [
{
name: 'desktop',
use: { viewport: { width: 1920, height: 1080 } },
},
{
name: 'tablet',
use: { viewport: { width: 768, height: 1024 } },
},
{
name: 'mobile',
use: { viewport: { width: 375, height: 667 } },
},
],
reporter: [['json', { outputFile: 'public/qa-screenshots/test-results.json' }]],
outputDir: 'public/qa-screenshots',
});
Étape 2 : Créer une suite de tests de captures d'écran
Créez qa-screenshots.spec.ts :
import { test, expect } from '@playwright/test';
import * as fs from 'fs';
import * as path from 'path';
// S'assurer que le répertoire de sortie existe
const outputDir = 'public/qa-screenshots';
if (!fs.existsSync(outputDir)) {
fs.mkdirSync(outputDir, { recursive: true });
}
test.describe('Reality Check Screenshots', () => {
test('capture full page at all breakpoints', async ({ page, browserName }) => {
const errors: string[] = [];
const consoleLogs: string[] = [];
// Capturer les erreurs de console
page.on('console', msg => {
if (msg.type() === 'error') {
consoleLogs.push(`[ERROR] ${msg.text()}`);
}
});
// Capturer les échecs réseau
page.on('requestfailed', request => {
errors.push(`[NETWORK] ${request.url()} failed`);
});
// Naviguer vers la page
await page.goto('/');
await page.waitForLoadState('networkidle');
// Capturer les métriques de performance
const metrics = await page.metrics();
const performance = {
jsHeapSize: metrics.JSHeapUsedSize,
loadTime: await page.evaluate(() => performance.timing.loadEventEnd - performance.timing.navigationStart),
domContentLoaded: await page.evaluate(() => performance.timing.domContentLoadedEventEnd - performance.timing.navigationStart),
};
// Enregistrer la capture d'écran
const projectName = browserName || 'chromium';
await page.screenshot({
path: path.join(outputDir, `full-page-${projectName}.png`),
fullPage: true,
});
// Enregistrer les métriques
fs.writeFileSync(
path.join(outputDir, 'performance-metrics.json'),
JSON.stringify({ performance, consoleErrors: consoleLogs, networkErrors: errors }, null, 2)
);
});
test('capture responsive layouts', async ({ page }) => {
const breakpoints = [
{ name: 'desktop', width: 1920, height: 1080 },
{ name: 'tablet', width: 768, height: 1024 },
{ name: 'mobile', width: 375, height: 667 },
];
for (const breakpoint of breakpoints) {
await page.setViewportSize({ width: breakpoint.width, height: breakpoint.height });
await page.goto('/');
await page.waitForLoadState('networkidle');
await page.screenshot({
path: path.join(outputDir, `responsive-${breakpoint.name}.png`),
fullPage: true,
});
}
});
test('capture navigation interactions', async ({ page }) => {
await page.goto('/');
// Trouver et cliquer sur les éléments de navigation
const navItems = await page.$$('nav a, header a, .nav a');
for (let i = 0; i < Math.min(navItems.length, 5); i++) {
await page.screenshot({ path: path.join(outputDir, `nav-${i}-before.png`) });
await navItems[i].click();
await page.waitForLoadState('networkidle');
await page.screenshot({ path: path.join(outputDir, `nav-${i}-after.png`) });
await page.goBack();
await page.waitForLoadState('networkidle');
}
});
test('capture form interactions', async ({ page }) => {
await page.goto('/');
// Trouver les formulaires
const forms = await page.$$('form');
for (let i = 0; i < forms.length; i++) {
const form = forms[i];
await form.screenshot({ path: path.join(outputDir, `form-${i}-initial.png`) });
// Remplir les champs
const inputs = await form.$$('input[type="text"], input[type="email"], input[type="password"]');
for (const input of inputs) {
await input.fill('test@example.com');
}
await form.screenshot({ path: path.join(outputDir, `form-${i}-filled.png`) });
}
});
test('capture accordion/dropdown interactions', async ({ page }) => {
await page.goto('/');
// Trouver les accordéons
const accordions = await page.$$('[data-accordion], details, .accordion');
for (let i = 0; i < accordions.length; i++) {
await accordions[i].screenshot({ path: path.join(outputDir, `accordion-${i}-closed.png`) });
await accordions[i].click();
await page.waitForTimeout(300);
await accordions[i].screenshot({ path.join(outputDir, `accordion-${i}-open.png`) });
}
});
});
Étape 3 : Créer un script de vérification de la réalité
Créez qa-playwright-capture.sh :
#!/usr/bin/env bash
#
# qa-playwright-capture.sh — Exécute les captures d'écran Playwright pour la vérification de la réalité
#
# Utilisation : ./qa-playwright-capture.sh [BASE_URL] [OUTPUT_DIR]
#
set -euo pipefail
BASE_URL="${1:-http://localhost:8000}"
OUTPUT_DIR="${2:-public/qa-screenshots}"
echo "Démarrage de la capture d'écran pour la vérification de la réalité..."
echo " URL de base : $BASE_URL"
echo " Sortie : $OUTPUT_DIR"
# S'assurer que le répertoire de sortie existe
mkdir -p "$OUTPUT_DIR"
# Exécuter les tests Playwright
export BASE_URL
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"
# Générer le résumé
echo ""
echo "Génération du résumé..."
# Compter les captures d'écran
SCREENSHOT_COUNT=$(find "$OUTPUT_DIR" -name "*.png" | wc -l)
echo " Captures d'écran réalisées : $SCREENSHOT_COUNT"
# Vérifier les erreurs de console
if [ -f "$OUTPUT_DIR/performance-metrics.json" ]; then
ERROR_COUNT=$(cat "$OUTPUT_DIR/performance-metrics.json" | grep -c '"\[ERROR\]"' || echo "0")
echo " Erreurs de console : $ERROR_COUNT"
fi
# Vérifier le temps de chargement
if [ -f "$OUTPUT_DIR/performance-metrics.json" ]; then
LOAD_TIME=$(cat "$OUTPUT_DIR/performance-metrics.json" | grep -o '"loadTime": [0-9.]*' | head -1 | awk '{print $2}')
echo " Temps de chargement : ${LOAD_TIME:-N/A}ms"
fi
echo ""
echo "Vérification de la réalité terminée. Consultez les captures d'écran dans : $OUTPUT_DIR"
echo ""
echo "Étape suivante : Exécuter l'agent Reality Checker pour valider les preuves"
Rendez-le exécutable :
chmod +x qa-playwright-capture.sh
Étape 4 : Exécuter les commandes de vérification de la réalité
Avant qu'un agent IA ne puisse approuver un travail, exécutez ces commandes :
# 1. Vérifier ce qui a été réellement construit
ls -la resources/views/ || ls -la *.html
ls -la src/components/ || ls -la components/
# 2. Recouper les fonctionnalités revendiquées
grep -r "glassmorphism\|backdrop-filter\|blur" . --include="*.css" --include="*.html" || echo "NO GLASSMORPHISM FOUND"
grep -r "responsive\|media-query\|@media" . --include="*.css" || echo "NO RESPONSIVE CSS FOUND"
grep -r "jwt\|authentication\|auth" . --include="*.ts" --include="*.js" || echo "NO AUTH FOUND"
# 3. Exécuter la capture d'écran
./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots
# 4. Examiner les preuves
ls -la public/qa-screenshots/
# Fichiers attendus :
# - responsive-desktop.png
# - responsive-tablet.png
# - responsive-mobile.png
# - nav-*-before.png, nav-*-after.png
# - form-*-initial.png, form-*-filled.png
# 5. Vérifier les métriques
cat public/qa-screenshots/test-results.json
cat public/qa-screenshots/performance-metrics.json
Étape 5 : Activer l'agent Reality Checker
Ouvrez une session Claude Code :
Activez le mode Reality Checker.
Exécutez votre processus de vérification de la réalité obligatoire :
1. Vérifier l'existence des fichiers : ls -la src/components/
2. Recouper les fonctionnalités revendiquées : grep pour "premium", "glassmorphism"
3. Examiner les preuves de capture d'écran : public/qa-screenshots/
4. Vérifier test-results.json pour les métriques
URL du projet : http://localhost:8000
Sortie : PASS ou NEEDS WORK avec des problèmes bloquants spécifiques.
Sortie attendue :
## Résultats de la vérification de la réalité
### Vérification des fichiers : PASS
- Fichiers de composants présents : 12 fichiers trouvés
- La structure attendue correspond
### Vérification des fonctionnalités : TRAVAIL NÉCESSAIRE
- Revendiqué : "Design glassmorphism premium"
- Résultat grep : AUCUN GLASSMORPHISM TROUVÉ
- Statut : REVENDICATION NON SOUTENUE
### Preuves de capture d'écran : TRAVAIL NÉCESSAIRE
- Bureau (1920x1080) : Mise en page correcte
- Tablette (768x1024) : Chevauchement de la navigation détecté
- Mobile (375x667) : Grille de produits cassée (2 colonnes au lieu de 1)
### Métriques de performance : TRAVAIL NÉCESSAIRE
- Temps de chargement : 2,3s (cible : <1s)
- Erreurs de console : 3 (cible : 0)
- Échecs réseau : 1 (cible : 0)
## Statut final : TRAVAIL NÉCESSAIRE
### Problèmes bloquants :
1. Glassmorphism revendiqué mais non implémenté
2. Mise en page mobile cassée à 375px
3. Temps de chargement supérieur à la cible de 1s
4. 3 erreurs de console à corriger
### Non bloquant :
- Chevauchement de la navigation sur tablette
- Ajouter des états de chargement
Ne pas approuver tant que les problèmes bloquants ne sont pas résolus.
Étape 6 : Recouper les revendications avec les preuves
Créez une liste de contrôle des revendications :
## Liste de contrôle Revendications vs. Preuves
| Revendication | Commande de preuve | Résultat |
|----------------------------|----------------------------|--------------------------|
| "Glassmorphism premium" | grep "backdrop-filter" | NON TROUVÉ |
| "Entièrement responsive" | responsive-mobile.png | ÉCHEC (grille cassée) |
| "Aucune erreur console" | test-results.json | 3 erreurs trouvées |
| "Temps de chargement rapide" | performance-metrics.json | 2,3s (cible : <1s) |
| "Authentification JWT" | grep "jsonwebtoken" | TROUVÉ |
| "Limitation de débit" | grep "rateLimit" | NON TROUVÉ |
Mettez à jour cette liste de contrôle pour chaque projet. Exigez des preuves pour chaque revendication.
Flux de travail complet de vérification de la réalité
┌─────────────────────────────────────────────────────────────────┐
│ 1. Développeur/IA termine le travail │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 2. Exécuter les commandes de vérification de la réalité │
│ - ls pour vérifier les fichiers │
│ - grep pour vérifier les fonctionnalités │
│ - Playwright pour les captures d'écran │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 3. Activer l'agent Reality Checker │
│ - Examiner la vérification des fichiers │
│ - Recouper les revendications │
│ - Analyser les captures d'écran │
│ - Vérifier les métriques │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 4. Sortie : PASS ou TRAVAIL NÉCESSAIRE │
│ - PASS : Livrer en toute confiance │
│ - TRAVAIL NÉCESSAIRE : Corriger les problèmes bloquants, relancer │
└─────────────────────────────────────────────────────────────────┘
Intégration avec CI/CD
Ajoutez des vérifications de la réalité à votre pipeline CI :
# .github/workflows/qa-reality-check.yml
name: Vérification de la réalité
on: [pull_request]
jobs:
reality-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Configuration de Node
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Installation des dépendances
run: npm ci
- name: Installation de Playwright
run: npx playwright install chromium
- name: Démarrage du serveur
run: npm start &
env:
PORT: 8000
- name: Attente du serveur
run: sleep 5
- name: Exécution des captures d'écran de vérification de la réalité
run: ./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots
- name: Téléchargement des captures d'écran
uses: actions/upload-artifact@v4
if: always()
with:
name: reality-check-screenshots
path: public/qa-screenshots/
- name: Vérification des erreurs de console
run: |
ERRORS=$(cat public/qa-screenshots/performance-metrics.json | grep -c '"\[ERROR\]"' || echo "0")
if [ "$ERRORS" -gt "0" ]; then
echo "Erreurs de console trouvées : $ERRORS"
exit 1
fi
- name: Vérification du temps de chargement
run: |
LOAD_TIME=$(cat public/qa-screenshots/performance-metrics.json | grep -o '"loadTime": [0-9.]*' | head -1 | awk '{print $2}')
if (( $(echo "$LOAD_TIME > 1000" | bc -l) )); then
echo "Temps de chargement trop lent : ${LOAD_TIME}ms (cible : <1000ms)"
exit 1
fi
Ce que vous avez construit
| Composant | Objectif |
|---|---|
| Configuration Playwright | Captures d'écran automatisées à 3 points d'arrêt |
| Suite de tests | Page entière, responsive, interactions |
| Script de vérification de la réalité | Collecte de preuves en une seule commande |
| Liste de contrôle des revendications | Recouper les revendications de l'IA avec les résultats grep |
| Intégration CI/CD | Vérifications de la réalité automatisées sur les PR |
Prochaines étapes
Étendez le flux de travail :
- Ajoutez l'intégration Lighthouse pour les scores de performance
- Ajoutez des audits d'accessibilité (axe-core)
- Ajoutez des tests de régression visuelle (comparaison de pixels)
Construisez une base de données de revendications :
- Enregistrez chaque revendication de l'IA avec le statut de preuve
- Suivez quels agents hallucinent le plus
- Créez des scores de précision au fil du temps
Partagez avec votre équipe :
- Documentez le processus de vérification de la réalité
- Exigez des preuves avant toute approbation de PR
- Faites du « montrez-moi les captures d'écran » une habitude d'équipe
Dépannage des problèmes courants
Délai d'attente des tests Playwright :
- Augmentez le délai d'attente dans la config :
timeout: 60000 - Vérifiez si le serveur est en cours d'exécution :
curl http://localhost:8000 - Ajoutez un délai d'attente plus long pour l'inactivité du réseau :
await page.waitForLoadState('networkidle', { timeout: 30000 }) - Exécutez en mode "headed" pour déboguer :
npx playwright test --headed
Captures d'écran non prises :
- Vérifiez que le répertoire de sortie existe et est inscriptible :
mkdir -p public/qa-screenshots - Vérifiez les permissions des fichiers :
chmod 755 public/qa-screenshots - Assurez-vous que Chromium est installé :
npx playwright install chromium - Exécutez avec la sortie de débogage :
DEBUG=pw:api npx playwright test
Erreurs de console non capturées :
- Ajoutez l'écouteur avant la navigation :
page.on('console', ...)avantpage.goto() - Vérifiez le filtrage par type d'erreur :
msg.type() === 'error' - Enregistrez tous les messages de la console pour déboguer :
page.on('console', msg => console.log(msg.text())) - Vérifiez que la page charge réellement du contenu (pas de captures d'écran vides)
Les captures d'écran mobiles montrent la mise en page de bureau :
- Assurez-vous que le viewport est défini avant la navigation
- Ajoutez un agent utilisateur mobile :
await page.setUserAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)') - Utilisez l'émulation d'appareil :
use: { ...devices['iPhone 12'] } - Vérifiez la balise meta responsive dans le HTML :
<meta name="viewport" content="width=device-width">
Échec du pipeline CI/CD sur Ubuntu :
- Installez les dépendances système :
sudo apt-get install -y libnss3 libnspr4 libatk1.0-0 - Utilisez l'image officielle de Playwright :
mcr.microsoft.com/playwright:v1.40.0-jammy - Exécutez
npx playwright install-depsavant d'installer les navigateurs - Ajoutez le drapeau
--no-sandboxpour les environnements conteneurisés
Modèles avancés de vérification de la réalité
Modèle 1 : Tests de régression visuelle
Comparez les captures d'écran aux bases de référence pour détecter les changements non intentionnels :
import { expect } from '@playwright/test';
test('visual regression check', async ({ page }) => {
await page.goto('/');
await expect(page).toHaveScreenshot('homepage-base.png', {
maxDiffPixels: 100, // Autoriser les différences mineures
fullPage: true,
});
});
Modèle 2 : Audit d'accessibilité
Intégrez axe-core pour les preuves d'accessibilité :
import AxeBuilder from '@axe-core/playwright';
test('accessibility audit', async ({ page }) => {
await page.goto('/');
const accessibilityScanResults = await new AxeBuilder({ page }).analyze();
// Enregistrer les résultats
const fs = require('fs');
fs.writeFileSync(
'public/qa-screenshots/accessibility-results.json',
JSON.stringify(accessibilityScanResults, null, 2)
);
// Échouer si violations critiques
const criticalViolations = accessibilityScanResults.violations.filter(
v => v.impact === 'critical' || v.impact === 'serious'
);
expect(criticalViolations).toHaveLength(0);
});
Modèle 3 : Application du budget de performance
Faire échouer les builds qui dépassent les seuils de performance :
test('performance budget', async ({ page }) => {
await page.goto('/');
const metrics = await page.metrics();
const loadTime = await page.evaluate(() =>
performance.timing.loadEventEnd - performance.timing.navigationStart
);
// Seuils de budget
expect(loadTime).toBeLessThan(2000); // 2s max
expect(metrics.JSHeapUsedSize).toBeLessThan(5 * 1024 * 1024); // 5Mo max
});
Vos agents IA ne pourront plus s'en tirer avec un simple « c'est super ». Ils doivent prouver leur travail avec des captures d'écran, des métriques et des résultats grep.
Fini les hallucinations. Fini les approbations fantaisistes. Juste des preuves.
Voilà à quoi ressemble l'assurance qualité basée sur des preuves : exécutez les commandes, vérifiez les captures d'écran, exigez des preuves.
À votre tour : ajoutez des vérifications de la réalité à votre flux de travail. Livrez en toute confiance.
FAQ
Pourquoi les agents IA hallucinent-ils lors de la révision du code ?Les agents IA sont entraînés à être serviables et accommodants. Ils répondent avec ce qui semble bien plutôt qu'avec ce qui est vérifié. Sans exigences de preuves, ils disent « c'est super » pour éviter les conflits.
Comment configurer Playwright pour les tests de captures d'écran ?Installez avec npm install -D @playwright/test, exécutez npx playwright install chromium, créez un fichier de configuration avec des points d'arrêt de viewport, et écrivez des suites de tests qui capturent des captures d'écran à chaque point d'arrêt.
Quelles commandes de vérification de la réalité devrais-je exécuter avant l'approbation ?Exécutez ls pour vérifier l'existence des fichiers, grep pour vérifier que les fonctionnalités revendiquées existent dans le code, des tests Playwright pour les captures d'écran, et vérifiez test-results.json pour les erreurs de console et les métriques de performance.
Qu'est-ce que l'agent Reality Checker ?Reality Checker est un agent IA spécialisé de The Agency qui valide le travail à l'aide de preuves. Il exécute des commandes de vérification, examine les captures d'écran, recoupe les affirmations et renvoie PASS ou NEEDS WORK avec des problèmes bloquants spécifiques.
Comment intégrer les vérifications de la réalité dans le CI/CD ?Ajoutez un workflow GitHub Actions qui installe Playwright, démarre votre serveur, exécute des captures d'écran, télécharge les artefacts et fait échouer la build si les erreurs de console dépassent 0 ou si le temps de chargement dépasse votre seuil.
Que faire si les captures d'écran montrent des problèmes mais que l'agent dit PASS ?L'agent est mal configuré. Reality Checker doit examiner les preuves avant de renvoyer un statut. Reformez-le pour qu'il exige : (1) des résultats grep prouvant les fonctionnalités, (2) un examen des captures d'écran, (3) des métriques dans les seuils.
Comment amener mon équipe à adopter l'assurance qualité basée sur des preuves ?Documentez le processus de vérification de la réalité, ajoutez des portes CI/CD qui exigent des tests réussis, rendez l'examen des captures d'écran obligatoire pour l'approbation des PR, et suivez quels agents produisent les évaluations les plus précises.