dsh-verify

Los agentes se autoevalúan y pasan. Los navegadores reales dicen la verdad.

dsh-verify es un probador de aceptación pequeño y con pocas dependencias para artefactos web entregados por agentes. Escribes una especificación JSON de lo que un humano comprobaría en un navegador; lanza un Chromium real sin interfaz, hace clic, lee los estilos calculados y produce un informe HTML además de un código de salida 0/1.

Existe porque nos pasó factura — y tenemos las pruebas.

La historia (por qué existe esto)

Montamos un equipo web de 4 agentes (redactor de especificaciones → desarrollador frontend → QA → revisor). El equipo publicó una página de demostración con un contador y un interruptor de modo oscuro. Su propio informe de revisión decía:

✅ "Todos los requisitos cumplidos. No se encontraron problemas."

En un navegador real, el botón de alternancia no hacía nada: el fondo de la página nunca cambiaba. La clase .dark se alternaba con JavaScript, pero la regla CSS para .dark nunca se escribió. Todos los autotests de los agentes pasaron porque no había nada en la página que los agentes pudieran ejecutar. Nadie abrió un navegador real.

Esa es la brecha: los agentes verifican contra lo que creen que han construido, no contra lo que el usuario experimenta realmente. Las pruebas unitarias y las comprobaciones estáticas no pueden detectar una regla CSS que falta.

Este repositorio contiene el error, corregido, lado a lado — y la evidencia basada en el navegador que los separa:

Misma página. Mismo JS. Una regla CSS que falta. Dos veredictos distintos.

Related MCP server: Mochi

El informe

Un informe HTML autocontenido — cada paso con una insignia de aprobado/suspenso, selector y detalle, además de capturas de pantalla:

Qué hace

• Lee una especificación JSON (sin framework, sin lenguaje de configuración)

• Sirve tu directorio estático (o apunta a cualquier URL)

• Maneja un Chromium real sin interfaz (Playwright)

• Comprueba lo que los humanos comprueban: texto, clases, estilos calculados, URLs, píxeles

• Genera un informe HTML autocontenido con capturas e imágenes de diferencias

• Sale con 0 si pasa, 1 si falla → introdúcelo en cualquier CI

• Servidor MCP para Claude Code / Cursor / Copilot · Listas de verificación redactadas por IA · GitHub Action · DSH plugin

Instalación

# from npm (CLI)
npm install -g dsh-verify

# as a DeepSeek Harness (DSH) plugin — available in every session of the profile
dsh plugin --profile web add dsh-verify

# or run without installing
npx dsh-verify --help

Úsalo desde cualquier agente de IA (MCP)

dsh-verify incluye un servidor MCP, así que Claude Code, Cursor, Copilot, o cualquier agente compatible con MCP puede verificar sus propias entregas en un navegador real — sin necesidad de archivos de especificación:

# register once (Claude Code)
claude mcp add dsh-verify -- npx -y -p dsh-verify dsh-verify-mcp

# or (Cursor / generic MCP client)
# add a stdio server with the command:  npx -y -p dsh-verify dsh-verify-mcp

Luego dile a tu agente, en palabras sencillas:

Verifica http://localhost:3000 — haz clic en #dark-toggle y comprueba que el background-color de body ha cambiado. Toma una captura.

El agente llama a verify_url con una lista de comprobaciones de estilo humano (goto / click / fill / expect_text / expect_class / capture_style / expect_style_changed / expect_url_contains / expect_navigation / expect_console_errors / expect_network_errors / screenshot / expect_screenshot), un Chromium real sin interfaz las ejecuta de forma determinista, y el agente recibe un veredicto PASS/FAIL además de un informe HTML autocontenido.

Herramientas que expone el servidor MCP:

Ningún LLM juzga el resultado — el navegador es el juez. Ese es el punto.

Úsalo en CI (GitHub Action)

Un solo paso en cualquier flujo de trabajo — instala dsh-verify y Chromium de forma aislada (tu proyecto queda intacto), ejecuta las comprobaciones y sube el informe como artefacto:

- 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)

El repositorio lo usa en producción: el flujo de trabajo dogfood verifica que la compilación corregida pasa y que la compilación con errores falla en cada push.

Regresión visual (líneas base de capturas de pantalla a nivel de píxel)

Cambia la página y deja que los píxeles te lo digan — no tus ojos, no tu memoria:

{
  "title": "my app",
  "serve": "dist",
  "steps": [
    { "action": "goto", "path": "/index.html" },
    { "action": "expect_screenshot", "name": "home", "threshold": 0.01 }
  ]
}

• La primera ejecución crea la línea base (out/baselines/home.png) y pasa.

• Las ejecuciones posteriores comparan capturas de pantalla de Chromium real píxel a píxel; las diferencias superiores a threshold (por defecto 1 %) hacen fallar la compilación.

• Una imagen de diferencias resaltada en rojo va a out/diffs/ y se incrusta en el informe HTML.

• ¿Un cambio esperado? Actualiza las líneas base en lugar de fallar: dsh-verify --spec spec.json --update-baselines.

• Acota una región con "selector", ajusta el ruido con "tolerance" (por canal, por defecto 10).

Acciones: capture_baseline (guardar una línea base explícitamente), expect_screenshot (comparar contra la línea base).

Listas de verificación redactadas por IA (las escribe un LLM, un navegador real las impone)

¿No quieres escribir el JSON a mano? dsh-verify gen aprende la página en un navegador real, hace que un LLM redacte la lista de verificación según tus requisitos y luego la ejecuta en Chromium real:

