Cómo Hacer que Agentes de IA Demuestren su Trabajo con Capturas de Pantalla: Evita Alucinaciones

En resumen

Detenga las alucinaciones de la IA con 4 pasos: (1) Instale Playwright y configure los puntos de interrupción (escritorio, tableta, móvil), (2) Cree un conjunto de pruebas de captura de pantalla que capture la página completa, los diseños responsivos y las interacciones, (3) Ejecute ./qa-playwright-capture.sh para recopilar pruebas, (4) Active el agente Reality Checker para cotejar las afirmaciones con los resultados de grep y las capturas de pantalla. Los agentes emiten APROBADO o NECESITA TRABAJO con problemas bloqueantes específicos — no más aprobaciones fantasiosas.

Introducción

Deje de aceptar un “se ve genial” de los agentes de IA. Construya un flujo de trabajo de QA basado en evidencia con capturas de pantalla de Playwright que requiera prueba visual antes de cualquier aprobación.

Le pide a un agente de IA que revise su página de destino. Responde:

The design looks premium and polished. The glassmorphism effects are well-implemented. The page is fully responsive. Ready for production!

Abre la página. El “glassmorphism” es un fondo gris sólido. El diseño “totalmente responsivo” se rompe en el móvil. Nada es premium ni pulido.

Los agentes de IA alucinan. Le dicen lo que quiere oír. Evitan los conflictos. Aprueban todo.

El agente Reality Checker de la colección The Agency adopta un enfoque diferente:

Estado: NECESITA TRABAJO

Evidencia:
- grep para "glassmorphism" devolvió NO SE ENCONTRARON CARACTERÍSTICAS PREMIUM
- responsive-mobile.png muestra el diseño roto con un ancho de 375px
- test-results.json muestra 3 errores de consola, tiempo de carga de 2.1s

Problemas bloqueantes: 4

Sin sentimientos. Sin opiniones. Solo evidencia.

En este tutorial, construirá un flujo de trabajo de QA basado en evidencia que complementa su pipeline de pruebas de API. Ya sea que esté validando diseños de frontend o verificando respuestas de API en Apidog, el principio es el mismo: exigir pruebas antes de la aprobación. Configurará Playwright para capturas de pantalla automatizadas, creará comandos obligatorios de verificación de la realidad, cotejará las afirmaciones del agente con el código real y exigirá la certificación APROBADO/FALLO antes del lanzamiento.

Por qué la evidencia importa

Los agentes de IA son complacientes. Quieren ayudar. Quieren gustarle. Por eso dicen lo que suena bien:

“¡El código parece sólido!” (nunca probado)
“¡El rendimiento debería ser excelente!” (nunca medido)
“¡Totalmente responsivo!” (nunca comprobado en móvil)

El QA basado en evidencia cambia esto. En lugar de opiniones, obtiene:

Capturas de pantalla en puntos de interrupción de escritorio, tableta, móvil
Métricas de rendimiento de cargas reales de la página
Resultados de Grep que prueban que las características existen (o no)
Recuentos de errores de consola de pruebas de navegador sin interfaz gráfica

No más “confía en mí”. Solo pruebas.

Paso 1: Configurar Playwright

Instalar Playwright:

npm install -D @playwright/test
npx playwright install chromium

Crear 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',
});

Paso 2: Crear Suite de Pruebas de Captura de Pantalla

Crear qa-screenshots.spec.ts:

import { test, expect } from '@playwright/test';
import * as fs from 'fs';
import * as path from 'path';

// Ensure output directory exists
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[] = [];

    // Capture console errors
    page.on('console', msg => {
      if (msg.type() === 'error') {
        consoleLogs.push(`[ERROR] ${msg.text()}`);
      }
    });

    // Capture network failures
    page.on('requestfailed', request => {
      errors.push(`[NETWORK] ${request.url()} failed`);
    });

    // Navigate to page
    await page.goto('/');
    await page.waitForLoadState('networkidle');

    // Capture performance metrics
    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),
    };

    // Save screenshot
    const projectName = browserName || 'chromium';
    await page.screenshot({
      path: path.join(outputDir, `full-page-${projectName}.png`),
      fullPage: true,
    });

    // Save metrics
    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('/');

    // Find and click navigation items
    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('/');

    // Find forms
    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`) });

      // Fill inputs
      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('/');

    // Find accordions
    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`) });
    }
  });
});

