Como Fazer Agentes de IA Provarem o Trabalho com Screenshots (Sem Alucinações)

Em resumo

Pare as alucinações da IA com 4 passos: (1) Instale o Playwright e configure os pontos de interrupção (desktop, tablet, celular), (2) Crie uma suíte de testes de captura de tela que registre a página inteira, layouts responsivos e interações, (3) Execute ./qa-playwright-capture.sh para coletar evidências, (4) Ative o agente Reality Checker para cruzar referências de alegações com resultados de grep e capturas de tela. Os agentes retornam APROVADO ou PRECISA DE TRABALHO com problemas de bloqueio específicos – chega de aprovações fantasiosas.

Introdução

Pare de aceitar “está ótimo” de agentes de IA. Construa um fluxo de trabalho de QA baseado em evidências com capturas de tela do Playwright que exija prova visual antes de qualquer aprovação.

Você pede a um agente de IA para revisar sua landing page. Ele responde:

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

Você abre a página. O “glassmorphism” é um fundo cinza sólido. O layout “totalmente responsivo” quebra no celular. Nada é premium ou polido.

Agentes de IA alucinam. Eles dizem o que você quer ouvir. Evitam conflitos. Aprovam tudo.

O agente Reality Checker da coleção The Agency adota uma abordagem diferente:

Status: PRECISA DE TRABALHO

Evidência:
- grep por "glassmorphism" retornou NENHUM RECURSO PREMIUM ENCONTRADO
- responsive-mobile.png mostra layout quebrado na largura de 375px
- test-results.json mostra 3 erros de console, tempo de carregamento de 2.1s

Problemas de bloqueio: 4

Sem sentimentos. Sem opiniões. Apenas evidências.

Neste tutorial, você construirá um fluxo de trabalho de QA baseado em evidências que complementa seu pipeline de testes de API. Seja validando layouts de frontend ou verificando respostas de API no Apidog, o princípio é o mesmo: exija prova antes da aprovação. Você configurará o Playwright para capturas de tela automatizadas, criará comandos obrigatórios de verificação da realidade, cruzará referências de alegações de agentes com código real e exigirá certificação APROVADO/REPROVADO antes do lançamento.

Por que a Evidência Importa

Agentes de IA são bajuladores. Eles querem ajudar. Querem que você goste deles. Então, eles dizem o que soa bem:

“O código parece sólido!” (nunca testado)
“O desempenho deve ser ótimo!” (nunca medido)
“Totalmente responsivo!” (nunca verificado no celular)

QA baseado em evidências muda isso. Em vez de opiniões, você obtém:

Capturas de tela em pontos de interrupção de desktop, tablet e celular
Métricas de desempenho de carregamentos reais da página
Resultados de Grep provando que os recursos existem (ou não)
Contagem de erros de console de testes de navegador headless

Chega de "confie em mim". Apenas prova.

Passo 1: Configurar o Playwright

Instalar o Playwright:

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

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

Passo 2: Criar Suíte de Testes de Captura de Tela

Criar qa-screenshots.spec.ts:

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

// Garante que o diretório de saída exista
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[] = [];

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

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

    // Navega para a página
    await page.goto('/');
    await page.waitForLoadState('networkidle');

    // Captura métricas de desempenho
    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),
    };

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

    // Salva métricas
    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('/');

    // Encontra e clica em itens de navegação
    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('/');

    // Encontra formulários
    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`) });

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

    // Encontra acordeões
    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`) });
    }
  });
});

Passo 3: Criar Script de Verificação da Realidade

Criar qa-playwright-capture.sh:

#!/usr/bin/env bash
#
# qa-playwright-capture.sh — Executa capturas de tela do Playwright para verificação da realidade
#
# 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 captura de tela para Verificação da Realidade..."
echo "  URL Base: $BASE_URL"
echo "  Saída: $OUTPUT_DIR"

# Garante que o diretório de saída exista
mkdir -p "$OUTPUT_DIR"

# Executa testes do Playwright
export BASE_URL
npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

