Control UI E2E

¿Qué hace Control UI E2E?

Diseño de Control UI con comentarios + flujos reales en el navegador con datos deterministas de Gateway.

Prueba de Estrés de UI

• Cambios sustanciales en la UI: construye una galería HTML local de prueba de estrés al inicio; permite al usuario comparar estados significativos y dar comentarios sobre ejemplos concretos.
• Úsalo para diseños, interacciones, componentes con múltiples estados. Pequeñas ediciones de texto/iconos pueden omitirse cuando la galería no añade una comparación útil.

1. Deriva ejemplos de los componentes afectados y los contratos de datos. Cubre los estados relevantes: normal, carga, vacío, error, no disponible, permiso, seleccionado, expandido; texto largo/contenido denso donde estresen el diseño. Muestra estados mutuamente excluyentes por separado; etiqueta los estados propuestos que la implementación actual no soporta.
2. Un resumen HTML navegable en el navegador: IDs de ejemplo estables, etiquetas de estado cortas, suficiente contexto para entender cada ejemplo. Prefiere componentes reales + fixtures simulados deterministas. Etiqueta representaciones estáticas/aproximadas; enlaza la UI en ejecución para interacciones que no puedan reproducir. Galerías generadas: almacenamiento de artefactos propiedad de la tarea; sin commit por defecto.
3. Cada ejemplo: entrada de comentarios etiquetada. Persiste localmente entre recargas con una clave de almacenamiento específica de la galería + IDs de ejemplo estables. La acción Copiar comentarios exporta IDs de ejemplo, etiquetas de estado, comentarios como Markdown/texto plano para que el usuario los devuelva a la conversación.
4. Abre la galería en el navegador de vista previa disponible; comparte la URL/ruta del archivo. Conserva la misma galería, IDs de ejemplo, comentarios existentes a través de iteraciones. Aplica los comentarios del usuario tanto a la galería como a la implementación; mantén la comparabilidad.
5. Antes de solicitar comentarios: inspecciona los ejemplos renderizados en tamaños de ventana relevantes; verifica que los comentarios sobrevivan a la recarga y exporten las etiquetas de ejemplo correctas. Informa estados no soportados/limitaciones de la vista previa.

La galería apoya la revisión de diseño; nunca reemplaza pruebas de comportamiento enfocadas o pruebas de antes/después inspeccionadas de la UI en ejecución. Conserva la prueba final en directorios de captura nuevos debajo, separados de la galería en evolución.

Forma de la Prueba

• Flujos GUI completos: ui/src/**/*.e2e.test.ts.
• ui/src/test-helpers/control-ui-e2e.ts: inicia Vite Control UI + instala Gateway WebSocket simulado.
• Escenarios deterministas. Sin claves de proveedor reales, credenciales de canal reales, Gateway real a menos que el usuario pida explícitamente una prueba con datos reales.
• Lógica de renderizado estrecha: prefiere pruebas .browser.test.ts/unitarias existentes. Carril E2E: enrutamiento, arranque de la aplicación, handshake del Gateway, solicitudes, comportamiento visible de la UI en conjunto.

Comandos

• Apunta a una prueba E2E en el árbol de trabajo de Codex:

node scripts/run-vitest.mjs run --config test/vitest/vitest.ui-e2e.config.ts --configLoader runner ui/src/e2e/chat-flow.messaging.e2e.test.ts

• Carril local completo en checkout normal:

pnpm test:ui:e2e

• Usa instalación de dependencias preparada o checkout normal preparado; nunca reconcilies la instalación compartida mientras otros trabajos la usan.
• Sigue $openclaw-testing: la prueba de desarrollo confiable puede ejecutarse localmente; la prueba remota necesita navegador/plataforma, entorno limpio o una razón de aislamiento de fuente.

Prueba Visual por Defecto