Paso 3: Crear Script de Verificación de la Realidad

Crear qa-playwright-capture.sh:

#!/usr/bin/env bash
#
# qa-playwright-capture.sh — Ejecutar capturas de pantalla de Playwright para verificación de la realidad
#
# Uso: ./qa-playwright-capture.sh [BASE_URL] [OUTPUT_DIR]
#

set -euo pipefail

BASE_URL="${1:-http://localhost:8000}"
OUTPUT_DIR="${2:-public/qa-screenshots}"

echo "Iniciando la captura de pantalla de Verificación de la Realidad..."
echo "  URL Base: $BASE_URL"
echo "  Salida: $OUTPUT_DIR"

# Asegurar que el directorio de salida existe
mkdir -p "$OUTPUT_DIR"

# Ejecutar pruebas de Playwright
export BASE_URL
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

# Generar resumen
echo ""
echo "Generando resumen..."

# Contar capturas de pantalla
SCREENSHOT_COUNT=$(find "$OUTPUT_DIR" -name "*.png" | wc -l)
echo "  Capturas de pantalla realizadas: $SCREENSHOT_COUNT"

# Comprobar errores de consola
if [ -f "$OUTPUT_DIR/performance-metrics.json" ]; then
  ERROR_COUNT=$(cat "$OUTPUT_DIR/performance-metrics.json" | grep -c '"\[ERROR\]"' || echo "0")
  echo "  Errores de consola: $ERROR_COUNT"
fi

# Comprobar tiempo de carga
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 "  Tiempo de carga: ${LOAD_TIME:-N/A}ms"
fi

echo ""
echo "Verificación de la Realidad completada. Revise las capturas de pantalla en: $OUTPUT_DIR"
echo ""
echo "Siguiente paso: Ejecutar el agente Reality Checker para validar la evidencia"

Hazlo ejecutable:

chmod +x qa-playwright-capture.sh

Paso 4: Ejecutar Comandos de Verificación de la Realidad

Antes de que cualquier agente de IA pueda aprobar el trabajo, ejecute estos comandos:

# 1. Verificar lo que realmente se construyó
ls -la resources/views/ || ls -la *.html
ls -la src/components/ || ls -la components/

# 2. Cotejar las características declaradas
grep -r "glassmorphism\|backdrop-filter\|blur" . --include="*.css" --include="*.html" || echo "NO SE ENCONTRÓ GLASSMORPHISM"
grep -r "responsive\|media-query\|@media" . --include="*.css" || echo "NO SE ENCONTRÓ CSS RESPONSIVO"
grep -r "jwt\|authentication\|auth" . --include="*.ts" --include="*.js" || echo "NO SE ENCONTRÓ AUTENTICACIÓN"

# 3. Ejecutar captura de pantalla
./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots

# 4. Revisar la evidencia
ls -la public/qa-screenshots/
# Archivos esperados:
# - responsive-desktop.png
# - responsive-tablet.png
# - responsive-mobile.png
# - nav-*-before.png, nav-*-after.png
# - form-*-initial.png, form-*-filled.png

# 5. Comprobar métricas
cat public/qa-screenshots/test-results.json
cat public/qa-screenshots/performance-metrics.json

Paso 5: Activar el Agente Reality Checker

Abra una sesión de Claude Code:

Activar modo Reality Checker.

Ejecute su proceso obligatorio de verificación de la realidad:

1. Verificar que los archivos existen: ls -la src/components/
2. Cotejar características declaradas: grep para "premium", "glassmorphism"
3. Revisar evidencia de captura de pantalla: public/qa-screenshots/
4. Comprobar test-results.json para métricas

