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

En resumen

Detenga las alucinaciones de la IA en 4 pasos prácticos: (1) Instale Playwright y configure los puntos de interrupción (desktop, tablet, móvil), (2) Cree una suite de pruebas de captura de pantalla para página completa, layouts responsivos e interacciones, (3) Ejecute ./qa-playwright-capture.sh para recolectar evidencia, (4) Active el agente Reality Checker para cotejar afirmaciones con resultados de grep y capturas. Los agentes emiten APROBADO o NECESITA TRABAJO con problemas bloqueantes claros — no más aprobaciones fantasiosas.

Prueba Apidog hoy

Introducción

Deje de aceptar un “se ve genial” de los agentes de IA. Construya un flujo de QA basado en evidencia con capturas de pantalla de Playwright y exija prueba visual antes de aprobar.

¿Le pide a un agente de IA que revise su landing? 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. El “totalmente responsivo” se rompe en móvil. Nada es premium ni pulido.

Los agentes de IA alucinan. Evitan conflictos y aprueban todo.

El agente Reality Checker de la colección The Agency lo hace 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 opiniones. Solo evidencia.

En este tutorial, montarás un flujo de QA basado en evidencia que complementa tu pipeline de pruebas de API. Ya sea validando frontend o verificando APIs en Apidog, el principio es el mismo: exigir pruebas antes de aprobar. Configura Playwright para capturas de pantalla automatizadas, crea comandos de verificación obligatorios y exige APROBADO/FALLO antes de lanzar.

Por qué la evidencia importa

Los agentes de IA suelen responder con 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. Obtendrás:

• Capturas en breakpoints desktop, tablet, móvil
• Métricas de rendimiento reales
• Resultados de grep que prueban la existencia de features
• Errores de consola de pruebas headless

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

Paso 1: Configurar Playwright

Instala Playwright:

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

Crea 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

Crea qa-screenshots.spec.ts:

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

// Asegura que el directorio de salida 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[] = [];

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

    // Capturar fallos de red
    page.on('requestfailed', request => {
      errors.push(`[NETWORK] ${request.url()} failed`);
    });

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

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

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

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

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

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

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

    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

Crea 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"

mkdir -p "$OUTPUT_DIR"

export BASE_URL
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

echo ""
echo "Generando resumen..."

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

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

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 aprobar, ejecuta:

# 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

Abre 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

Crea una checklist 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                |

Actualiza esta lista para cada proyecto: exige 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

Agrega verificaciones de la realidad a tu 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

Extiende el flujo de trabajo:

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

Construye una base de datos de afirmaciones:

• Registra cada afirmación de IA con su evidencia
• Rastrea qué agentes alucinan más
• Crea puntuaciones de precisión históricas

Comparte con tu equipo:

• Documenta el proceso de verificación de la realidad
• Requiere evidencia antes de aprobar PRs
• Haz de “muéstrame las capturas de pantalla” un hábito de equipo

Solución de Problemas Comunes

Los tests de Playwright agotan el tiempo de espera:

• Aumenta el timeout en la config: timeout: 60000
• Verifica si el servidor está en ejecución: curl http://localhost:8000
• Añade una espera más larga: await page.waitForLoadState('networkidle', { timeout: 30000 })
• Ejecuta en modo headed para depurar: npx playwright test --headed

Las capturas de pantalla no se realizan:

• Verifica que el directorio de salida existe: mkdir -p public/qa-screenshots
• Comprueba permisos de archivo: chmod 755 public/qa-screenshots
• Asegúrate de que Chromium está instalado: npx playwright install chromium
• Ejecuta con depuración: DEBUG=pw:api npx playwright test

Los errores de consola no se capturan:

• Añade el listener antes de la navegación: page.on('console', ...) antes de page.goto()
• Comprueba el filtrado: msg.type() === 'error'
• Registra todos los mensajes para depurar: page.on('console', msg => console.log(msg.text()))
• Verifica que la página realmente carga contenido

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

• Establece el viewport antes de navegar
• Añade user-agent móvil: await page.setUserAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)')
• Usa emulación de dispositivo: use: { ...devices['iPhone 12'] }
• Comprueba <meta name="viewport" content="width=device-width"> en HTML

El pipeline de CI/CD falla en Ubuntu:

• Instala dependencias del sistema: sudo apt-get install -y libnss3 libnspr4 libatk1.0-0
• Usa la imagen oficial de Playwright: mcr.microsoft.com/playwright:v1.40.0-jammy
• Ejecuta npx playwright install-deps antes de instalar navegadores
• Añade el flag --no-sandbox en contenedores

Patrones Avanzados de Verificación de la Realidad

Patrón 1: Pruebas de Regresión Visual

Compara capturas con la línea base para detectar cambios inesperados:

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

Integra 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

Falla builds que superen 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
});

Tus agentes de IA ya no pueden aprobar “se ve genial” sin evidencia. Deben demostrarlo con capturas, métricas y grep.

No más alucinaciones ni aprobaciones sin pruebas. Solo evidencia.

Así es como se implementa el QA basado en evidencia: ejecuta los comandos, revisa capturas, exige pruebas.

Tu turno: añade verificaciones de la realidad a tu flujo. Lanza con confianza.

Preguntas Frecuentes (FAQ)

¿Por qué los agentes de IA alucinan al revisar código?

Porque están entrenados para ser útiles y complacientes. Sin requerir evidencia, dicen “se ve genial” para evitar conflictos.

¿Cómo configuro Playwright para pruebas de screenshots?

Instala con npm install -D @playwright/test, ejecuta npx playwright install chromium, crea una configuración con breakpoints de viewport, y escribe suites de pruebas que capturen capturas de pantalla en cada breakpoint.

¿Qué comandos de verificación debo ejecutar antes de aprobar?

Ejecuta ls para verificar archivos, grep para features declaradas, pruebas de Playwright para screenshots, y revisa test-results.json para errores y métricas.

¿Qué es Reality Checker?

Reality Checker es un agente de IA de The Agency que valida usando evidencia: ejecuta comandos, revisa capturas, coteja afirmaciones y emite APROBADO o NECESITA TRABAJO con problemas específicos.

¿Cómo integro las verificaciones en CI/CD?

Agrega un workflow de GitHub Actions que instale Playwright, levante tu server, ejecute screenshots, suba artefactos y falle si hay errores de consola o el tiempo de carga excede el umbral.

¿Qué pasa si las capturas muestran problemas pero el agente dice APROBADO?

El agente está mal configurado. Reality Checker debe revisar evidencia antes de emitir estado. Exige: (1) grep de features, (2) revisión de capturas, (3) métricas dentro de los límites.

¿Cómo logro que mi equipo adopte el QA basado en evidencia?

Documenta el proceso, agrega puertas de CI/CD obligatorias, haz que la revisión de capturas sea requisito para aprobar PRs y rastrea qué agentes hacen evaluaciones más precisas.