• Cambios de apariencia: evidencia visual de antes/después inspeccionada.
• Otro comportamiento: prueba de límite clara y apropiada; el conjunto de vídeo + captura de pantalla no es obligatorio cuando las aserciones ya demuestran el cambio.
• Aserciones E2E deterministas de Vitest; nunca commits de capturas de pantalla/vídeos generados.
• El conjunto compartido deshabilita la rasterización parcial de Chromium y la rasterización GPU para evitar píxeles de borde dependientes del historial de renderizado observados. Aún se requieren comparaciones exactas repetidas antes de reclamar reproducibilidad.
• Estados transitorios como Guardado: instala page.clock antes del fixture; pausa con pauseVirtualClock; avanza solo el trabajo del fixture necesario para entrar en el estado. setFixedTime solo no pausa los temporizadores. La captura de preparación usa la entrega de diseño nativa sin avanzar el reloj del fixture.
• Imágenes fijas: takeControlUiScreenshotFrame de ui/src/test-helpers/control-ui-e2e-screenshot.ts, contenido semántico explícito + animations: "disabled". Pasa cambios de ventana/objetivo de desplazamiento previsto a través de viewport/scrollTo; verifica el centrado retenido, la intersección ventana/clip de desplazamiento, el diseño/fuentes/imágenes visibles asentadas.
• Pasa todos los localizadores de elementos relacionados en elements; guarda el PNG de la página devuelto + recortes de ese mismo fotograma. Los recortes encierran límites fraccionarios en píxeles PNG medidos; se asercionan dimensiones + límites no modificados. Nunca combines capturas de pantalla de página/localizador separadas como evidencia del mismo fotograma.
• El modo de fotograma actual por defecto + los helpers existentes de ventana/elemento preservan la grabación y el comportamiento de animación muestreado. La preparación estática permanece activa durante la medición de límites y la captura sin recorte; las pruebas de página completa deben ajustarse a las dimensiones del fotograma de la ventana.
• Después/junto a la prueba E2E enfocada: ejecuta la aplicación Control UI simulada cuando esté disponible, ej. pnpm dev:ui:mock -- --port <port>.
• Controla Chromium con Playwright contra la URL simulada local. Captura los estados necesarios con capturas de pantalla/vídeo corto.
• Usa browser.newContext({ recordVideo: { dir, size }, viewport }), page.screenshot({ path }); cierra el contexto antes de informar la ruta del vídeo.
• Prueba de estado de comando de sesión: capturas solo de ventana, verificadas con Playwright 1.62.1 + Chrome 151.0.7922.34 (Linux Gateway real; macOS arm64 reproducción sintética). Otros propietarios de grabación no migrados/certificados por esta corrección; verifica el contenido de captura de pantalla requerido y el vídeo finalizado por separado. Consulta la ruta de captura verificada y la limitación ascendente.
• Asigna la prueba conservada con createControlUiE2eArtifactDir(scope, parentDir?) de ui/src/test-helpers/control-ui-e2e-artifacts.ts. Cada llamada crea atómicamente un directorio nuevo + registra la ruta real. Precedencia del padre: padre explícito → recortado de la variable OPENCLAW_UI_E2E_ARTIFACT_DIR existente → padre .artifacts/control-ui-e2e del repositorio. Los controles de salida personalizados existentes seleccionan padres específicos; nunca añadas/reescribas variables de entorno para habilitar la captura.
• Asigna durante la prueba/escenario o beforeEach, una vez por intento; scripts independientes una vez por invocación. Pasa el propietario explícitamente a los helpers de captura compartidos. Mantén las puertas, nombres de características/etapas, ventanas, esperas, opciones de grabación originales. Etapas distintas: nombres de archivo distintos. Mantén capturas de pantalla/informes/vídeo juntos.
• Conserva la evidencia exitosa y fallida. Informa las rutas asignadas reales, incluyendo las sobrescrituras de nombre de archivo reubicadas. Elimina manualmente solo los directorios exactos de propiedad después de la revisión; nunca limpies los padres compartidos antes de la repetición. Los fixtures de construcción/medios desechables y el vídeo sin procesar temporal de propiedad pueden mantener la limpieza. Las nuevas capturas sintéticas no pueden recuperar evidencia sobrescrita.
• Diagnósticos de tiempo de espera: hijos nuevos debajo del padre de diagnóstico existente. Mantis retiene cada intento de captura bajo el directorio propiedad de la invocación; rechaza la sobrescritura de informes. Suites de Gateway real, chat-outbox-*, chat-attachment-read-lifecycle: propietarios separados; coordina antes de reclamar retención segura de repetición allí.
• Grabación = validación, no solo captura de demostración. El grabador falla/muestra comportamiento sorprendente: detente, corrige el comportamiento, añade/actualiza prueba de regresión, regraba.
• Prueba visual bloqueada: indica el bloqueador exacto; aún informa evidencia E2E textual.