URL del Proyecto: http://localhost:8000

Salida: APROBADO o NECESITA TRABAJO con problemas bloqueantes específicos.

Salida esperada:

## Resultados de Verificación de la Realidad

### Verificación de Archivos: APROBADO
- Archivos de componentes presentes: 12 archivos encontrados
- La estructura esperada coincide

### Verificación de Características: NECESITA TRABAJO
- Declarado: "Diseño premium de glassmorphism"
- Resultado de grep: NO SE ENCONTRÓ GLASSMORPHISM
- Estado: RECLAMACIÓN NO SOPORTADA

### Evidencia de Captura de Pantalla: NECESITA TRABAJO
- Escritorio (1920x1080): Diseño correcto
- Tableta (768x1024): Superposición de navegación detectada
- Móvil (375x667): Cuadrícula de productos rota (2 columnas en lugar de 1)

### Métricas de Rendimiento: NECESITA TRABAJO
- Tiempo de carga: 2.3s (objetivo: <1s)
- Errores de consola: 3 (objetivo: 0)
- Fallos de red: 1 (objetivo: 0)

## Estado Final: NECESITA TRABAJO

### Problemas Bloqueantes:
1. Glassmorphism declarado pero no implementado
2. Diseño móvil roto a 375px
3. El tiempo de carga excede el objetivo de 1s
4. 3 errores de consola por corregir

### No Bloqueantes:
- Superposición de navegación en tableta
- Añadir estados de carga

No aprobar hasta que se resuelvan los problemas bloqueantes.

Paso 6: Cotejar Afirmaciones con Evidencia

Crear una lista de verificación de afirmaciones:

## Lista de Verificación: Afirmaciones vs. Evidencia

| Afirmación | Comando de Evidencia | Resultado |
|-------|------------------|--------|
| "Premium glassmorphism" | grep "backdrop-filter" | NOT FOUND |
| "Fully responsive" | responsive-mobile.png | FAIL (broken grid) |
| "No console errors" | test-results.json | 3 errors found |
| "Fast load time" | performance-metrics.json | 2.3s (target: <1s) |
| "JWT authentication" | grep "jsonwebtoken" | FOUND |
| "Rate limiting" | grep "rateLimit" | NOT FOUND |

Actualice esta lista de verificación para cada proyecto. Requiera evidencia para cada afirmación.

Flujo de Trabajo Completo de Verificación de la Realidad

┌─────────────────────────────────────────────────────────────────┐
│  1. Desarrollador/IA completa el trabajo                        │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  2. Ejecutar comandos de verificación de la realidad            │
│     - ls para verificar archivos                                │
│     - grep para verificar características                       │
│     - Playwright para capturas de pantalla                      │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  3. Activar el agente Reality Checker                           │
│     - Revisar verificación de archivos                          │
│     - Cotejar afirmaciones                                      │
│     - Analizar capturas de pantalla                             │
│     - Comprobar métricas                                        │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  4. Salida: APROBADO o NECESITA TRABAJO                         │
│     - APROBADO: Lanzar con confianza                            │
│     - NECESITA TRABAJO: Corregir problemas bloqueantes, reejecutar│
└─────────────────────────────────────────────────────────────────┘

Integración con CI/CD

Agregue verificaciones de la realidad a su pipeline de CI:

# .github/workflows/qa-reality-check.yml
name: Verificación de la Realidad

on: [pull_request]

