Mocking de red para pruebas propias de automatización del navegador

El mocking de red resulta útil cuando la prueba es propietaria de la página y de la dependencia de aplicación que ejercita. Una respuesta controlada hace reproducibles un estado de carga, una lista vacía, un error de validación o una caída temporal sin esperar a un servicio remoto. El límite forma parte del contrato: el mock es un doble para una dependencia autorizada, no una forma de modificar un sitio de terceros, eludir una política o afirmar que producción se comportó igual.

Empieza por el contrato visible. Nombra la ruta, el método y la forma de la solicitud, el estado esperado y la evidencia que puede conservar la prueba. Decide qué dependencia pertenece a tu equipo y qué integración real requiere otra comprobación. Consulta la guía de Playwright y la guía de descargas y cargas para el ciclo del navegador y los artefactos. La guía de mocking de Playwright y las prácticas de Selenium explican mecanismos, pero ninguna convierte una respuesta sintética en prueba de un servicio remoto.

Define el límite de propiedad

Intercepta solo una solicitud que pertenezca al escenario. Usa una cuenta sintética, un origen de prueba y un patrón estrecho que no capture analítica, autenticación, telemetría ni recursos ajenos. El handler debe comprobar el método y los campos relevantes, devolver una respuesta documentada y guardar solo un resultado breve. No registres cabeceras de autorización, cuerpos completos, cookies, texto de página ni un cuerpo de respuesta de producción copiado solo porque el handler pueda verlo.

Separa la ruta de producción. Coloca los handlers en código de prueba o en un servidor stub de pruebas, actívalos mediante una opción explícita y haz fallar la prueba si esa opción aparece en una compilación de producción. Incluye el nombre del escenario en el resultado para distinguir una respuesta sintética de una integración real. Si un service worker o la caché evita que llegue la solicitud, documenta esa condición. Que el handler no reciba una solicitud describe el camino del navegador, no demuestra que se llamó al servicio.

Define un fixture determinista

Antes de escribir el handler, anota cuatro hechos:

• Entrada: registro sintético, ruta, método y esquema de respuesta propiedad de la prueba.
• Cambio: una condición controlada, como estado 503, lista vacía o demora limitada.
• Observación: estado visible para el usuario y contador breve de coincidencias.
• Limpieza: eliminación de la ruta, cierre del contexto y estado de retención de artefactos.

Una sola condición modificada mantiene el fallo explicable. Si el mismo fixture cambia autenticación, reintentos, caché y datos de base de datos, una aserción correcta no identifica qué contrato se ejercitó. Versiona el esquema junto al test y usa valores que no puedan confundirse con un registro de cliente. Un fixture puede representar un incidente upstream, pero su nombre debe indicar que es sintético.

Elige la API de red mínima

Esta matriz relaciona una pregunta de prueba con una superficie de interceptación y su límite de evidencia. Usa una fila por contrato y evita un handler que capture todo el tráfico.

Pregunta	Playwright	Selenium/WebDriver	Límite de evidencia
Devolver un JSON conocido	page.route('**/api/items', route => route.fulfill({ json }))	Proxy de prueba o endpoint stub propio configurado antes del driver	Estado renderizado para la respuesta sintética
Ejercitar un error del servidor	route.fulfill({ status: 503, body: ... })	Endpoint stub con estado documentado	Interfaz de error y recuperación, no salud del servicio
Simular latencia	route.fulfill({ delay: 250, ... }) o stub controlado	Proxy o stub demora solo la ruta nombrada	Transición de carga y manejo de timeout
Observar sin cambiar tráfico	route.continue() y contador redactado	Registro del proxy con metadatos mínimos	Camino de la solicitud, no autorización exitosa
Garantizar limpieza	page.unroute() en finally y cierre del contexto	Detener proxy propio y salir del driver	Ningún handler o estado del worker pasa al siguiente test

No uses una interceptación amplia **/* salvo que la prueba verifique explícitamente una política de red. Un handler amplio puede ocultar recursos faltantes y producir un resultado verde ajeno al recorrido real. Para una sola ruta, comprueba el método, devuelve un fixture pequeño y deja que las demás solicitudes continúen o fallen según el contrato. Una solicitud inesperada debe ser un fallo visible, no una respuesta inventada.

Conserva un fixture de fallo reproducible

El fixture debe cambiar una condición y nombrar el resultado visible esperado. Este ejemplo de Playwright devuelve una caída sintética, conserva el primer fallo de aserción y elimina siempre el handler junto con el contexto:

const context = await browser.newContext();
const page = await context.newPage();
let matched = 0;
await page.route('**/api/items', async route => {
  matched += 1;
  await route.fulfill({
    status: 503,
    contentType: 'application/json',
    body: JSON.stringify({ code: 'owned-test-outage' }),
  });
});
try {
  await page.goto('http://test.local/items');
  await expect(page.getByRole('alert')).toHaveText('Items are temporarily unavailable');
  expect(matched).toBe(1);
} finally {
  await page.unroute('**/api/items');
  await context.close();
}

