Cómo subir archivos en un navegador remoto con Playwright
TL;DR
Utiliza locator.setInputFiles() para una entrada de archivo real en una aplicación autorizada.
Espera el evento filechooser antes de hacer clic en un control personalizado que abre el selector de archivos.
Utiliza un pequeño Buffer nombrado para una prueba sintética, con un nombre de archivo y tipo MIME que espera el formulario.
Verifica la selección de archivos, el resultado de envío y un recibo del servidor como hitos separados.
Mantén los archivos de prueba libres de secretos y datos personales. Verifica los límites actuales de archivos, rutas y navegadores con el entorno previsto.
Cierra la página que creaste y verifica el fin del navegador gestionado cuando su trabajo esté completo.
¿Cómo carga Playwright un archivo en un navegador remoto?
Playwright carga un archivo configurando la entrada de archivo del navegador o suministrando archivos a un selector capturado. El trabajador comienza con los bytes de la configuración y la página inicia la acción de la aplicación. Aún necesitas validar lo que la aplicación recibió y si la transacción objetivo se comprometió. Nstdata proporciona sesiones de Chromium gestionadas que pueden ser controladas a través de un cliente Playwright adjunto.
Una prueba simple puede mostrar un nombre de archivo elegido y aún así fallar al transmitir el archivo. Por ejemplo, el front end muestra una selección válida mientras que una carga en segundo plano recibe un rechazo del servidor. Comienza con un formulario autorizado, un pequeño archivo sintético y un recibo del servidor conocido. La guía de automatización de formularios de Playwright cubre la misma separación entre hacer clic en Enviar y probar un resultado comprometido.
¿Cuándo deberías usar una entrada de archivo o un selector?
Utiliza la entrada de archivo cuando la página exponga input[type="file"] con una etiqueta accesible identificable o un localizador estable. Utiliza el evento del selector de archivos cuando la aplicación abra el selector a través de un botón y la entrada sea transitoria. El método apropiado depende de cómo la página autorizada ofrezca la selección de archivos.
Archivo sintético correcto seleccionado y recibo esperado después de enviar
Selector activado por un botón
page.waitForEvent('filechooser') y chooser.setFiles()
El clic abre el selector pretendido y la aplicación acepta el archivo
Carga inmediata después de la selección
Entrada de archivo o selector dependiendo de la UI
Espera el marcador de finalización duradero de la aplicación
Flujo de trabajo de múltiples archivos
Suministra los archivos esperados solo si la entrada los admite
Confirma el conjunto completo aceptado y maneja el rechazo parcial
La documentación de entrada de Playwright describe rutas y cargas de archivos en memoria. La referencia de API de FileChooser documenta el suministro de archivos después del evento del selector. Un Buffer nombrado hace que los bytes de configuración sean autónomos y evita depender de un archivo copiado en el sistema de archivos en tiempo de ejecución. Verifica la ruta de transferencia y cualquier límite aplicable antes de usar activos reales.
¿Qué deberías preparar para una prueba de carga?
Prepara un origen de prueba aprobado, contenidos de archivo sintético y una regla de aceptación verificable de forma independiente. Registra la etiqueta del campo, tipo de archivo, tamaño permitido y formato esperado del nombre de archivo o recibo. Alinea estos detalles con la aplicación que tienes permiso para probar. Una vista previa visible es útil como señal intermedia. Un recibo o registro de la aplicación prueba si el servidor aceptó el archivo.
Elige también un caso de rechazo esperado, como un nombre de archivo válidamente enviado pero inaceptable. Utiliza la política de pruebas existente de tu aplicación y una carga pequeña acotada, particularmente si la acción escribe datos. Establece un propietario de limpieza para los artefactos de prueba fuera del navegador, ya que cerrar un navegador puede dejar registros guardados en la aplicación.
¿Cómo adjuntas y envías un archivo sintético?
Inicia la configuración complementaria, conecta un navegador y envía la pequeña carga de prueba a la página de revisión fija. Este ejemplo utiliza Node.js 22 y playwright-core@1.65.1. Utiliza npx playwright-core install chromium y node fixture.mjs para una ejecución local. La configuración se vincula a 127.0.0.1 y sirve /upload en el puerto 4173 por defecto.
Paso 1. Confirma el objetivo y formato del recibo
La aplicación local acepta un archivo llamado fixture.txt que contiene 15 bytes. Escribe un recibo después de que la API lea el archivo, por lo que la prueba puede distinguir el reconocimiento correcto de un control vacío. Confirma que el objetivo utilice el origen previsto y la cuenta de sandbox antes de elegir un archivo. Configuración de automatización del navegador.
Paso 2. Prepara el cliente del navegador
Guarda los módulos de compañero. Una ejecución local lanza Chromium directamente. Una prueba aislada de cliente remoto puede usar la dirección CDP de bucle invertido del verificador. Para una ejecución administrada, utiliza una sesión autorizada lista, una aplicación de prueba aprobada accesible por el navegador en la nube y la configuración documentada NSTDATA_API_KEY, NSTDATA_SESSION_ID y opcionalmente NSTDATA_TEAM_ID. Mantén la clave separada de la credencial CDP emitida. El navegador local y las ramas CDP locales ejercen la operación del cliente. La rama administrada requiere la autorización de tu propio espacio de trabajo y un fixture equivalente.
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. Adjuntar la carga de prueba
Guarda el ejemplo como upload.mjs. Inicia el servidor de prueba, luego ejecuta node upload.mjs. El script envía un nombre, tipo MIME y Buffer a la entrada etiquetada. Utiliza una etiqueta de control exacta y envía una vez. Si tu página autorizada real expone solo un selector, registra la promesa de evento antes de hacer clic en su botón, luego llama a setFiles() con la carga verificada.
Utiliza el resultado asociado con el archivo provisional enviado y verifica lo que fue aceptado. Aquí el servidor informa el nombre del archivo y los bytes y el script emite un registro compacto aceptado. Una aplicación de producción puede usar un ID de carga, un estado de escaneo pendiente o un artefacto persistente. Espera cualquier señal que defina la aceptación en esa aplicación. La documentación sobre la capacidad de acción de Playwright describe por qué una acción exitosa espera, lo cual es distinto de lo que la aplicación hace después.
[Captura de pantalla: Muestra el formulario de prueba con el archivo sintético seleccionado y el recibo reconociendo su conteo de bytes.]
¿Por qué se puede seleccionar el archivo mientras la carga aún falla?
Un archivo puede aparecer en la entrada incluso cuando la aplicación lo rechaza o no ha terminado de procesarlo. Verifica la etapa que produjo la última señal confiable. Un tiempo de espera en el localizador apunta a la página o control. Un error del servidor después de seleccionar el archivo apunta a la validación del formulario, la solicitud o el procesamiento en backend. Registrar contenidos de archivo en bruto añade poco valor diagnóstico.
Síntoma
Qué inspeccionar
Respuesta segura
La entrada se agota
Etiqueta, página correcta, límite del iframe
Localiza la entrada prevista dentro de la página aprobada
El evento del selector nunca aparece
Comportamiento del control y orden de registro de eventos
Registra el evento correcto antes de la acción
Tamaño de archivo incorrecto
Datos del fixture y codificación
Compara los bytes esperados con el recibo del servidor
Recibo ausente después de la presentación
Resultado de la solicitud y registro de la aplicación
Concilia antes de volver a presentar
La guía de consola de navegador y depuración de red ayuda a distinguir un resultado de UI visible de un fallo de respuesta o transporte. Cuando tu objetivo utiliza un escaneo en segundo plano, retiene el ID de carga y consulta su estado seguro documentado en lugar de enviar el archivo nuevamente.
¿Cómo debería manejar un trabajo de carga un error de validación?
Un trabajo de carga debería preservar el intento original y clasificar la respuesta antes de enviar más bytes. Ante un rechazo de fixture, conserva el nombre de archivo seguro, el tamaño esperado, la categoría de respuesta y el estado del recibo de la aplicación. Ejecuta una carga sintética deliberadamente rechazada con un campo cambiado y verifica que la UI informe el rechazo sin crear un registro aceptado. Si la primera solicitud pudo haber tenido éxito y el recibo está ausente, consulta la aplicación utilizando su identificador de carga u otra vista de estado de solo lectura.
Vincula cada prueba negativa a un pequeño archivo en un entorno explícitamente aprobado para el rechazo de fixture. Almacena un breve registro de diagnóstico y limpia cualquier dato de prueba persistente utilizando el procedimiento de limpieza previsto del objetivo.
¿Cómo encaja Nstdata Cloud Browser en la QA de carga?
Nstdata Cloud Browser proporciona el tiempo de ejecución de Chromium gestionado para un flujo de trabajo de archivo autorizado. Un script de Playwright aún construye la entrada de archivo, realiza la acción del formulario prevista y valida lo que registra la aplicación. Live View o diagnósticos de navegador permitidos pueden ayudar a un operador a investigar una carga que pasa por varias fases de UI. El acceso a la aplicación objetivo, las restricciones del archivo y la eliminación de datos de prueba almacenados siguen siendo parte del diseño de tu aplicación.
Conexión remota. Utiliza el flujo de trabajo CDP soportado con una sesión propia y una página objetivo verificada.
Fixture reproducible. Mantén una pequeña carga de bytes aprobada en el worker y confirma el recibo esperado del servidor.
Limpieza intencionada. Cierra la página que posees y detén el navegador gestionado por separado; elimina registros de prueba a través de la ruta aprobada de la aplicación.
¿Qué debería demostrar una prueba de carga de humo repetible?
Una prueba de humo de carga repetible debería demostrar que se seleccionó el archivo esperado, que el servidor lo aceptó una vez y que el navegador y los artefactos de la fixture guardada habían identificado a los propietarios de limpieza. Comience con la muestra más pequeña permitida y verifique tanto un recibo exitoso como una falla de validación. Cuando un resultado intermitente necesite revisión, utilice el flujo de trabajo de reproducción de sesión del Cloud Browser con datos sintéticos y retención aprobada.
Q: ¿Puede Playwright adjuntar un Buffer a una entrada de archivo?
Sí. Utilice un objeto con name, mimeType y buffer para la API de entrada de archivo documentada.
Q: ¿Qué pasa si el botón de carga abre un selector nativo?
Espere el evento filechooser de la página antes de hacer clic, luego suministre la carga del archivo a través del selector devuelto.
Q: ¿Una vista previa del archivo demuestra que el servidor lo aceptó?
Verifique un recibo de aplicación duradero o estado. Una vista previa demuestra principalmente que el cliente sabe qué archivo se seleccionó.
Q: ¿Debería intentar enviar nuevamente si se perdió la respuesta?
Inspeccione primero el registro de carga original. Repita el envío solo cuando pueda establecer un resultado seguro bajo las reglas de la aplicación.
Q: ¿Puede una sesión en la nube abrir la URL de la fixture local?
Un navegador en la nube tiene su propio entorno de red. Utilice una fixture de staging equivalente aprobada que el navegador en la nube pueda alcanzar, o ejecute la prueba en la ruta del navegador local.
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.