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

Em resumo

Pare as alucinações da IA com 4 passos práticos:

1. Instale o Playwright e configure os breakpoints (desktop, tablet, celular).
2. Crie uma suíte de testes de captura de tela cobrindo 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 alegações com grep e screenshots. O agente retorna APROVADO ou PRECISA DE TRABALHO com bloqueios claros.

Experimente o Apidog hoje mesmo

Introdução

Chega de “está ótimo” de agentes de IA. Implemente um fluxo de QA baseado em evidências, usando capturas de tela automáticas do Playwright, exigindo prova visual antes de aprovar qualquer entrega.

Exemplo clássico de alucinação de IA:

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

Você verifica: não tem glassmorphism, o responsivo quebra, nada é premium.

O agente Reality Checker da coleção The Agency segue outra abordagem:

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 achismos. Só evidência.

Neste tutorial, você vai montar um fluxo de QA baseado em evidências para reforçar seu pipeline de testes — tanto para frontend (com screenshots Playwright) quanto para APIs no Apidog. O objetivo: exigir prova antes de qualquer aprovação.

Por que a Evidência Importa

Agentes de IA costumam aprovar tudo sem testar:

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

Com QA baseado em evidências, você obtém:

• Capturas de tela reais (desktop, tablet, celular)
• Métricas de performance de carregamento
• Grep para provar existência de recursos
• Contagem de erros de console

Não confie em opiniões — exija provas.

Passo 1: Configurar o Playwright

Instale o Playwright:

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

Crie qa-playwright.config.ts para definir breakpoints e saída:

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

Implemente qa-screenshots.spec.ts para capturar página inteira, responsividade e interações:

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

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[] = [];

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

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

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

Automatize a coleta de evidências com 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"

mkdir -p "$OUTPUT_DIR"

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

echo ""
echo "Gerando resumo..."

SCREENSHOT_COUNT=$(find "$OUTPUT_DIR" -name "*.png" | wc -l)
echo "  Capturas de tela 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 "  Erros de console: $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 "  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"

Torne o script executável:

chmod +x qa-playwright-capture.sh

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

Antes de aprovar qualquer entrega, execute:

# 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

Inicie uma sessão do Claude Code (ou agente similar) e insira:

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 checklist de alegações vs. evidências:

## 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 a tabela a cada projeto. Todo claim deve ter evidência.

---

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

Inclua a verificação no seu pipeline do GitHub Actions:

# .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

Estenda o fluxo:

• Adicione integração Lighthouse para métricas de desempenho
• Insira auditorias de acessibilidade (axe-core)
• Implemente testes de regressão visual (comparação de pixels)

Construa um banco de dados de alegações:

• Registre cada claim de IA com status de evidência
• Rastreie quais agentes mais alucinam
• Gere score de precisão ao longo do tempo

Compartilhe com sua equipe:

• Documente o processo de verificação da realidade
• Exija evidências antes de aprovar PRs
• Torne "mostre-me as capturas de tela" um hábito

Solução de Problemas Comuns

Timeout nos testes Playwright:

• Aumente timeout para 60000
• Confirme se o servidor está rodando: curl http://localhost:8000
• Use await page.waitForLoadState('networkidle', { timeout: 30000 })
• Execute testes em modo headed: npx playwright test --headed

Capturas de tela não sendo salvas:

• Garanta que o diretório existe: mkdir -p public/qa-screenshots
• Verifique permissões: chmod 755 public/qa-screenshots
• Confirme instalação do Chromium: npx playwright install chromium
• Use DEBUG=pw:api npx playwright test para depurar

Erros de console não capturados:

• Adicione o listener antes do page.goto()
• Confirme o filtro msg.type() === 'error'
• Logue todas as mensagens: page.on('console', msg => console.log(msg.text()))
• Certifique-se de que a página carrega conteúdo real

Screenshot mobile mostra layout de desktop:

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

Pipeline CI/CD falha no Ubuntu:

• Instale dependências: sudo apt-get install -y libnss3 libnspr4 libatk1.0-0
• Use imagem oficial Playwright: mcr.microsoft.com/playwright:v1.40.0-jammy
• Rode npx playwright install-deps antes dos navegadores
• Adicione --no-sandbox em containers

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

Padrão 1: Teste de Regressão Visual

Compare screenshots com baseline:

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

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

Padrão 2: Auditoria de Acessibilidade

Integre axe-core para auditoria:

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

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

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

  const criticalViolations = accessibilityScanResults.violations.filter(
    v => v.impact === 'critical' || v.impact === 'serious'
  );
  expect(criticalViolations).toHaveLength(0);
});

Padrão 3: Orçamento de Desempenho

Estoure a build se exceder limites:

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

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

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

Seus agentes de IA agora são obrigados a provar cada claim com evidência: screenshot, métricas, grep.

Chega de alucinações e aprovações fantasiosas. Só evidência.

Implemente esses passos no seu workflow. Lance com confiança.

FAQ

Por que os agentes de IA alucinam ao revisar código?

Eles são treinados para agradar — respondem com o que soa bem, não o que é verificado. Sem exigência de evidência, dizem “está ótimo” para evitar conflitos.

Como configuro o Playwright para testes de captura de tela?

Instale com npm install -D @playwright/test, rode npx playwright install chromium, crie um config com breakpoints e escreva testes que capturem screenshots em cada viewport.

Quais comandos de verificação devo executar antes da aprovação?

Use ls para checar arquivos, grep para features, Playwright para screenshots, e revise test-results.json para erros/metricas.

O que é o agente Reality Checker?

Um agente IA da The Agency que valida trabalho usando comandos de verificação, screenshots e métricas, e retorna APROVADO ou PRECISA DE TRABALHO com bloqueios claros.

Como integrar as verificações ao CI/CD?

Adicione um workflow do GitHub Actions que instala o Playwright, inicia seu servidor, executa capturas, faz upload de artefatos e falha se houver erros ou lentidão além do limite.

E se as screenshots mostram problemas, mas o agente diz APROVADO?

O agente está mal configurado. O Reality Checker deve revisar as evidências antes de aprovar. Retreine para exigir: (1) grep dos recursos, (2) revisão de screenshot, (3) métricas dentro do limite.

Como fazer a equipe adotar QA baseado em evidências?

Documente o processo, adicione gates no CI/CD, torne revisão de screenshot obrigatória para PR, e monitore quais agentes trazem avaliações mais precisas.