# 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.

```ts
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):

```ts
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).