intelica-library-e2e
v1.0.24
Published
Herramental común de las suites E2E (Playwright) del stack de Intelica: config, sesión, discovery de selectores, helpers del shell, datos del ambiente, lectura del Excel exportado y ticketing de Jira.
Readme
intelica-library-e2e
Herramental común de las suites E2E (Playwright) del stack de Intelica.
Antes, cada microfront copiaba ~136 KB de código idéntico en su proyecto de tests —el motor del
discovery, los tres scripts de Jira, la sesión, los helpers del shell y el playwright.config.ts
entero—. Cada copia envejecía por su cuenta y actualizarlas era ir repo por repo. Acá viven una
sola vez y se actualizan con un bump de versión.
No es una librería Angular. No se compila con
ng-packagrni está declarada enangular.json: es Node plano, se compila contscy su consumidor es un proyecto de tests, no una aplicación.
Instalación
npm install intelica-library-e2eDependencia normal, no devDependency. El reusable que publica los tickets de Jira instala con
npm i --omit=dev, que no trae devDependencies: como devDep, el binario intelica-e2e-jira-submit
no existiría en ese job. Y la distinción no cuesta nada, porque el proyecto de tests es privado y
nunca se publica.
@playwright/test es peer dependency (>=1.49.0, por locator.ariaSnapshot() del discovery): lo pone el
proyecto de tests, que ya lo tiene. Por eso tenerlo en este repo no arrastra navegadores a nadie.
Qué expone
| Subpath | Qué da |
| --- | --- |
| intelica-library-e2e/config | defineE2EConfig() — el playwright.config.ts completo; la URL del ambiente sale de BASE_URL |
| intelica-library-e2e/auth | login, ensureAuth, isAuthEnabled, AUTH_STATE — la sesión |
| intelica-library-e2e/shell | switchProfile, setLanguage, logout, ProfileNotFoundError — helpers de la UI compartida del portal (perfil, idioma y cierre de sesión del header) |
| intelica-library-e2e/discovery | runDiscovery({ pages, emptyTexts? }) — el motor del catálogo de anclas (selectors/); la URL también sale de BASE_URL |
| intelica-library-e2e/excel | readExport, readXlsx, buildXlsx — leer el .xlsx que descarga un spec y armar uno para una respuesta controlada (exceljs viene con el paquete) |
| intelica-library-e2e/testdata | data, hasData, requireData — los datos del ambiente, leídos en runtime de tests/<proyecto>/qa-implementation-data.json (la materialización de QA-Implementacion-Datos.md; su ambiente se compara con E2E_ENV) |
| intelica-library-e2e/jira/reporter | el reporter que propone bugs; se referencia por nombre en el config |
| intelica-e2e-jira-submit (bin) | el script que crea los tickets revisados (--reviewed), tras la aprobación de QA |
Cómo se usa en un proyecto de tests
playwright.config.ts
import { defineE2EConfig } from "intelica-library-e2e/config";
export default defineE2EConfig();La URL del ambiente no se fija en el repo: sale de BASE_URL (el .env en local, el environment de GitHub en CI), así la misma suite corre contra qa, development o main. baseURL todavía se acepta como respaldo, pero BASE_URL siempre gana.
Los timeouts tienen los defaults del stack (test 120 s, aserción 10 s, acción 15 s, navegación 30 s) y se ajustan por proyecto sin tocar el resto:
export default defineE2EConfig({
timeouts: { navigation: 60_000 }, // lo que no se pasa, queda con el default
});Si te encontrás pasando el mismo override en varios proyectos, eso es señal de que el default del paquete tiene que cambiar — no cada repo.
discover.config.ts — lo único del microfront: su inventario de rutas. La URL sale de BASE_URL, como en el config.
import { runDiscovery, type PageSpec } from "intelica-library-e2e/discovery";
import type { Page } from "@playwright/test";
const PAGES: PageSpec[] = [
{ path: "/login", auth: false },
{ path: "/dashboard", prepare: async (page: Page) => { /* abrir overlays */ } },
{ path: "/fee/saving-opportunities/opportunities", profile: "Group - Absa" },
];
runDiscovery({ pages: PAGES });profile es el literal exacto del selector de perfiles del header: el discovery cambia a ese perfil antes de abrir la ruta. Se usa cuando, con el perfil por defecto de la cuenta, la vista queda en su estado vacío ("No data to display") y sus tablas y acciones no se renderizan. Sin profile, se cataloga con el perfil activo.
- El perfil no se restaura. Una página sin
profileque se cataloga después de otra conprofilehereda ese perfil. El discovery lo avisa ([discover] <ruta> se catalogó con el perfil heredado "<X>") y lo deja en la cabecera del JSON de la página:"profile": "<X>", "profileInherited": true. Las páginas que declaranprofilellevan"profile"sin la marca. Es solo informativo: dice con qué perfil se fotografió el DOM, porque recatalogar esa página sola (npm run discover -- <ruta>) usaría otro. - Un perfil que no existe deja pendiente solo esa página.
switchProfilelanzaProfileNotFoundError(El perfil "<X>" no existe para el usuario en sesión. Perfiles disponibles: …); la página queda conselectors: {}y ese motivo en su_review(ypending: trueen el índice), y el discovery sigue con las demás. profile+auth: falsees un error de configuración: las páginas públicas se catalogan antes del login, sin perfiles. El discovery aborta antes de abrir el navegador.
En un spec, switchProfile(page, "<perfil>") falla con el mismo ProfileNotFoundError en vez del timeout genérico del locator.
Qué escribe el discovery
npm run discover cataloga todas las páginas de PAGES; npm run discover -- <ruta o slug>, solo esas. Escribe en selectors/ (se commitea), un archivo por página con el slug del path sin query (/fee/detail/12 → fee-detail-12; file: en el PageSpec si dos rutas chocan):
| Archivo | Qué trae |
| --- | --- |
| <página>.json | solo anclas: cada data-testid y cada #id puesto por el dev (los autogenerados —pn_id_*, p-*, cdk*, numéricos— no). Por ancla: anchor (testid/id), playwright (el locator), tag, inner (el control interno de un host de componente), text (pista para reconocerlo, nunca para seleccionar), visible, count, unique. Nada por texto: cambia con el idioma (DEC-49) |
| <página>.aria.yml | el ariaSnapshot() de la página tras su prepare: lo que se ve, con o sin ancla. Referencia para reconocer elementos y estructura; nunca selector |
| _index.json | el estado de cada página (selectors, notUnique, pending, empty y, con mapa, missing) y, con mapa, routes: una fila por ruta verificada (photos, expected, missing, notUnique), que es la que se suma; se reconstruye leyendo la carpeta |
- Estado vacío. Si la foto aria contiene alguno de los
emptyTexts(default"No data to display","No hay datos para mostrar","No hay datos"; pasarlos arunDiscoverylos reemplaza), la página lleva"empty": true: se catalogó sin datos y conviene unprofileque los tenga. - Verificación del mapa de anclas, por ruta. Si existe
selectors/_anchors.json(el mapa que arma QA desde el plan y los templates), cada ruta con entrada en él se verifica:verification: { expected, missing, notUnique, photos }—las anclas esperadas que no están o no son únicas; una entrada"match": "prefix"basta con que exista una—. Una ruta puede tener varias fotos (entradas dePAGEScon el mismopathy distintofile, porque un overlay cierra al otro): la verificación junta las anclas de todas sus fotos que hay enselectors/—también las de una corrida anterior— y queda igual en cada una, con sus nombres enphotos. Un ancla falta solo si no sale en ninguna foto, y es no única solo si no sale única en ninguna. Por eso conviene catalogar juntas las fotos de una ruta (npm run discover -- <path>las toma todas). El log cierra con una línea por ruta tocada (🧭 mapa <ruta> (N fotos): X de Y faltan). Sin mapa, se cataloga sin verificar (con un aviso). - Rutas que no se pudieron catalogar (redirigieron o falló su
profile) dejan su archivo conselectors: {}y un_reviewcon el motivo. - Solo la corrida completa borra los archivos de rutas que ya no están en
PAGES.
El contrato completo vive en los skills de QA (Intelica.Context.AI): el mapa en QA/skills/selectors-catalog/references/anchors.md y el catálogo en QA/skills/selectors-catalog/references/catalog.md. Para explorar una página en vivo (sin producir selectores), la cadena usa el MCP de Playwright: QA/skills/e2e-fundamentals/mcp-playwright.md; no es parte de este paquete.
Idioma de la interfaz. setLanguage(page, "ESP" | "ENG") elige el idioma en el selector del header (el p-select del componente <language> del header del portal) y espera a que el combobox muestre Esp / Eng y la cookie language valga ES / EN. Si ya es el idioma activo no hace nada; si la página no tiene header (en blanco o en el dominio de seguridad), primero abre el portal, como switchProfile. El cambio es solo del navegador (cookies language y languageChoice, sin escribir en el servidor) y no recarga la página: el microfront trae sus términos después, así que el spec espera el texto que va a afirmar. La cookie sigue en el contexto: si el test cambió el idioma, lo vuelve al de partida al terminar.
import { setLanguage } from "intelica-library-e2e/shell";
await setLanguage(page, "ESP");
// … afirmaciones en español …
await setLanguage(page, "ENG");Cerrar sesión. logout(page) abre el popover de perfil del header (#headerPerfilGA) y pulsa la opción de cerrar sesión, tomada por estructura (el p-button que sigue a #headerPerfilSettingsGA), no por su texto; espera a que el portal salga del shell. Muta el ambiente: el portal cierra la sesión en el servidor (close-imrp-session), borra las cookies y redirige a la web de autenticación. Un caso que lo usa lleva @muta y corre en un contexto propio, para no dejar sin sesión a los demás tests del worker:
import { logout } from "intelica-library-e2e/shell";
import { AUTH_STATE } from "intelica-library-e2e/config";
const ctx = await browser.newContext({ storageState: AUTH_STATE });
const page = await ctx.newPage();
await logout(page);
// … afirmaciones sobre el estado posterior …
await ctx.close();tests/auth.setup.ts — tiene que estar bajo testDir o Playwright no lo recolecta.
import { test as setup } from "@playwright/test";
import { ensureAuth } from "intelica-library-e2e/auth";
setup("authenticate", async ({ page }) => {
await ensureAuth(page);
});El login aterriza en BASE_URL. A dónde redirige Security tras el login no lo decide BASE_URL: es la página por defecto de AUTH_USER y, si no tiene, el portal de su tipo de usuario (hoy el legacy). login visita BASE_URL después del login y, si la app lo devuelve a la autenticación, falla sin guardar .auth/state.json con el host al que redirigió Security: la causa es la configuración de la cuenta, no los tests. Se arregla dándole a la cuenta de la suite, en ese ambiente, una única página por defecto del portal de BASE_URL (la guía está en ambiente.md de e2e-fundamentals, en Intelica.Context.AI).
Datos del ambiente en un spec: una cuenta, un periodo o una oportunidad que tiene que existir en el ambiente contra el que corre la suite. El valor no va literal en el spec: vive en tests/<proyecto>/qa-implementation-data.json, junto a los specs, y se pide por su alias. Ese archivo es la materialización del bloque json de la nota QA-Implementacion-Datos.md de la base de conocimiento (lo copia el skill qa-implementation-to-playwright) y se versiona con el código, igual que selectors/ y el qa-implementation.json. Trae los datos de un ambiente: el de su campo environment.
import { data, requireData } from "intelica-library-e2e/testdata";
test("@ts-002 @happy-path …", async ({ page }) => {
requireData("periodo-con-datos"); // sin valor → test.fixme con el motivo
const periodo = data("periodo-con-datos");
// …
});- Dónde lo busca: en la carpeta del spec que corre,
tests/<slug>/qa-implementation-data.json. Por eso las tres funciones se llaman dentro de untest(); en unScenario Outline, el valor de cada fila se resuelve dentro de sutest(), no al armar el array. requireData()decide eltest.fixmeen runtime: en cuanto el dato se materializa, el test corre, sin regenerar el spec.- Sin archivo, o con un archivo de otro ambiente (su
environmentno es el deE2E_ENV) → los alias quedan sin valor y sus tests en fixme, con el motivo; el resto de la suite corre. Falla si el archivo no es JSON válido o si suqaImplementationno es el nombre de su carpeta: un dato roto no se convierte en fixmes silenciosos. - Forma del archivo:
{ "qaImplementation": "<slug>", "environment": "qa", "updatedAt": "…", "values": { "<alias>": <valor> } }. Lo escribeqa-implementation-data-resolver: no se edita a mano.
El Excel que exporta una vista. readExport(download) lee el .xlsx de una descarga de Playwright y devuelve sus hojas: sheetNames en orden y rows(hoja) con cada fila como texto (la fila 1 son los encabezados), con el texto que muestra Excel en cada celda, así que una fecha exportada ya formateada se compara tal cual. buildXlsx(hojas) arma un .xlsx para una respuesta controlada (un export de más filas de las que tiene el ambiente) y readXlsx(buffer) lee uno que no vino de una descarga. exceljs viene con el paquete: el proyecto de tests no lo instala. Qué hojas y columnas espera cada export, y cómo se llega a él, es del proyecto (su support.ts).
import { readExport } from "intelica-library-e2e/excel";
const [download] = await Promise.all([page.waitForEvent("download"), exportButton.click()]);
const xlsx = await readExport(download);
// las hojas y los encabezados esperados salen del plan del proyecto (aquí, un ejemplo)
expect(xlsx.sheetNames, "el Excel trae sus dos hojas").toEqual(["<Hoja de datos>", "<Hoja de filtros>"]);
expect(xlsx.rows("<Hoja de datos>")[0], "encabezados de la hoja").toEqual(["<Columna 1>", "<Columna 2>", /* … */]);Variables de entorno
Las lee del .env del proyecto que llama, no del paquete. Todas las rutas que el paquete
escribe o lee (.auth/state.json, selectors/, jira-tickets.json, tests/<proyecto>/qa-implementation-data.json) son relativas a ese proyecto.
| Variable | Para qué |
| --- | --- |
| BASE_URL | la URL del ambiente (el portal contenedor) contra el que corre la suite y el discovery. Obligatoria: sin ella falla al arrancar |
| E2E_ENV | el ambiente (qa, development, main): tiene que ser el environment del qa-implementation-data.json o los casos con datos quedan en fixme. Default qa. En CI la define el workflow a partir del environment |
| AUTH_LOGIN_URL | el interruptor: sin ella no se autentica nada y no se arma el proyecto setup |
| AUTH_USER / AUTH_PASS | credenciales del ambiente. La cuenta necesita además, en ese ambiente, una página por defecto del portal de BASE_URL (ver El login aterriza en BASE_URL) |
| AUTH_TTL_MIN | minutos que se reutiliza la sesión guardada (default 30) |
| JIRA_BASE_URL / JIRA_EMAIL / JIRA_API_TOKEN | solo las necesita el bin de submit; el reporter nunca habla con Jira. Sin ellas (y sin dry run) el submit sale en 1 |
| JIRA_SUBTASK_TYPE | submit: tipo de nivel sub-tarea con el que se crean los tickets. Default Sub-task (Bug) (nombre exacto de Jira) |
| JIRA_MAX_ISSUES | reporter: por encima de esta cantidad de fallos se propone UN ticket resumen en vez de uno por test. Default 10 |
| JIRA_ASSIGNEE_EMAIL | reporter: dev asignado de respaldo si el qa-implementation.json no trae assigneeEmail. Sin default (el ticket sale sin asignar) |
| DRY_RUN | submit: true equivale a --dry-run (la define el reusable e2e-publish-tickets.yml) |
El submit en GitHub Actions
intelica-e2e-jira-submit corre desde la carpeta del proyecto de tests (las rutas de las evidencias del jira-tickets.json son relativas a ella) y, si existe GITHUB_OUTPUT, publica los outputs que leen el summary y la tarjeta de Teams (secret TEAMSWEBHOOKURL) del reusable e2e-publish-tickets.yml de Intelica.Actions:
| Output | Valor |
| --- | --- |
| created / commented / failed | contadores de la publicación. En dry run, o sin propuestas, created=0 |
| total | propuestas del jira-tickets.json |
| keys | claves de Jira creadas o comentadas, separadas por coma |
Sin credenciales, o si no autentican, sale en 1 con failed=total: había propuestas aprobadas y ninguna llegó a Jira, y el run no puede quedar verde. Si el jira-tickets.json existe pero no se puede leer, sale en 1 sin outputs (no se sabe cuántas propuestas había).
Tickets revisados (--reviewed)
El reporter solo propone (jira-tickets.json); a Jira llegan solo los tickets revisados —uno por causa, solo los bugs, redactados por quien diagnostica la corrida— (DEC-58). El submit exige --reviewed para crear: sin él, solo hace dry run.
npx intelica-e2e-jira-submit --reviewed revisados.json --dry-run
npx intelica-e2e-jira-submit --reviewed revisados.jsonrevisados.json es { "tickets": [ … ] } con el mismo formato de TicketProposal, más sources: las huellas de los tests de la corrida que agrupa cada ticket. Las huellas salen de failures del jira-tickets.json, que el reporter escribe para todos los fallos (también en un fallo masivo).
Antes de tocar Jira —también en dry run— el submit valida el archivo entero contra el jira-tickets.json de la corrida y, si algo no cierra, no crea nada y sale en 1:
| Regla | Por qué |
| --- | --- |
| cada sources es la huella de un test que falló en esa corrida | un ticket revisado agrupa fallos reales, no inventa bugs |
| el destino (projectKey, parentKey, assigneeEmail, reporterEmail) es uno de los que la corrida resolvió desde el qa-implementation.json | se reescribe el texto, no el destino |
| las evidencias son imágenes o videos dentro de test-results/ y existen | un trace.zip guarda las cookies de la sesión |
| fingerprint único en el archivo; summary, description y recurrenceComment no vacíos | la huella es el label que deduplica: si el ticket sigue abierto, la próxima corrida comenta en vez de duplicar |
Una corrida escrita por una versión del reporter sin failures no admite tickets revisados.
Un ticket revisado puede traer además jiraFields: campos propios del proyecto de Jira por su nombre en la pantalla de creación, no por su id (que cambia de un proyecto a otro). Por ejemplo, en el proyecto SO:
"jiraFields": { "Environment": ["PROD"], "Type Bug": ["Functional"], "Finding Type": "Defecto (en el producto)", "Bug Cause": ["Business Rule"] }Al crear el ticket, el submit los resuelve contra el createmeta del proyecto y del tipo de sub-tarea, y arma el formato que corresponde (opción, lista de opciones o texto). Un campo que no está en la pantalla, o un valor que no está entre los permitidos, se omite con un aviso en el log. Si Jira rechaza uno al crear, se descarta y se reintenta sin él: el ticket vale más que un campo de clasificación. El dry run los muestra sin validarlos, porque no tiene credenciales.
Por qué así
loginy noensureAuthen el discovery:ensureAuthsolo garantiza que.auth/state.jsonexista y esté fresco; si lo reutiliza no navega, y el navegador del discovery (que no carga ese archivo) catalogaría los redirects a/logincomo si fueran la página.process.envse lee dentro de las funciones: losimportse evalúan antes que eldotenv.config()del módulo que importa.- El proyecto
setupno depende de que exista.auth/state.json: en un clon limpio o en CI no existe al leer el config, y es justosetupquien lo crea. Por lo mismostorageStateva en el proyectochromiumy no enuse.setupcorre sin trace ni video: guardarían lo tipeado, la contraseña incluida. - Trace
retain-on-first-failure: el trace es ~80 % del peso de una corrida; en un bug real los dos intentos fallan igual y en un flaky el primero es el único que muestra el fallo. switchProfileespera#headerPerfilGA, nonetworkidle:networkidledepende de todo el portal (SignalR, long-polls de terceros) y con el ambiente lento agotaba el timeout con el header ya pintado. Tras elegir el perfil espera el eventoloadde la recarga (waitForLoadStateresolvería con el anterior), y si el perfil ya es el activo no espera nada. El perfil se elige por texto exacto porque es un dato del producto, no texto traducido; si no está,ProfileNotFoundErrorlista los disponibles tras una espera corta (la lista llega completa de una vez).- Los helpers del shell no usan
expect: también corren en lospreparedel discovery, fuera del runner.
Publicación
Igual que las librerías Angular de este repo: el workflow
.github/workflows/publish-intelica-library-e2e.yml se dispara al mergear a main cambios bajo
projects/intelica-library-e2e/**, compila con tsc y publica desde dist/intelica-library-e2e.
