Как загружать файлы в удаленном браузере с помощью Playwright
TL;DR
Используйте locator.setInputFiles() для фактического ввода файла в авторизованном приложении.
Подождите событие filechooser, прежде чем нажимать на пользовательский элемент управления, который открывает выбор файлов.
Используйте небольшой именованный Buffer для синтетического теста с именем файла и типом MIME, ожидаемыми формой.
Подтвердите выбор файла, результат отправки и подтверждение на сервере как отдельные этапы.
Держите тестовые файлы свободными от секретов и личных данных. Проверьте текущие ограничения по файлам, пути и браузеру в намеренной среде.
Закройте страницу, которую вы создали, и проверьте завершение управляемого браузера, когда его работа будет завершена.
Как Playwright загружает файл в удаленный браузер?
Playwright загружает файл, устанавливая файловый ввод браузера или предоставляя файлы захваченному выборщику. Рабочий процесс начинается с байт фиктивного файла, и страница инициирует действие приложения. Вам все равно нужно проверить, что приложение получило и было ли транзакция выполнена. Nstdata предоставляет управляемые сессии Chromium, которые можно контролировать через подключенный клиент Playwright.
Простой тест может продемонстрировать выбранное имя файла и все же не передать файл. Например, интерфейс отображает правильный выбор, в то время как фоновая загрузка получает отказ от сервера. Начните с авторизованной формы, небольшого синтетического файла и известного подтверждения сервера. Руководство по автоматизации форм Playwright охватывает ту же разницу между нажатием "Отправить" и подтверждением выполненного результата.
Когда следует использовать файловый ввод или выборщик?
Используйте файловый ввод, когда страница предлагает input[type="file"] с различимой доступной меткой или стабильным локатором. Используйте событие выбора файлов, когда приложение открывает выбор через кнопку, и ввод является временным. Подходящий метод зависит от того, как авторизованная страница предлагает выбор файла.
Правильный синтетический файл выбран и ожидаемое подтверждение после отправки
Выборщик, вызванный кнопкой
page.waitForEvent('filechooser') и chooser.setFiles()
Нажатие открывает предусмотренный выборщик, и приложение принимает файл
Немедленная загрузка после выбора
Файловый ввод или выборщик в зависимости от интерфейса
Подождите, пока приложение выполнит долговременный маркер завершения
Рабочий процесс с несколькими файлами
Укажите ожидаемые файлы только если ввод их поддерживает
Подтвердите полный принятый набор и обработайте частичный отказ
Документация по вводу Playwright описывает пути и загружаемые в память файлы. Справочник по API FileChooser документирует предоставление файлов после события выбора. Именованный Buffer делает байты фиктивного файла самодостаточными и избегает зависимости от файла, скопированного в файловую систему времени выполнения. Подтвердите путь передачи и любые применимые ограничения, прежде чем использовать реальные активы.
Что следует подготовить для теста загрузки?
Подготовьте утвержденный источник тестирования, синтетическое содержимое файла и независимо проверяемое правило принятия. Запишите метку поля, тип файла, разрешенный размер и ожидаемый формат имени файла или подтверждения. Соответствуйте этим данным приложению, которое вы имеете право тестировать. Видимый предварительный просмотр полезен как промежуточный сигнал. Подтверждение или запись приложения доказывает, было ли подтверждено сервером принятие файла.
Выберите один ожидаемый случай отказа, например, допустимое имя файла, но неприемлемое для передачи. Используйте существующую политику тестирования вашего приложения и небольшую ограниченную загрузку, особенно если действие записывает данные. Установите владельца очистки для тестовых артефактов вне браузера, так как закрытие браузера может оставить записи, сохраненные в приложении.
Как прикрепить и отправить синтетический файл?
Начните сопутствующий фиктивный файл, подключите браузер и отправьте небольшой тестовый полезный груз на фиксированную страницу обзора. Этот пример использует Node.js 22 и playwright-core@1.65.1. Используйте npx playwright-core install chromium и node fixture.mjs для локального запуска. Фиктивный файл связывается с 127.0.0.1 и обслуживает /upload на порту 4173 по умолчанию.
Шаг 1. Подтвердите целевой и формат подтверждения
Локальное приложение принимает файл с именем fixture.txt, содержащим 15 байт. Оно записывает подтверждение после того, как API прочитал файл, так что тест может отличать правильное подтверждение от пустого контроля. Подтвердите, что цель использует намеренный источник и аккаунт песочницы, прежде чем выбирать файл. Настройка автоматизации браузера.
Шаг 2. Подготовьте клиент браузера
Сохраните модули-спутники. Локальный запуск запускает Chromium напрямую. Изолированное тестирование удаленного клиента может использовать адрес петли CDP верификатора. Для управляемого запуска используйте готовую, авторизованную сессию, одобренное тестовое приложение, доступное через облачный браузер, и задокументированные конфигурации NSTDATA_API_KEY, NSTDATA_SESSION_ID и необязательную NSTDATA_TEAM_ID. Держите ключ отдельно от выданных учетных данных CDP. Локальный браузер и локальные ветви CDP выполняют клиентскую операцию. Управляемая ветвь требует авторизации вашего рабочего пространства и эквивалентного фикстуры.
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();}}}
Шаг 3. Присоедините тестовую нагрузку
Сохраните пример как upload.mjs. Запустите тестовый сервер, затем выполните node upload.mjs. Скрипт отправляет имя, MIME-тип и Buffer к помеченному вводу. Он использует точную метку управления и отправляет один раз. Если ваша настоящая авторизованная страница открывает только селектор, зарегистрируйте обещание события перед нажатием кнопки, затем вызовите setFiles() с проверенной нагрузкой.
Используйте результат, связанный с загруженным файлом, и проверьте, что было принято. Здесь сервер сообщает имя файла и размер в байтах, а скрипт выдает компактную запись об одобрении. В производственном приложении может быть использован идентификатор загрузки, ожидаемое состояние сканирования или сохраненный артефакт. Подождите, пока не появится сигнал, определяющий принятие в этом приложении. Документация документация по действию Playwright описывает, на что ожидает успешное действие, что отличается от того, что делает приложение после этого.
[Скриншот: Отобразите форму теста с выбранным синтетическим файлом и чеком, подтверждающим его количество байтов.]
Почему файл можно выбрать, в то время как загрузка все еще терпит неудачу?
Файл может отображаться в вводе, даже когда приложение отклоняет его или еще не завершило обработку. Проверьте этап, который произвел последний надежный сигнал. Таймаут локатора указывает на страницу или элемент управления. Ошибка сервера после выбора файла указывает на валидацию формы, запрос или обработку на стороне сервера. Логирование необработанных содержимого файла дает мало диагностической ценности.
Симптом
Что проверить
Безопасный ответ
Ввод истекает по времени
Метка, правильная страница, граница iframe
Найдите предусмотренный ввод на утверждённой странице
Событие выбора никогда не появляется
Поведение элемента управления и порядок регистрации событий
Зарегистрируйте правильное событие перед действием
Неправильный размер файла
Данные фикстуры и кодировка
Сравните ожидаемые байты с чеком от сервера
Чек отсутствует после отправки
Результат запроса и запись приложения
Согласуйте перед повторной отправкой
Руководство по отладке браузера и сети помогает отличить видимый результат интерфейса от сбоя ответа или передачи. Когда ваша цель использует фоновое сканирование, сохраните идентификатор загрузки и опрашивайте его задокументированное безопасное состояние, вместо того чтобы повторно отправлять файл.
Как должен обрабатывать задание на загрузку ошибку валидации?
Задание на загрузку должно сохранить оригинальную попытку и классифицировать ответ перед отправкой дополнительных байтов. При отклонении фикстуры сохраните безопасное имя файла, ожидаемый размер, категорию ответа и состояние записи приложения. Запустите намеренно отклоненную синтетическую нагрузку с измененным полем и подтвердите, что интерфейс сообщает об отклонении, не создавая записи о принятии. Если первый запрос мог быть успешным, а чек отсутствует, проконсультируйтесь с приложением, используя его идентификатор загрузки или другой вид состояния только для чтения.
Привяжите каждый негативный тест к одному небольшому файлу в среде, явно одобренной для отклонения фикстуры. Сохраните короткую диагностическую запись и очистите все сохраненные тестовые данные, используя предписанную процедуру очистки цели.
Как Nstdata Cloud Browser вписывается в QA загрузки?
Nstdata Cloud Browser предоставляет управляемый временем исполнения Chromium для авторизованного рабочего процесса с файлами. Скрипт Playwright по-прежнему создает ввод файлов, выполняет намеренное действие формы и проверяет, что записывает приложение. Живой просмотр или разрешенные диагностики браузера могут помочь оператору исследовать загрузку, проходящую через несколько фаз интерфейса. Доступ к целевому приложению, ограничениям файлов и удалению сохраненных тестовых данных остаются частью вашего проектирования приложения.
Удаленное подключение. Используйте поддерживаемый рабочий процесс CDP с собственным сеансом и проверенной целевой страницей.
Воспроизводимая фикстура. Храните небольшой одобренный байтовый полезный загрузку в рабочей среде и подтвердите ожидаемый чек от сервера.
Намеренная очистка. Закройте страницу, которую вы контролируете, и отдельно остановите управляемый браузер; удалите записи теста через одобренный путь приложения.
Что должен доказать повторяемый дымовой тест загрузки?
Повторяемый тест загрузки должен подтвердить, что ожидаемый файл был выбран, сервер принял его один раз, а артефакты браузера и сохраненной фикстуры определили владельцев очистки. Начните с наименьшей разрешенной выборки и проверьте как успешное получение, так и сбой валидации. Когда периодический результат требует проверки, используйте workflow воспроизведения сессии Cloud Browser с синтетическими данными и одобренным хранением.
Q: Может ли Playwright прикрепить Buffer к файлу ввода?
Да. Используйте объект с name, mimeType и buffer для документированного API файла ввода.
Q: Что делать, если кнопка загрузки открывает нативный выбор?
Подождите события filechooser страницы перед тем, как нажать, затем предоставьте загрузочный файл через возвращенный выбор.
Q: Доказательство файла в предварительном просмотре подтверждает, что сервер его принял?
Проверьте долговечную квитанцию приложения или статус. Предварительный просмотр в основном подтверждает, что клиент знает, какой файл был выбран.
Q: Нужно ли повторять отправку, если ответ был потерян?
Сначала проверьте оригинальную запись загрузки. Повторите отправку только тогда, когда сможете установить безопасный результат в соответствии с правилами приложения.
Q: Может ли облачная сессия открыть локальный URL фиктуры?
Облачный браузер имеет свою собственную сетевую среду. Используйте эквивалентную одобренную фиктуру staging, которую может достичь облачный браузер, либо выполните тест на локальном пути браузера.
Marcus Chen
Nov. 20th 2026
Запускайте облачные браузеры по запросу
Работайте с отпечатками браузера и CAPTCHA
Автоматизируйте процессы и расширяйте возможности ИИ-агентов
От сбора веб-данных и тестирования до автоматизации с ИИ — запускайте всё в облаке.