fn_registry/docs/capabilities/playwright.md

playwright

Helpers para tests end-to-end de frontends del registry con Playwright. Wrappers finos sobre la API de Playwright para que los tests queden declarativos y consistentes entre apps.

Funciones del grupo

ID	Firma corta	Qué hace
pw_launch_browser_ts_browser	(opts?: PwLaunchOptions) => Promise<PwHandles>	Lanza chromium + context + page; navega a baseUrl; soporta storageStatePath para pre-auth
pw_kanban_login_ts_browser	(page, {username, password, baseUrl?}) => Promise<void>	POST /api/login, setea cookie de sesión, navega al root y verifica que la pantalla de login desaparece
pw_drag_drop_ts_browser	(page, {source, target, steps?, delayMs?, hoverMs?, activateOffset?}) => Promise<void>	Drag con PointerEvents compatible con dnd-kit (umbral 8px); soporta hoverMs para dropzones temporales
pw_keyboard_sequence_ts_browser	(page, KbStep[]) => Promise<void>	Ejecuta secuencia ordenada de focus/type/press/wait
pw_wait_predicate_ts_browser	(page, predicate, {timeoutMs?, pollMs?, arg?, message?}) => Promise<T>	Espera a que un predicado JS en la página devuelva truthy; mensaje custom en timeout
pw_assert_class_ts_browser	(page, {selector, className, mustHave?, timeoutMs?}) => Promise<void>	Assert (con poll) de que un selector/Locator tiene o no una CSS class

Ejemplo canónico

Test e2e del kanban: login, crea card, navega autocomplete con ↑↓, valida que el modal sigue abierto.

import { test } from "@playwright/test";
import { pw_launch_browser } from "@fn_library/browser/pw_launch_browser";
import { pw_kanban_login } from "@fn_library/browser/pw_kanban_login";
import { pw_keyboard_sequence } from "@fn_library/browser/pw_keyboard_sequence";
import { pw_assert_class } from "@fn_library/browser/pw_assert_class";

test("requester input ↑↓Enter no cierra modal", async () => {
  const h = await pw_launch_browser({ baseUrl: "http://localhost:5180", headless: true });
  try {
    await pw_kanban_login(h.page, { username: "egutierrez", password: process.env.KANBAN_PWD! });
    await h.page.click("[data-add-card]");
    await pw_keyboard_sequence(h.page, [
      { kind: "focus", selector: "input[data-field=requester]" },
      { kind: "type", text: "Enma" },
      { kind: "wait", ms: 200 },
      { kind: "press", key: "ArrowDown" },
      { kind: "press", key: "Enter" },
    ]);
    // Modal sigue abierto:
    await pw_assert_class(h.page, {
      selector: "[role=dialog]",
      className: "mantine-Modal-content",
      mustHave: true,
      timeoutMs: 500,
    });
  } finally {
    await h.close();
  }
});

Drag desde sidebar al board (Issue 1):

await pw_drag_drop(h.page, {
  source: "[data-card-id='abc']",
  target: "[data-column-id='xyz']",
  hoverMs: 0,  // 500 si quieres validar dropzone temporal
});

Cuándo usarla

• App tiene UI compleja (drag-drop, autocomplete, animaciones) que un test backend no cubre.
• Test backend Go ya existe y necesitas un complemento de browser real.
• Cualquier app del registry que sirva HTTP en un puerto local y tenga login por cookie.

Fronteras

• NO sustituye tests unitarios (vitest + @testing-library) — Playwright es lento y caro, úsalo para flujos críticos.
• NO hace mocks de red — usa page.route directamente si necesitas.
• NO incluye fixtures Playwright (test.beforeAll, etc.) — eso lo escribe el consumer.
• playwright y vitest son peer deps; cada app que use el grupo debe pnpm add -D playwright @playwright/test vitest localmente.

Prerequisitos

• App corriendo en baseUrl (ej. http://localhost:5180) antes del test.
• Login disponible vía POST /api/login con {username, password} JSON.
• Selectores estables (data-* atributos recomendados) para drag y assertions.

Gotchas

• dnd-kit requiere 8px de movimiento para activar; pw_drag_drop ya añade activateOffset por defecto.
• pw_kanban_login asume backend kanban; otros backends necesitan un helper análogo.
• pw_assert_class con Locator hace poll manual (no waitForFunction) porque los Locators no serializan a contexto de página.
• Chromium en WSL2 necesita xvfb-run o headless: true (default).