Cómo manejar ventanas emergentes y nuevas pestañas en Playwright
TL;DR
Utilice el evento popup de la página del abridor cuando una acción conocida cree una pestaña o ventana hija.
Use el evento page del contexto del navegador cuando el creador sea desconocido o si desea monitorear intencionalmente todas las nuevas páginas en ese contexto.
Registre la promesa del evento antes de hacer clic y defina cuánto tiempo esperará el cliente.
Verifique el destino y un marcador específico de la tarea antes de interactuar con la nueva página.
Utilice una espera de navegación para la ruta de la misma pestaña y un manejador de diálogos para diálogos de JavaScript.
Cierre solo las páginas que posee la tarea, luego verifique la limpieza de la sesión administrada a través del controlador.
¿Cómo manejas un popup o nueva pestaña en Playwright?
Maneje un popup esperando el evento de la página que lo abrirá, luego trate la página devuelta como un objetivo de automatización separado. Verifique su destino real y el estado de aplicación esperado antes de emitir otra acción. Nstdata proporciona navegadores administrados a los cuales un cliente Playwright compatible puede adjuntarse y gestionar más de una página.
Considere una cola de revisión de staging con un enlace que abre una vista previa de lanzamiento. También está abierta una pestaña de estado no relacionada. Seleccionar el elemento más reciente en context.pages() asume que ningún otro trabajador o página ha creado una pestaña. El diseño más seguro espera el evento del abridor conocido y verifica que la página devuelta muestre el lanzamiento correcto. Para los casos en que alguien abre una página manualmente primero, consulte el workflow de entrega de operador.
¿Qué evento coincide con el comportamiento de su aplicación?
Elija el evento que corresponde a lo que la página realmente crea. Un modal DOM nuevo mantiene la misma página de Playwright y necesita localizadores ordinarios. Un diálogo levantado por JavaScript es un evento separado. Una nueva pestaña es representada por otra página, y una navegación en la misma pestaña cambia la URL de la página original.
¿Cómo capturas la vista previa de lanzamiento prevista?
Capture el popup de la página de revisión conocida y requiera una URL de fixture exacta e identificador de lanzamiento. El ejemplo utiliza un fixture de staging local y una pestaña extra para detectar un error común. Se ejecuta en Node.js 22 y playwright-core@1.65.1. Utilice el compañero fixture.mjs e instale Chromium local con npx playwright-core install chromium para la ruta independiente.
Paso 1. Prepare el abridor y el hijo esperado
Inicie node fixture.mjs. El abridor aprobado es /opener y el hijo esperado es /child. El hijo muestra el encabezado Vista previa de lanzamiento y un marcador para fixture-42. El script también crea una pestaña señuelo para /status. En una aplicación real, derive el destino aprobado y el marcador del ítem de trabajo autorizado antes de iniciar el clic.
Paso 2. Conectar un trabajador al navegador correcto
Guarde los módulos compartidos y elija una ejecución local o la ruta de verificación CDP de loopback. Si está utilizando un navegador administrado, utilice una sesión lista propia y un objetivo aprobado correspondiente que sea accesible desde ese entorno. Configure NSTDATA_API_KEY, NSTDATA_SESSION_ID y opciones de selección de espacio de trabajo. El flujo de trabajo se ha ejercido en Chromium local y CDP de loopback. Necesita un espacio de trabajo autorizado para probar la rama administrada. Guía de automatización de navegador Nstdata.
const root ='https://api.nstdata.io/api/v1/cloud-browser';exportasyncfunctionapi(method, path, body){const key = process.env.NSTDATA_API_KEY;if(!key)thrownewError('Set NSTDATA_API_KEY');const headers ={'x-api-key': key };if(process.env.NSTDATA_TEAM_ID) headers['x-team-id']= process.env.NSTDATA_TEAM_ID;if(body) headers['content-type']='application/json';let response;try{ response =awaitfetch(root + path,{ method, headers,redirect:'error',body: body ?JSON.stringify(body):undefined,signal:AbortSignal.timeout(20_000),});}catch{throwObject.assign(newError('API transport failed; reconcile the original operation'),{retryable:true});}const retryable = response.status===429|| response.status>=500;let result;try{ result =await response.json();}catch{throwObject.assign(newError('Invalid API JSON'),{ retryable });}if(!response.ok|| result.err===true|| result.success===false){throwObject.assign(newError(`Cloud Browser API HTTP ${response.status}`),{ retryable });}if(!result.data)thrownewError('Missing API data');return result.data;}exportasyncfunctionconnection(id){if(!id)thrownewError('Set NSTDATA_SESSION_ID');const path =`/sessions/${encodeURIComponent(id)}`;const session =awaitapi('GET', path);if(session.state!=='ready')thrownewError(`Session is ${session.state}, not ready`);const c =awaitapi('POST', path +'/automation-credentials');if(c.sessionId!== id ||!c.headerName||!c.accessToken||!(Date.parse(c.expiresAt)>Date.now())||newURL(c.cdpUrl).protocol!=='wss:'){thrownewError('Invalid or expired CDP credentials');}return{endpoint: c.cdpUrl,headers:{[c.headerName]: c.headerName.toLowerCase()==='authorization'?`Bearer ${c.accessToken}`: c.accessToken},};}exportasyncfunctionendpoint(){// An isolated local CDP endpoint can test the client without managed credentials.if(process.env.LOCAL_CDP_URL){const url =newURL(process.env.LOCAL_CDP_URL);if(!['127.0.0.1','localhost','[::1]'].includes(url.hostname)){thrownewError('LOCAL_CDP_URL must use loopback');}return{endpoint: url.href,headers:{}};}returnconnection(process.env.NSTDATA_SESSION_ID);}
import{ chromium }from'playwright-core';import{ endpoint }from'./cloud-api.mjs';exportasyncfunctionwithPage(task){const origin =newURL(process.env.APP_ORIGIN??'http://127.0.0.1:4173');const remote =Boolean(process.env.LOCAL_CDP_URL|| process.env.NSTDATA_SESSION_ID);if(!remote && origin.hostname!=='127.0.0.1')throwError('Use the local fixture for local runs');const connection = remote ?awaitendpoint():null;const browser = connection
?await chromium.connectOverCDP(connection.endpoint,{headers: connection.headers,timeout:15_000}):await chromium.launch({args:['--no-proxy-server']});let page;try{const context = remote ? browser.contexts()[0]:await browser.newContext();if(!context)throwError('Expected a browser context'); page =await context.newPage(); page.setDefaultTimeout(8_000); page.setDefaultNavigationTimeout(10_000);returnawaittask(page, origin);}finally{try{await page?.close();}finally{await browser.close();}}}
Paso 3. Registrar el evento y hacer clic
Guarde el ejemplo como popup.mjs, luego ejecute node popup.mjs. La promesa del evento se registra antes del clic en el enlace. El popup devuelto se mantiene en una variable dedicada. El script verifica su ruta y que su contenido se refiera a la revisión de prueba esperada. También prueba que el opener no navegó lejos y que el popup pertenece a esa página. La referencia de la API de Playwright Page documenta la semántica del popup y el opener.
Paso 4. Terminar el flujo de trabajo hijo bajo propiedad conocida
Cierre el hijo y el señuelo creados por el ejemplo. Si otro trabajo posee pestañas en ese tiempo de ejecución, deje esas pestañas solas. Registre de qué página provino el resultado. Detenga la sesión administrada solo cuando el controlador verifique que todo el trabajo autorizado en ella esté completo. La guía de gestión de sesiones del navegador muestra dónde pertenece el apagado.
[Captura de pantalla: Muestre la página de revisión de staging y la vista previa del hijo verificado con ID de lanzamiento sintético. Mantenga otras pestañas y direcciones firmadas fuera de la captura de pantalla.]
¿Por qué el tiempo de espera del popup se agota o apunta a la pestaña equivocada?
Un tiempo de espera de popup suele fallar porque el oyente se retrasa, el abridor es incorrecto, la aplicación navegó en la misma pestaña, o el contenido esperado nunca llegó. Encuentre qué hito ocurrió. Verifique el comportamiento documentado del botón y suscríbase en la página apropiada. Una pestaña puede aparecer antes de que su URL final o contenido esté listo, así que verifique ambos de forma independiente.
Síntoma
Explicación probable
Cómo recuperarse
El evento se agota pero la URL cambió
La página original navegó
Espere a que el destino conocido de la misma pestaña esté disponible, luego verifique el contenido
El evento de contexto eligió una pestaña no relacionada
Otra página la creó
Limite la espera al abridor o correlacione la página devuelta antes de actuar
Se abre una nueva pestaña con una página en blanco
La navegación de destino está pendiente o fallida
Espere a que la ruta y el resultado aprobados estén disponibles con un tiempo de espera limitado
El popup se cierra antes del siguiente paso
La aplicación terminó o rechazó el flujo de trabajo
Lea el recibo del padre o del servidor antes de intentar nuevamente
Destino inesperado o pestaña adicional
El flujo de trabajo difiere del fixture aprobado
Detenga esa acción e investigue con un identificador de página seguro
Si la nueva página es parte de un flujo de trabajo sensible, mantenga su URL completa fuera de los registros y evite registrar pestañas privadas por defecto. La guía de depuración de consola y red ayuda a identificar qué página y ruta realmente produjeron el fallo.
¿Cómo maneja un flujo de trabajo que a veces se queda en la misma pestaña?
Maneje la navegación opcional definiendo dos resultados esperados y agregando una observación limitada para cada uno. Una aplicación podría abrir una vista previa en una nueva pestaña solo para ciertos roles de cuenta. Instrumente el comportamiento real en el entorno de prueba aprobado y mantenga el contrato visible en sus casos. Una configuración que siempre usa un popup aún debería fallar si se retrocede silenciosamente al padre.
Para alternativas genuinas, comience las esperas apropiadas antes de hacer clic y mantenga cualquier oyente limitado a esa acción. Cuando se establezca un resultado, cancele o retire la observación no utilizada de manera limpia para que no afecte el siguiente paso. Verifique el objetivo por separado del tipo de transición. Coincida el origen esperado y la revisión prevista en ambos caminos y mantenga evidencia que muestre qué camino pasó.
¿Cómo apoya Nstdata Cloud Browser flujos de trabajo de múltiples páginas?
Nstdata Cloud Browser proporciona navegadores en la nube administrados para la automatización del navegador y agentes de IA. Use CDP para adjuntarse a la sesión seleccionada y derive la propiedad de la página de la aplicación y el cliente. Live View le da a un operador autorizado una forma de revisar la página activa cuando un flujo se comporta de manera diferente al fixture. El trabajador aún verifica la nueva página y coordina su ciclo de vida con el controlador.
Automatización consciente del contexto. Alquile los objetos de página de un trabajo y valide el abridor exacto o el destino aprobado.
Revisión del operador. Use diagnósticos documentados o Live View si un flujo de varias páginas necesita investigación supervisada.
Limpieza predecible. Cierre solo las páginas creadas por el flujo de trabajo y verifique el apagado administrado a través de su ciclo de vida separado.
¿Qué debería establecer una prueba de regresión de múltiples pestañas?
Una prueba de regresión de múltiples pestañas debería establecer que la acción del usuario esperada creó exactamente la página de destino prevista y preservó o cambió el abridor según lo diseñado. Ejecute una prueba con otra página presente, compare el marcador de la aplicación y provoque un fallo controlado donde el popup no muestre la revisión esperada. Registre el resultado seleccionado en lugar de un conteo general de pestañas.
Para un flujo de captura, agregue capturas de pantalla remotas verificadas solo después de que pueda identificar la página hija prevista y su contenido estable.
Q: ¿Cuál es la diferencia entre los eventos de popup y de página?
El evento de popup pertenece a un abridor conocido. El evento de página en un contexto de navegador puede observar nuevas páginas creadas dentro de ese contexto de manera más amplia.
Q: ¿Playwright necesita que la nueva pestaña esté visualmente enfocada?
Las acciones de Playwright se dirigen al objeto de página que usas. Verifica que el objeto devuelto represente a la página deseada.
Q: ¿Puedes asumir que context.pages().at(-1) es la nueva página?
Evita confiar en el orden de las páginas para la propiedad. Captura el evento correspondiente y verifica el objetivo o el marcador de tarea.
Q: ¿Qué pasa si el enlace permanece en la misma pestaña?
Espera la URL esperada de la página original y verifica el contenido resultante. Una navegación en la misma pestaña no emite un evento de popup de abridor.
Q: ¿Debería cerrar un popup cerrar el navegador gestionado?
Cierra el popup que posees sin terminar el trabajo no relacionado del navegador. Detén la sesión gestionada a través del controlador propietario cuando su trabajo esté hecho.
Marcus Chen
Nov. 20th 2026
Inicia navegadores en la nube bajo demanda
Gestiona huellas digitales y CAPTCHA
Automatiza flujos de trabajo e impulsa agentes de IA
Desde la extracción de datos web y las pruebas hasta la automatización con IA, ejecútalo todo en la nube.