wiki: E2E Visual Testing — pipeline 3-tier (Playwright + Gemma vision)

E2E-Visual-Testing.md

@@ -0,0 +1,98 @@
+# E2E Visual Testing
+
+Pipeline de revisión visual/funcional de feadulta (y otros WP/web locales) con coste mínimo en tokens de Claude.
+
+Implementación: `tools/e2e/` del repo. Issue de diseño: [#37](../issues/37).
+
+## Objetivo
+
+Validar a escala que las páginas y posts cargan correctamente (sin imágenes rotas, sin 4xx, sin console errors) sin abrir el navegador uno a uno y sin pasarle screenshots a Claude (que es caro).
+
+## Arquitectura 3-tier
+
+| Tier | Quién | Cuándo | Coste tokens Claude |
+|---|---|---|---|
+| **1. Programático** | Playwright local | Siempre | **0** |
+| **2. LLM local vision** | Gemma 4 vision en LM Studio (`http://172.19.128.1:1234/v1`) | Solo cuando Tier 1 marca regresión o el usuario lo pide | 0 (compute local) |
+| **3. Claude** | Lee `report.md` (texto) | Solo cuando hay que decidir/arreglar | Mínimo |
+
+**Principio:** los problemas reales (imagen rota, link 404, render fallido) son deterministas. El LLM solo aporta opinión visual y solo se invoca bajo demanda.
+
+## Tier 1 — checks que cubren el 95%
+
+Por cada URL, Playwright captura:
+- HTTP status de la página y de cada subrequest
+- `console.error` / `console.warning`
+- `pageerror` (JS uncaught)
+- Requests con status ≥ 400 (img, mp3, css, js…)
+- `<img>` con `naturalWidth==0` (broken aunque devuelvan 200)
+- `<title>`, primer `<h1>`, word count
+- Screenshot full-page
+
+Severity automática:
+- `OK` — sin problemas detectados
+- `WARN` — imágenes rotas, requests 4xx, console errors
+- `FAIL` — HTTP ≥ 400 o error de navegación
+
+## Tier 2 — Gemma 4 vision bajo demanda
+
+`tools/e2e/ask-vision.js` envía una captura PNG + prompt al endpoint LM Studio (`http://172.19.128.1:1234/v1`, modelo `google/gemma-4-e4b`).
+
+Útil cuando hace falta opinar visualmente (maquetación, estética, "se ve raro"). Vision en local confirmada — el modelo reconoce escenas correctamente. Tiempo ~10s por captura, ~1000 tokens locales por respuesta.
+
+Modo auto: para cada URL con severity ≠ OK del último run, pregunta a la vision y consolida en `vision.md`.
+
+## Comandos rápidos
+
+```bash
+cd tools/e2e
+
+# Suite completa
+node run.js feadulta
+
+# Un solo target
+node run.js feadulta home-es
+
+# Vision ad hoc
+node ask-vision.js out/feadulta/latest/post-tolle-44247.png \
+  "¿Se ve la imagen del autor? ¿Hay placeholders rotos?"
+
+# Vision auto sobre todos los WARN/FAIL del último run
+node ask-vision.js --auto out/feadulta/latest
+```
+
+## Output
+
+```
+tools/e2e/out/<site>/<timestamp>/
+  report.json    # datos crudos (~10-50 KB)
+  report.md      # tabla legible para humano + Claude
+  vision.md      # (opcional) opinión visual de Gemma 4 sobre WARN/FAIL
+  vision.json    # (opcional) misma info en JSON
+  <slug>.png     # screenshot full-page por URL
+tools/e2e/out/<site>/latest -> <timestamp>   # symlink al último run
+```
+
+## Suite inicial (feadulta)
+
+Definida en `tools/e2e/sites/feadulta.json`. Cubre:
+- 5 portadas Polylang (ES, EN, FR, IT, PT)
+- EFFA hub
+- Carta de la semana
+- Categoría Evangelios
+- Listado de autores
+- Post canónico del fix de [#34](../issues/34) (`post-tolle-44247`)
+- 3 posts del delta 2026-03/05 ([#36](../issues/36))
+
+Añadir URLs: editar el JSON; sin tocar código.
+
+## Añadir un sitio nuevo (ytsummaries, triptyk, joomla-php83…)
+
+Crear `tools/e2e/sites/<nombre>.json` con misma estructura que `feadulta.json`. El runner es agnóstico al sitio.
+
+## Limitaciones
+
+- Sin baseline/diff todavía. La suite describe estado actual, no compara contra una pasada anterior. Snapshot/pHash es trivial añadirlo después.
+- Gemma 4 a veces escribe razonamiento antes de la respuesta final. `ask-vision.js` parsea "Final Answer:" o la primera etiqueta `[OK|WARN|FAIL]`.
+- Playwright 1.58.2 pineado para reaprovechar browsers ya cacheados en `~/.cache/ms-playwright/chromium_headless_shell-1208`. Subir requiere `npx playwright install`.
+- LM Studio debe estar escuchando en `0.0.0.0:1234` para que el gateway WSL→Windows funcione. Se resetea al cambiar de modelo (ver [Infraestructura](Infraestructura)).