Patrón de Simulación

Inicia el servidor de la aplicación; instala el simulacro antes de page.goto; verifica el tráfico del Gateway + la UI visible:

const server = await startControlUiE2eServer();
const page = await context.newPage();
const gateway = await installMockGateway(page, {
  historyMessages: [{ role: "assistant", content: [{ type: "text", text: "Listo." }] }],
});

await page.goto(`${server.baseUrl}chat`);
await page.locator(".agent-chat__composer-combobox textarea").fill("hola");
await page.getByRole("button", { name: "Enviar mensaje" }).click();

const request = await gateway.waitForRequest("chat.send");
await gateway.emitChatFinal({ runId: String(request.params.idempotencyKey), text: "Hecho." });
await page.getByText("Hecho.").waitFor();

Se necesita más superficie del Gateway para nuevos flujos: extiende installMockGateway con opciones de escenario tipadas/respuestas de método.

Evidencia del Inspector de Ejecución

• Recoge con withControlUiRunInspector de ui/src/test-helpers/control-ui-run-inspector.ts. Posee una página separada; se cierra en éxito/fallo; deja la página de Chat del llamante + borrador no enviado en su lugar.
• preparePage: Gateway simulado o configuración de autenticación por pestaña existente de la campaña. El contexto compartido del navegador no copia el token de almacenamiento de sesión de otra pestaña.
• El helper usa RunInspectorSelector + activityRunInspectorSelectorHref del modelo de componente renderizado, incluyendo el cursor de decisión del recibo seleccionado.
• data-run-id + data-execution-id del panel renderizado: identidad presente devuelta, no solo la URL solicitada. El data-receipt-selector-id del detalle seleccionado = DecisionReceiptDisplayV1.selectorId.
• La identidad faltante/ambigua o la falta de recibos seleccionados no deben contar como coincidencias.
• Los selectores de decisión están separados de la clave de transcripción terminal opcional agent.wait.terminalReceipt.assistantTranscriptIdempotencyKey. Nunca fabriques la clave desde el selector DOM/fila de historial ni afirmes que la evidencia del Inspector repara su ausencia.
• La etiqueta accesible actual del estado de ejecución de la barra lateral: Ejecución activa, no Running.

Grabación Independiente

• Subtítulos narrados, zooms objetivo suavizados, pausas aceleradas: usa habilidad de vídeo de prueba. La plantilla independiente graba evidencia bruta + sidecar de señales, renderiza MP4 subtitulado con ffmpeg del sistema. Mantén la captura bruta; adjunta el vídeo pulido inspeccionado.
• URL de Control UI simulada ya en ejecución: script temporal de Playwright o especificación playwright test; mantén el flujo de grabación enfocado:
  • Abre la URL simulada; interactúa a través de selectores estables data-*/de rol para el usuario; espera estados asercionados, no pausas fijas.
  • Flujos impulsados por solicitudes: verifica la UI visible + tráfico del Gateway simulado. Ejemplo: recuento/fila esperado visible + sessions.list llamado con los search, offset, limit esperados.
  • Pausas cortas solo después de aserciones para un vídeo capturado legible.
  • Vídeo generado: directorio nuevo asignado de la invocación. Nunca commits ni elimines capturas anteriores.