echo ""
echo "Gerando resumo..."

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

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

# Verifica tempo de carregamento
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 "  Tempo de carregamento: ${LOAD_TIME:-N/A}ms"
fi

echo ""
echo "Verificação da Realidade concluída. Revise as capturas de tela em: $OUTPUT_DIR"
echo ""
echo "Próximo passo: Execute o agente Reality Checker para validar as evidências"

Torná-lo executável:

chmod +x qa-playwright-capture.sh

Passo 4: Executar Comandos de Verificação da Realidade

Antes que qualquer agente de IA possa aprovar o trabalho, execute estes comandos:

# 1. Verifique o que foi realmente construído
ls -la resources/views/ || ls -la *.html
ls -la src/components/ || ls -la components/

# 2. Faça a verificação cruzada dos recursos alegados
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. Execute a captura de tela
./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots

# 4. Revise as evidências
ls -la public/qa-screenshots/
# Arquivos esperados:
# - responsive-desktop.png
# - responsive-tablet.png
# - responsive-mobile.png
# - nav-*-before.png, nav-*-after.png
# - form-*-initial.png, form-*-filled.png

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

Passo 5: Ativar Agente Verificador da Realidade

Abra uma sessão do Claude Code:

Ativar modo Verificador da Realidade.

Execute seu processo obrigatório de verificação da realidade:

1. Verifique se os arquivos existem: ls -la src/components/
2. Faça a verificação cruzada dos recursos alegados: grep por "premium", "glassmorphism"
3. Revise as evidências de captura de tela: public/qa-screenshots/
4. Verifique test-results.json para métricas

Project URL: http://localhost:8000

Saída: APROVADO ou PRECISA DE TRABALHO com problemas de bloqueio específicos.

Saída esperada:

## Resultados da Verificação da Realidade

### Verificação de Arquivos: APROVADO
- Arquivos de componente presentes: 12 arquivos encontrados
- Estrutura esperada corresponde

### Verificação de Recursos: PRECISA DE TRABALHO
- Alegado: "Design premium com glassmorphism"
- resultado grep: NENHUM GLASSMORPHISM ENCONTRADO
- Status: ALEGAÇÃO NÃO SUPORTADA

### Evidência de Captura de Tela: PRECISA DE TRABALHO
- Desktop (1920x1080): Layout correto
- Tablet (768x1024): Sobreposição de navegação detectada
- Celular (375x667): Grade de produtos quebrada (2 colunas em vez de 1)

### Métricas de Desempenho: PRECISA DE TRABALHO
- Tempo de carregamento: 2.3s (meta: <1s)
- Erros de console: 3 (meta: 0)
- Falhas de rede: 1 (meta: 0)

## Status Final: PRECISA DE TRABALHO

### Problemas de Bloqueio:
1. Glassmorphism alegado, mas não implementado
2. Layout móvel quebrado em 375px
3. Tempo de carregamento excede a meta de 1s
4. 3 erros de console para corrigir

### Não Bloqueadores:
- Sobreposição de navegação no Tablet
- Adicionar estados de carregamento

Não aprove até que os problemas de bloqueio sejam resolvidos.

Passo 6: Cruza Referências de Alegações com Evidências

Crie uma lista de verificação de alegações:

## Lista de Verificação de Alegações vs. Evidências

| Alegação | Comando de Evidência | Resultado |
|-------|------------------|--------|
| "Glassmorphism premium" | grep "backdrop-filter" | NÃO ENCONTRADO |
| "Totalmente responsivo" | responsive-mobile.png | FALHA (grade quebrada) |
| "Sem erros de console" | test-results.json | 3 erros encontrados |
| "Tempo de carregamento rápido" | performance-metrics.json | 2.3s (meta: <1s) |
| "Autenticação JWT" | grep "jsonwebtoken" | ENCONTRADO |
| "Limite de taxa" | grep "rateLimit" | NÃO ENCONTRADO |

Atualize esta lista de verificação para cada projeto. Exija evidências para cada alegação.

