egutierrez
626d06327c
New domain `browser` under frontend/functions/ with 6 Playwright helpers: - pw_launch_browser: chromium + context + page bootstrap with storageState support and baseUrl navigation. - pw_kanban_login: authenticates a Page against /api/auth/login; sets the kanban_session cookie via shared storageState; verifies login page no longer visible after navigation. - pw_drag_drop: human-like pointer drag (mousedown + activateOffset + stepped move + mouseup) compatible with @dnd-kit/core's 8px activation threshold; supports hoverMs for time-based dropzones. - pw_keyboard_sequence: ordered focus/type/press/wait steps for scripting realistic input flows (typing then arrow-key navigating autocompletes). - pw_wait_predicate: thin wrapper over page.waitForFunction with friendlier defaults and custom error messages. - pw_assert_class: poll-based assertion that a Locator has/lacks a CSS class within a timeout; useful for visual-state checks. Each function ships with vitest tests (5-8 cases each) covering both happy and error paths, plus self-documenting .md (Ejemplo + Cuando usarla + Gotchas + frontmatter with params/output schema). Adds frontend/functions/package.json with `"type": "module"` so consumers can ESM-import the .ts files from anywhere in the registry (Playwright's tsx loader respects nearest package.json). Capability page docs/capabilities/playwright.md documents the group with a canonical end-to-end example, frontiers, prerequisites, and gotchas. Index updated. First consumer (issue 0088): apps/kanban requester-input.spec.ts. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
87 lines
4.2 KiB
Markdown
87 lines
4.2 KiB
Markdown
# 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).
|