Comment créer des agents IA qui prouvent leur travail avec des captures d'écran : Fini les hallucinations

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.

Essayez Apidog dès aujourd'hui

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('[e-mail]');
      }

      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: 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', ...) avant page.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-deps avant d'installer les navigateurs
• Ajoutez le drapeau --no-sandbox pour 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.