El fixture demuestra que la página muestra el error y la recuperación documentados para esa respuesta. No demuestra que un upstream real emita 503, que los reintentos sean seguros, que la autorización haya tenido éxito ni que un registro remoto quede intacto. Conserva el código sintético y el esquema junto al test. Nunca copies secretos de producción en un fixture.

Si configuración, aserción y limpieza pueden fallar, conserva el primer error y registra la limpieza en un campo separado. Un error posterior de cierre no debe sustituir la causa del fallo de página. Un reintento es un contexto y un intento nuevos; que después pase no demuestra que la primera solicitud no tuvo efecto remoto.

Decide cuándo necesitas realidad

El mocking es una decisión acotada. Usa esta tabla antes de añadir un handler:

Propósito de la prueba	¿Mock?	Motivo
Estado de carga, vacío, validación o caída propio de la página	Sí	La entrada determinista repite el contrato de interfaz
Comprobar serialización y contrato cliente-servidor	Normalmente no; usa integración propia	El mock no detecta deriva de esquema o transporte
Validar pago, identidad u otra operación irreversible	No para la aserción final	Solo el servicio autorizado establece el resultado remoto
Reproducir un incidente upstream conocido	Sí, con fixture nombrado	La condición sintética es explícita y revisable
Sondear o modificar un tercero	No	Fuera de propiedad y autorización

Combina pruebas mockeadas frecuentes con algunas integraciones reales aprobadas. La prueba mockeada puede ejecutarse en cada cambio; la integración comprueba que ruta, cabeceras, esquema, autorización y política del servicio siguen alineados. Separa nombres y recibos para que un pase sintético no oculte un fallo real. Una respuesta visible del navegador no es evidencia de facturación, cambio de cuenta, borrado de datos ni disponibilidad remota sin evidencia del propietario del servicio.

Aísla contextos, datos y artefactos

Crea un BrowserContext nuevo cuando cookies, almacenamiento, permisos, caché o service workers influyan. Cada worker necesita un directorio de artefactos privado e identificadores sintéticos. El contexto evita mezclar estado gestionado por el navegador, pero no aísla una base de datos, cola o proxy compartidos. Usa registros independientes o serializa la mutación mediante una operación admitida por la aplicación.

Trata archivos de fixture y etiquetas de ruta como entradas propias. Puedes copiar una base de solo lectura a un directorio del worker, pero un resultado incompleto no debe reemplazarla mientras otro worker la lee. Separa capturas, traces y contadores, y aplica la política de retención normal. Un recibo corto solo necesita escenario, ruta coincidente, clase de respuesta, resultado visible y estado de limpieza.

La limpieza debe estar en finally: elimina la ruta, cierra páginas y contextos, detén el proxy propio y registra el error junto a la aserción. Si un service worker o la caché sirve otra respuesta, registra ese camino observado y cambia deliberadamente la preparación del fixture. No amplíes la interceptación solo para forzar una coincidencia.

Mantén separado el tráfico de producción

Usa un hostname de prueba o un modo de pruebas admitido por la aplicación, identidades sintéticas y un almacén de datos separado cuando sea posible. Haz explícito el cambio a mocking en la configuración del runner y en los registros de CI. La compilación de producción no debe importar handlers de prueba, y una comprobación smoke debe fallar cerrada si aparece una opción de prueba. Es un límite de despliegue, no solo una convención de nombres.

Cuando necesites una integración real, usa la cuenta aprobada por el propietario del servicio y su política de retención. No reutilices un recibo mock como prueba de esa integración. Compara el contrato visible y etiqueta qué hechos proceden del navegador y cuáles del servicio. Si la ruta real no está disponible, registra la condición externa en lugar de sustituirla por un pase sintético.

Capacidad y limitación de BotBrowser

BotBrowser proporciona BrowserContexts aislados para repetir un escenario autorizado con cookies, almacenamiento y permisos separados, pero no verifica la base de datos del servicio ni garantiza efectos remotos.