jobs:
  reality-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configurar Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Instalar dependencias
        run: npm ci

      - name: Instalar Playwright
        run: npx playwright install chromium

      - name: Iniciar servidor
        run: npm start &
        env:
          PORT: 8000

      - name: Esperar servidor
        run: sleep 5

      - name: Ejecutar capturas de pantalla de verificación de la realidad
        run: ./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots

      - name: Subir capturas de pantalla
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: reality-check-screenshots
          path: public/qa-screenshots/

      - name: Comprobar errores de consola
        run: |
          ERRORS=$(cat public/qa-screenshots/performance-metrics.json | grep -c '"\[ERROR\]"' || echo "0")
          if [ "$ERRORS" -gt "0" ]; then
            echo "Errores de consola encontrados: $ERRORS"
            exit 1
          fi

      - name: Comprobar tiempo de carga
        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 "Tiempo de carga demasiado lento: ${LOAD_TIME}ms (objetivo: <1000ms)"
            exit 1
          fi

Lo que construyó

Componente	Propósito
Configuración de Playwright	Capturas de pantalla automatizadas en 3 puntos de interrupción
Suite de pruebas	Página completa, responsivo, interacciones
Script de verificación de la realidad	Recopilación de evidencia con un solo comando
Lista de verificación de afirmaciones	Cotejar las afirmaciones de la IA con los resultados de grep
Integración CI/CD	Verificaciones de la realidad automatizadas en PR

Siguientes Pasos

Extender el flujo de trabajo:

Añadir integración de Lighthouse para puntuaciones de rendimiento
Añadir auditorías de accesibilidad (axe-core)
Añadir pruebas de regresión visual (comparación de píxeles)

Construir una base de datos de afirmaciones:

Registrar cada afirmación de IA con el estado de la evidencia
Rastrear qué agentes alucinan más
Crear puntuaciones de precisión a lo largo del tiempo

Compartir con su equipo:

Documentar el proceso de verificación de la realidad
Requerir evidencia antes de cualquier aprobación de PR
Hacer de “muéstrame las capturas de pantalla” un hábito del equipo

Solución de Problemas Comunes

Los tests de Playwright agotan el tiempo de espera:

Aumentar el tiempo de espera en la configuración: timeout: 60000
Comprobar si el servidor está en ejecución: curl http://localhost:8000
Añadir una espera más larga para la inactividad de la red: await page.waitForLoadState('networkidle', { timeout: 30000 })
Ejecutar en modo con interfaz gráfica para depurar: npx playwright test --headed

Las capturas de pantalla no se realizan:

Verificar que el directorio de salida existe y es escribible: mkdir -p public/qa-screenshots
Comprobar permisos de archivo: chmod 755 public/qa-screenshots
Asegurarse de que Chromium está instalado: npx playwright install chromium
Ejecutar con salida de depuración: DEBUG=pw:api npx playwright test

Los errores de consola no se capturan:

Añadir el listener antes de la navegación: page.on('console', ...) antes de page.goto()
Comprobar el filtrado por tipo de error: msg.type() === 'error'
Registrar todos los mensajes de consola para depurar: page.on('console', msg => console.log(msg.text()))
Verificar que la página realmente carga contenido (sin capturas de pantalla en blanco)

Las capturas de pantalla móviles muestran el diseño de escritorio:

Asegurarse de que el viewport se establece antes de la navegación
Añadir agente de usuario móvil: await page.setUserAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)')
Usar emulación de dispositivo: use: { ...devices['iPhone 12'] }
Comprobar la meta etiqueta responsiva en HTML: <meta name="viewport" content="width=device-width">

El pipeline de CI/CD falla en Ubuntu:

Instalar dependencias del sistema: sudo apt-get install -y libnss3 libnspr4 libatk1.0-0
Usar la imagen oficial de Playwright: mcr.microsoft.com/playwright:v1.40.0-jammy
Ejecutar npx playwright install-deps antes de instalar los navegadores
Añadir el flag --no-sandbox para entornos contenedorizados

Patrones Avanzados de Verificación de la Realidad

Patrón 1: Pruebas de Regresión Visual

Compare capturas de pantalla con las líneas base para detectar cambios no deseados:

import { expect } from '@playwright/test';

test('verificación de regresión visual', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveScreenshot('homepage-base.png', {
    maxDiffPixels: 100, // Permitir diferencias menores
    fullPage: true,
  });
});

Patrón 2: Auditoría de Accesibilidad