Fluxo de Trabalho Completo de Verificação da Realidade

┌─────────────────────────────────────────────────────────────────┐
│  1. Desenvolvedor/IA completa o trabalho                        │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  2. Execute os comandos de verificação da realidade             │
│     - ls para verificar arquivos                                │
│     - grep para verificar recursos                              │
│     - Playwright para capturas de tela                          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  3. Ative o agente Verificador da Realidade                     │
│     - Revise a verificação de arquivos                          │
│     - Cruza referências de alegações                            │
│     - Analise as capturas de tela                               │
│     - Verifique as métricas                                     │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│  4. Saída: APROVADO ou PRECISA DE TRABALHO                      │
│     - APROVADO: Lance com confiança                             │
│     - PRECISA DE TRABALHO: Corrija problemas de bloqueio, execute novamente │
└─────────────────────────────────────────────────────────────────┘

Integração com CI/CD

Adicione verificações da realidade ao seu pipeline de CI:

# .github/workflows/qa-reality-check.yml
name: Verificação da Realidade

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 dependências
        run: npm ci

      - name: Instalar Playwright
        run: npx playwright install chromium

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

      - name: Aguardar servidor
        run: sleep 5

      - name: Executar capturas de tela da verificação da realidade
        run: ./qa-playwright-capture.sh http://localhost:8000 public/qa-screenshots

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

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

      - name: Verificar tempo de carregamento
        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 "Tempo de carregamento muito lento: ${LOAD_TIME}ms (meta: <1000ms)"
            exit 1
          fi

O Que Você Construiu

Componente	Propósito
Configuração do Playwright	Capturas de tela automatizadas em 3 pontos de interrupção
Suíte de testes	Página inteira, responsivo, interações
Script de verificação da realidade	Coleta de evidências com um comando
Lista de verificação de alegações	Cruza referências de alegações de IA com resultados de grep
Integração CI/CD	Verificações da realidade automatizadas em PR

Próximos Passos

Estender o fluxo de trabalho:

Adicionar integração Lighthouse para pontuações de desempenho
Adicionar auditorias de acessibilidade (axe-core)
Adicionar testes de regressão visual (comparação de pixels)

Construir um banco de dados de alegações:

Registrar cada alegação de IA com status de evidência
Rastrear quais agentes alucinam mais
Criar pontuações de precisão ao longo do tempo

Compartilhe com sua equipe:

Documentar o processo de verificação da realidade
Exigir evidências antes de qualquer aprovação de PR
Torne "mostre-me as capturas de tela" um hábito da equipe

Solução de Problemas Comuns

Tempo limite dos testes do Playwright:

Aumente o tempo limite na configuração: timeout: 60000
Verifique se o servidor está rodando: curl http://localhost:8000
Adicione um tempo de espera maior para inatividade da rede: await page.waitForLoadState('networkidle', { timeout: 30000 })
Execute em modo com interface para depurar: npx playwright test --headed

Capturas de tela não estão sendo salvas:

Verifique se o diretório de saída existe e é gravável: mkdir -p public/qa-screenshots
Verifique as permissões do arquivo: chmod 755 public/qa-screenshots
Garanta que o Chromium esteja instalado: npx playwright install chromium
Execute com saída de depuração: DEBUG=pw:api npx playwright test

Erros de console não estão sendo capturados:

Adicione o listener antes da navegação: page.on('console', ...) antes de page.goto()
Verifique a filtragem do tipo de erro: msg.type() === 'error'
Registre todas as mensagens do console para depurar: page.on('console', msg => console.log(msg.text()))
Verifique se a página realmente carrega conteúdo (sem capturas de tela em branco)

Capturas de tela de celular mostram layout de desktop:

Garanta que o viewport esteja configurado antes da navegação
Adicione user agent móvel: await page.setUserAgent('Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X)')
Use emulação de dispositivo: use: { ...devices['iPhone 12'] }
Verifique a meta tag responsiva no HTML: <meta name="viewport" content="width=device-width">

Pipeline CI/CD falha no Ubuntu:

