dsh-verify

O portão de qualidade para aplicações web construídas por agentes - testes de aceitação em navegador real com veredictos APROVADO/REPROVADO e recibos de captura de tela.

GitHub

Experimente este MCPPatrocinado

Documentação

dsh-verify

中文 | English

Witness — O navegador é o juiz. O portão de qualidade para aplicações web construídas por agentes. Agentes dizem que está pronto; o navegador prova. (Witness é o nome do produto; dsh-verify é o nome do pacote — a mesma coisa.)

Se o Witness pegar algo para você, ⭐ dê uma estrela no repositório — é assim que este projeto continua vivo.

Você pediu a uma IA para construir uma aplicação web. Ela disse "pronto". Será que realmente funciona?

dsh-verify abre um navegador real e verifica — para que você nunca precise confiar na palavra do agente.

dsh-verify in action

O portão de qualidade para aplicações web construídas por agentes. Funciona com qualquer agente — DeepSeek Harness (dsh), Claude Code, Cursor, Copilot, Codex — e com qualquer CI. Você escreve o que um humano verificaria em um navegador; um navegador real executa e retorna um veredito PASS/FAIL com comprovantes (capturas de tela + imagens de diff).

Nenhum LLM julga o resultado. O navegador é o juiz.

Same task, same AI, two builds — only a real browser tells the difference

Mesma tarefa. Mesma IA. Duas versões. Uma regra de CSS ausente — a auto-revisão do agente passou, um navegador real pegou.

Por que isso existe

Executamos um time web de 4 agentes (redator de especificação → desenvolvedor frontend → QA → revisor). A revisão deles disse:

✅ "Todos os requisitos atendidos. Nenhum problema encontrado."

Em um navegador real, o alternador de modo escuro não fazia nada — a classe .dark era alternada, mas a regra de CSS nunca foi escrita. Todos os auto-testes dos agentes passaram porque não havia nada na página para os agentes executarem. Ninguém abriu um navegador real.

Essa é a lacuna: agentes verificam contra o que acreditam ter construído, não contra o que o usuário realmente experimenta. Testes unitários e verificações estáticas não conseguem pegar uma regra de CSS ausente.

Versão	O que os agentes disseram	O que um navegador real diz
`demo/buggy`	"Nenhum problema encontrado"	❌ FALHA — o fundo nunca muda
`demo/fixed`	uma regra de CSS adicionada	✅ PASSOU — o tema alterna

Mesma página. Mesmo JS. Uma regra de CSS ausente. Dois vereditos diferentes.

Por que não simplesmente...?

O que você pode considerar	Seu ponto cego	O que o dsh-verify adiciona
Scripts Playwright feitos à mão	Cada projeto de agente reescreve o mesmo boilerplate; nada é revisável como especificação	Uma especificação JSON é todo o contrato — escreva uma vez, reutilize entre agentes e CI
Juízes LLM (avaliações estilo promptfoo)	Um LLM diz "parece certo" — ele não executa o aplicativo nem vê os pixels	Um navegador real executa cliques, entradas, estilos e retorna comprovantes de captura de tela
Ferramentas de navegador integradas ao agente	São as mãos do agente — compartilham os mesmos pontos cegos do código que acabaram de escrever	O dsh-verify é uma testemunha independente, não parte do agente sendo testado
Ferramentas visuais apenas de captura de tela	Elas pegam desvio de pixels, não "botão não faz nada"	Verificações de comportamento: clique, espere mudança de texto/classe/estilo, erros de console, erros de rede

O agente avaliou o próprio dever de casa. O dsh-verify reavalia em um navegador real.

Use de três maneiras

Ponto de entrada	Para que serve	Uma linha
Servidor MCP	Seu agente de IA verifica sua própria entrega, durante a sessão	`claude mcp add dsh-verify -- npx -y -p dsh-verify dsh-verify-mcp`
CLI	Você ou seu CI verificam uma build/URL	`npx dsh-verify --spec demo/fixed.json`
GitHub Action	Cada push executa verificações em navegador real	`uses: 263311487-ux/dsh-verify/.github/actions/dsh-verify@main`

De qualquer agente de IA (MCP)

claude mcp add dsh-verify -- npx -y -p dsh-verify dsh-verify-mcp

Depois diga ao seu agente, em palavras simples:

Verifique http://localhost:3000 — clique em #dark-toggle, depois verifique se a body background-color mudou. Tire uma captura de tela.

Ferramentas expostas: verify_spec (executa uma especificação JSON), verify_url (verificações inline, sem arquivos), generate_and_verify (a IA rascunha a lista de verificação, o Chromium real executa), health.

No CI (GitHub Action)

- uses: 263311487-ux/dsh-verify/.github/actions/dsh-verify@main
  with:
    spec: demo/fixed.json       # spec file or glob
    # url: https://staging.example.com   # optional override
    # out: dsh-verify-out               # report output dir (default)

O repositório usa o próprio produto: o workflow dogfood afirma que a build corrigida passa e a build com bug falha em cada push.

Na linha de comando

npm install -g dsh-verify          # or: npx dsh-verify
npx playwright install chromium    # one-time browser download
npx dsh-verify --spec 'specs/*.json'
# [PASS] specs/home.json (5/5)
# [FAIL] specs/cart.json (4/5)
#   ❌ expect_text #total: got "0" want "99"

O que está incluído