Integre axe-core para evidencia de accesibilidad:

import AxeBuilder from '@axe-core/playwright';

test('auditoría de accesibilidad', async ({ page }) => {
  await page.goto('/');
  const accessibilityScanResults = await new AxeBuilder({ page }).analyze();

  // Guardar resultados
  const fs = require('fs');
  fs.writeFileSync(
    'public/qa-screenshots/accessibility-results.json',
    JSON.stringify(accessibilityScanResults, null, 2)
  );

  // Fallar si hay violaciones críticas
  const criticalViolations = accessibilityScanResults.violations.filter(
    v => v.impact === 'critical' || v.impact === 'serious'
  );
  expect(criticalViolations).toHaveLength(0);
});

Patrón 3: Cumplimiento del Presupuesto de Rendimiento

Falle las compilaciones que excedan los umbrales de rendimiento:

test('presupuesto de rendimiento', async ({ page }) => {
  await page.goto('/');

  const metrics = await page.metrics();
  const loadTime = await page.evaluate(() =>
    performance.timing.loadEventEnd - performance.timing.navigationStart
  );

  // Umbrales de presupuesto
  expect(loadTime).toBeLessThan(2000); // 2s máximo
  expect(metrics.JSHeapUsedSize).toBeLessThan(5 * 1024 * 1024); // 5MB máximo
});

Sus agentes de IA ya no pueden salirse con la suya diciendo “se ve genial”. Deben probar su trabajo con capturas de pantalla, métricas y resultados de grep.

No más alucinaciones. No más aprobaciones fantasiosas. Solo evidencia.

Así es como se ve el QA basado en evidencia: ejecute los comandos, revise las capturas de pantalla, exija pruebas.

Su turno: añada verificaciones de la realidad a su flujo de trabajo. Lance con confianza.

button

Preguntas Frecuentes (FAQ)

¿Por qué los agentes de IA alucinan al revisar código?Los agentes de IA están entrenados para ser útiles y complacientes. Responden con lo que suena bien en lugar de lo que está verificado. Sin requisitos de evidencia, dicen “se ve genial” para evitar conflictos.

¿Cómo configuro Playwright para pruebas de captura de pantalla?Instale con npm install -D @playwright/test, ejecute npx playwright install chromium, cree un archivo de configuración con puntos de interrupción de viewport, y escriba suites de pruebas que capturen capturas de pantalla en cada punto de interrupción.

¿Qué comandos de verificación de la realidad debo ejecutar antes de la aprobación?Ejecute ls para verificar que los archivos existen, grep para verificar que las características declaradas existen en el código, pruebas de Playwright para capturas de pantalla, y revise test-results.json para errores de consola y métricas de rendimiento.

¿Qué es el agente Reality Checker?Reality Checker es un agente de IA especializado de The Agency que valida el trabajo utilizando evidencia. Ejecuta comandos de verificación, revisa capturas de pantalla, coteja afirmaciones y emite APROBADO o NECESITA TRABAJO con problemas bloqueantes específicos.

¿Cómo integro las verificaciones de la realidad en CI/CD?Añada un flujo de trabajo de GitHub Actions que instale Playwright, inicie su servidor, ejecute capturas de pantalla, suba artefactos y falle la compilación si los errores de consola superan 0 o el tiempo de carga excede su umbral.

¿Qué pasa si las capturas de pantalla muestran problemas pero el agente dice APROBADO?El agente está mal configurado. Reality Checker debe revisar la evidencia antes de emitir un estado. Reentrénalo para que requiera: (1) resultados de grep que prueben las características, (2) revisión de capturas de pantalla, (3) métricas dentro de los umbrales.

¿Cómo consigo que mi equipo adopte el QA basado en evidencia?Documente el proceso de verificación de la realidad, añada puertas de CI/CD que requieran pasar las pruebas, haga obligatoria la revisión de capturas de pantalla para la aprobación de PR, y rastree qué agentes producen las evaluaciones más precisas.