BotBrowser puede proporcionar un BrowserContext aislado con estado separado del navegador para una prueba autorizada. Es útil cuando un fixture de red necesita cookies, almacenamiento, permisos o estado limpio de service worker conocidos. BotBrowser no decide qué rutas puede interceptar una prueba, no convierte el tráfico de terceros en tráfico propio y no verifica la base de datos, facturación, autorización ni efectos secundarios del servicio remoto. BotBrowser no garantiza disponibilidad de producción ni resultados remotos. El propietario de la prueba aporta datos sintéticos, controla el handler, cierra el contexto y solicita evidencia al propietario de la aplicación fuera del límite del navegador.

Mantén capacidad y limitación en el mismo informe. Registra propósito del contexto, versiones de navegador y framework, ruta coincidente, clase de respuesta, resultado visible y recibo de limpieza. Indica que el resultado procede de una dependencia sintética. Un pase mock no es prueba de disponibilidad de producción, autorización o transacción empresarial. Un contexto limpio tampoco prueba que se revocó una sesión de servidor o se vació una cola remota.

Revisa el límite antes de fusionar

Comprueba que el handler coincide con una ruta propia, que el fixture cambia una condición, que el tráfico no coincidente sigue una política intencionada y que la limpieza corre tras fallos de configuración y aserción. Ejecuta un éxito mock, un fallo forzado y una integración real aprobada cuando el contrato lo exija. Inspecciona ruta y recibo, no un cuerpo de solicitud volcado.

Pide confirmar cuatro no-afirmaciones: el fixture no modifica terceros; la respuesta no demuestra salud upstream; el aislamiento del navegador no borra datos de servidor; y un reintento no elimina la incertidumbre del primer intento. Así la evidencia de red sigue siendo útil, privada y proporcional al comportamiento probado.

Define la propiedad de la ruta antes de elegir la sintaxis. Una URL puede pertenecer a un proveedor u otro equipo. Escribe el propietario y el entorno aprobado. Si no está claro, deja la solicitud en una integración aprobada y afirma solo el comportamiento autorizado.

La autenticación también necesita una frontera clara. Usa sesiones sintéticas del entorno de pruebas, representa los roles aprobados y no copies sesiones de clientes. Un 401 o 403 mock comprueba la interfaz, pero no prueba la decisión de un motor real.

Elige deliberadamente cómo tratar la caché. Limpiarla estabiliza el fixture; conservarla permite comprobar respuestas cacheadas. Registra la elección y si coincidió la ruta. Si la caché responde antes del handler, conserva esa observación y no amplíes el patrón.

En ejecución paralela, cada worker necesita un recibo, archivo temporal y registro sintético propios. El contexto protege el estado del navegador, pero los datos de aplicación necesitan una clave independiente o una regla de serialización aprobada.

Haz explícita la coincidencia: método HTTP, ruta y parámetros del escenario. Una ruta para todos los métodos puede convertir una escritura en una respuesta sintética. Una regla sin versión puede ocultar una actualización. Las reglas pequeñas facilitan la revisión y muestran solicitudes inesperadas.

Las clases de respuesta son parte del contrato. La respuesta correcta incluye solo los campos necesarios para la página y el error sigue la forma documentada. Campos adicionales ocultan dependencias accidentales; campos ausentes crean contratos no documentados.

Haz observable el tiempo sin fragilidad. Un retraso limitado prueba el indicador de carga, pero la aserción espera una transición y no un sueño fijo. Nombra el retraso en el fixture y distingue un timeout esperado de una ruta sin coincidencia.

Usa un recibo común en mocks e integraciones: escenario, ruta, método, clase de respuesta, estado visible, conteo y limpieza. No incluyas credenciales, cookies, cuerpos completos ni texto privado. Así se compara evidencia sin confundir navegador y servicio.

Los reintentos necesitan una aserción propia. Cada intento es nuevo y conserva el resultado inicial. Si la primera solicitud pudo llegar a un servicio real, marca la incertidumbre. El mock prueba el flujo; la integración aprobada establece el efecto remoto.

Mantén el fixture junto a la aserción que lo explica. Nombra la condición sintética, enlaza el contrato visible y documenta la comprobación real que cubre transporte y servicio.

La autenticación también requiere una frontera explícita. Usa sesiones sintéticas, define roles aprobados y no copies sesiones de clientes. Un 401 o 403 mock comprueba la interfaz, pero no demuestra una decisión real.

Elige deliberadamente la política de caché. Limpiarla estabiliza el fixture y conservarla prueba una respuesta cacheada. Registra la elección y conserva la observación si la caché responde antes del handler.

En paralelo, cada worker necesita su propio recibo, archivo temporal y registro sintético. El contexto protege el estado del navegador, pero los datos de aplicación requieren una clave independiente o serialización aprobada.

Fuentes

• Playwright: Network mocking
• Playwright: Network
• Selenium: Test practices
• BotBrowser: Multi-account isolation