export DEEPSEEK_API_KEY=sk-...   # or pass --api-key / --provider openai

dsh-verify gen --url http://localhost:3000 \
  --prompt "dark-mode toggle must actually change the background color" \
  --run

gen: opening http://localhost:3000 in a real browser to learn the page...
gen: page learned (2 buttons, 0 inputs) — drafting checklist...
gen: checklist drafted by deepseek-v4-flash (10 steps) -> dsh-verify.gen.json
gen: executed in real browser -> PASS (10/10)
report: dsh-verify-out/report.html

La IA solo redacta la lista de verificación — nunca juzga el resultado. El mismo motor Chromium determinista ejecuta los pasos, y el JSON se escribe en disco para que puedas revisarlo o editarlo antes de confiar en él.

Requiere Node >= 18 y una instalación de navegador: npx playwright install chromium.

Inicio rápido

npm install
npx playwright install chromium   # one-time browser download

# Run the two demo specs back to back
npm run demo:buggy                # → FAIL (exit 1) — missing .dark style caught
npm run demo:fixed                # → PASS (exit 0)

# engine self-tests + full CI flow
npm test                          # node:test suite
npm run ci                        # tests + fixed PASS + buggy FAIL (as proof of detection)

El CI del propio repositorio ejecuta exactamente eso: autotests del motor, y luego verifica que la compilación corregida pasa y que la compilación con errores falla — así la herramienta se verifica a sí misma en cada push (.github/workflows/ci.yml).

Salida legible por máquina

node bin/verify.mjs --spec demo/fixed.json --out /tmp/out --json
# {"verdict":"PASS","passed":11,"total":11,"failed":[],"report":"/tmp/out/report.html"}

Ejecutar muchas especificaciones

node bin/verify.mjs --spec 'specs/*.json' --out reports/
# [PASS] specs/home.json (5/5)
# [FAIL] specs/cart.json (4/5)
#   ❌ expect_text #total: got "0" want "99"

Cada especificación recibe su propia carpeta reports/<name>/; la salida es 0 solo si todas pasan.

Formato de la especificación

Campos de nivel superior: title, serve (directorio estático), base (URL de destino), browser (opcional: chromium | firefox | webkit, por defecto chromium), steps.

{
  "title": "my app",
  "serve": "dist",
  "browser": "chromium",
  "steps": []
}

Anula por ejecución con --browser firefox.

{
  "title": "my acceptance check",
  "serve": "demo/fixed",
  "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" }
  ]
}

Acciones

El par capture_style → expect_style_changed es el corazón de este proyecto: verifica lo que ve el usuario, no lo que dice la lista de clases del DOM.

Evidencia en vivo

Las dos capturas siguientes son resultados reales de dsh-verify contra las dos compilaciones de la misma demo (Chromium, 1280×800, después de hacer clic en el interruptor):

Compilación con errores — interruptor pulsado, fondo sin cambios:

Compilación corregida — interruptor pulsado, tema cambiado:

Informes completos paso a paso: informe con errores · informe corregido.

Docker (Chromium fijado a una versión)

docker build -t dsh-verify .
docker run --rm -v "$PWD:/app" dsh-verify --spec demo/fixed.json --out /app/reports

Usa mcr.microsoft.com/playwright:v1.62.1-jammy para que la compilación de Chromium coincida con la versión de Playwright — sin descarga del navegador en el momento de construir la imagen. (Construido y documentado; verificado localmente, todavía no en un host Docker).

Por qué nada más hace esto

Investigamos la comunidad de herramientas para agentes antes de construir esto. La "verificación" existente para entregas de agentes es principalmente:

• Comprobaciones de humo de plugins/instalación — si una habilidad se instala, si existe una CLI (por ejemplo, herramientas de descubrimiento de plugins).

• Lint estático / pruebas unitarias — validan el código que escribió el agente, no el comportamiento que experimenta el usuario.

• Agentes solo de capturas de pantalla — miran una imagen, no afirman un comportamiento.

Ninguno de ellos ejecuta un navegador real contra el artefacto y responde: "Cuando hago clic en este botón, ¿ve el usuario el cambio?" Ese es el nicho que llena dsh-verify — deliberadamente pequeño, sin framework, especificación JSON de entrada, veredicto de navegador de salida.

Hoja de ruta

• expect_console_errors / expect_network_errors — sin errores de consola, sin solicitudes 4xx/fallidas

• --json salida de veredicto para registros de CI; pasos fallidos impresos en stdout

• Flujos de varias páginas y expect_navigation (esperar URL después del clic)

• --spec glob (ejecutar muchas especificaciones, un veredicto agregado)

• Imagen de Docker con Chromium fijado (mcr.microsoft.com/playwright:v1.62.1-jammy)

• Manifiesto del plugin DSH (dsh plugin add dsh-verify)

• Servidor MCP — verificar desde Claude Code / Cursor / Copilot (verify_spec / verify_url / generate_and_verify)

• Listas de verificación redactadas por IA — dsh-verify gen (la LLM redacta, el navegador determinista aplica)

• GitHub Action — aceptación de CI en un solo paso con artefacto de informe

• Regresión visual — líneas base de capturas de pantalla a nivel de píxel (capture_baseline / expect_screenshot)

• Matriz de múltiples navegadores — --browser / spec.browser: chromium, firefox, webkit (todo verde en CI)

• Viewports móviles

• Generación de especificaciones por IA a partir de un requisito en lenguaje natural sin una página en ejecución

Licencia

MIT