Instale as dependências do sistema: sudo apt-get install -y libnss3 libnspr4 libatk1.0-0
Use a imagem oficial do Playwright: mcr.microsoft.com/playwright:v1.40.0-jammy
Execute npx playwright install-deps antes de instalar navegadores
Adicione a flag --no-sandbox para ambientes conteinerizados

Padrões Avançados de Verificação da Realidade

Padrão 1: Teste de Regressão Visual

Compare capturas de tela com baselines para detectar mudanças não intencionais:

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

test('visual regression check', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveScreenshot('homepage-base.png', {
    maxDiffPixels: 100, // Permite pequenas diferenças
    fullPage: true,
  });
});

Padrão 2: Auditoria de Acessibilidade

Integre axe-core para evidências de acessibilidade:

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

test('accessibility audit', async ({ page }) => {
  await page.goto('/');
  const accessibilityScanResults = await new AxeBuilder({ page }).analyze();

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

  // Falha se houver violações críticas
  const criticalViolations = accessibilityScanResults.violations.filter(
    v => v.impact === 'critical' || v.impact === 'serious'
  );
  expect(criticalViolations).toHaveLength(0);
});

Padrão 3: Aplicação de Orçamento de Desempenho

Faça com que builds falhem se excederem os limites de desempenho:

test('performance budget', async ({ page }) => {
  await page.goto('/');

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

  // Limites de orçamento
  expect(loadTime).toBeLessThan(2000); // 2s máximo
  expect(metrics.JSHeapUsedSize).toBeLessThan(5 * 1024 * 1024); // 5MB máximo
});

Seus agentes de IA não podem mais se safar com “está ótimo.” Eles devem provar seu trabalho com capturas de tela, métricas e resultados de grep.

Chega de alucinações. Chega de aprovações fantasiosas. Apenas evidências.

É assim que o QA baseado em evidências se parece: execute os comandos, verifique as capturas de tela, exija prova.

Sua vez: adicione verificações da realidade ao seu fluxo de trabalho. Lance com confiança.

button

FAQ

Por que os agentes de IA alucinam ao revisar código?Os agentes de IA são treinados para serem úteis e agradáveis. Eles respondem com o que soa bem, em vez do que é verificado. Sem requisitos de evidência, eles dizem “está ótimo” para evitar conflitos.

Como configuro o Playwright para testes de captura de tela?Instale com npm install -D @playwright/test, execute npx playwright install chromium, crie um arquivo de configuração com pontos de interrupção de viewport e escreva suítes de teste que capturem capturas de tela em cada ponto de interrupção.

Quais comandos de verificação da realidade devo executar antes da aprovação?Execute ls para verificar se os arquivos existem, grep para verificar se os recursos alegados existem no código, testes do Playwright para capturas de tela e verifique test-results.json para erros de console e métricas de desempenho.

O que é o agente Reality Checker?Reality Checker é um agente de IA especializado da The Agency que valida o trabalho usando evidências. Ele executa comandos de verificação, revisa capturas de tela, cruza referências de alegações e retorna APROVADO ou PRECISA DE TRABALHO com problemas de bloqueio específicos.

Como integro as verificações da realidade no CI/CD?Adicione um fluxo de trabalho do GitHub Actions que instala o Playwright, inicia seu servidor, executa capturas de tela, faz upload de artefatos e falha a build se os erros do console excederem 0 ou o tempo de carregamento exceder seu limite.

E se as capturas de tela mostrarem problemas, mas o agente disser APROVADO?O agente está mal configurado. O Reality Checker deve revisar as evidências antes de retornar o status. Retreine-o para exigir: (1) resultados de grep que comprovem recursos, (2) revisão de captura de tela, (3) métricas dentro dos limites.

Como faço para minha equipe adotar o QA baseado em evidências?Documente o processo de verificação da realidade, adicione "gates" de CI/CD que exijam a aprovação nos testes, torne a revisão de capturas de tela obrigatória para aprovação de PR e rastreie quais agentes produzem as avaliações mais precisas.