Juiz determinístico — um Chromium headless real (ou Firefox / WebKit) executa verificações no estilo humano: clique, preenchimento, texto, classes, estilos computados, URLs, erros de console, erros de rede, pixels.
Comprovantes, não vibrações — cada execução emite um relatório HTML autocontido com capturas de tela e imagens de diff destacadas em vermelho; --json para máquinas; código de saída 0/1 para CI.
Regressão visual — baselines de captura de tela, diff de pixels com limites (expect_screenshot), atualize com --update-baselines.
Listas de verificação rascunhadas por IA — dsh-verify gen --url ... --prompt "..." aprende a página em um navegador real, faz um LLM rascunhar a lista de verificação e depois executa deterministicamente. A IA rascunha; nunca julga.
Multi-navegador — chromium | firefox | webkit por especificação ou --browser.
Zero dependência de framework — uma especificação JSON é tudo o que existe. Sem linguagem de configuração, sem SDK, sem fornecedor.

Exemplo de especificação

{
  "title": "my app",
  "serve": "dist",
  "browser": "chromium",
  "steps": [
    { "action": "goto", "path": "/index.html" },
    { "action": "click", "selector": "#count-btn", "count": 3 },
    { "action": "expect_text", "selector": "#count-btn", "text": "Clicked: 3" },
    { "action": "capture_style", "selector": "#page", "prop": "backgroundColor", "var": "bg_before" },
    { "action": "click", "selector": "#color-btn" },
    { "action": "expect_class", "selector": "#page", "class": "dark", "present": true },
    { "action": "expect_style_changed", "selector": "#page", "prop": "backgroundColor", "var": "bg_before" },
    { "action": "screenshot", "name": "final-state" }
  ]
}

Campos de nível superior: title, serve (diretório estático) ou base (URL alvo), browser, steps. Execute muitos de uma vez com um glob; a saída é 0 apenas se todos passarem.

O relatório

Um relatório HTML autocontido — cada etapa com um selo de passou/falhou, seletor e detalhe, além de capturas de tela:

dsh-verify report

Agent Arena — traga seu agente

Benchmark em navegador real para aplicações web construídas por agentes: mesmas 3 tarefas, mesmas verificações humanas, entrada aberta. Execute seu modelo no quadro em ~10 minutos:

git clone https://github.com/263311487-ux/dsh-verify && cd dsh-verify
npm install && npx playwright install chromium
export LLM_API_KEY=sk-...          # any OpenAI-compatible model
node arena/run.mjs --agent "gpt-5/single" --task all --repeat 1 --submitter yourname

Sua configuração aparece no leaderboard ao vivo ao lado de DeepSeek v4-flash / v4-pro: agent-arena. Regras completas em docs/ARENA.md.

Prove (execute você mesmo)

git clone https://github.com/263311487-ux/dsh-verify && cd dsh-verify
npm install && npx playwright install chromium
npm run demo:fixed    # → PASS (11/11)
npm run demo:buggy    # → FAIL (exit 1) — the missing .dark rule, caught
npm test              # engine self-tests

O próprio CI do repositório executa exatamente isso — auto-testes do motor, depois afirma que a versão corrigida passa e a com bug falha — para que a ferramenta se verifique em cada push.

Agent Arena — agentes conseguem entregar aplicações web funcionais?

Mesma tarefa, mesmo prompt, mesmas verificações humanas — agentes diferentes, avaliados pelo dsh-verify em um navegador real. Última execução (2026-08-19): 44/48 execuções passaram em 2 modelos × 2 estratégias × 3 tarefas, 4 execuções por célula. Duas descobertas contraintuitivas: o mais caro v4-pro single-shot pontuou abaixo do mais barato v4-flash single-shot (10/12 vs 11/12), e um loop de auto-verificação em navegador real elevou o v4-pro para 12/12 — enquanto o auto-check do v4-flash travou uma vez quando seu próprio relatório de verificação voltou como JSON corrompido. Cada falha é reproduzível e invisível para um juiz LLM.

Veja docs/ARENA.md — metodologia, as tarefas e como executar seu próprio agente.

Insígnia para sua aplicação construída por agente

Construiu algo com um agente de IA? Prove em um navegador real e mostre ao mundo:

[![agent deliverable: browser-verified](https://img.shields.io/badge/agent_deliverable-browser_verified-brightgreen?logo=playwright&logoColor=white)](https://github.com/263311487-ux/dsh-verify)

Adicione uma especificação, conecte o GitHub Action, e a insígnia é conquistada, não reivindicada. Veja docs/verified-badge.md.

Roadmap

Servidor MCP · listas de verificação rascunhadas por IA · regressão visual · multi-navegador · GitHub Action · plugin dsh
Agent arena — um benchmark público: dê a mesma tarefa a diferentes configurações de agentes, avalie em navegadores reais, publique o leaderboard
Gravador de especificações (extensão de navegador: clique uma vez → especificação gerada)
Execuções em nuvem + links de relatórios compartilháveis + comentários em PR

Relacionados

dsh-doublecheck — portão de qualidade de entrega para DeepSeek Harness (/gate): grill de requisitos + disciplina de evidências. Par complementar: /gate mantém as evidências honestas, dsh-verify mantém o navegador honesto.
falsify — o protocolo de pensamento científico para agentes de IA (hipótese → falsificação → evidência → conclusão calibrada). O par: falsify pega a conclusão errada, dsh-verify pega a saída quebrada.
Apresentado na comunidade DeepSeek Harness — Show Your Plugins: dsh-verify (resultados do Agent Arena com 48 execuções no tópico)

Licença

MIT