Успешная проверка клика не доказывает, что загруженный файл верен. Браузер может начать загрузку, хотя сервер возвращает неправильный отчёт, пустой архив, устаревшие данные или потенциально опасное имя файла. Для надёжного тестирования загрузок требуются два независимых результата: Playwright должен зафиксировать ожидаемую загрузку, а тест должен проверить сохранённый артефакт.
1. Зарегистрируйте обработчик события до действия
Playwright генерирует событие страницы download при начале скачивания. Обработчик должен быть зарегистрирован до клика, запускающего загрузку; иначе можно пропустить быстрый ответ. Используйте промис события и действие вместе:
const [download] = await Promise.all([
page.waitForEvent('download'),
page.getByRole('button', { name: 'Export report' }).click(),
]);Этот шаблон ожидает наблюдаемого события браузера, а не произвольного тайм-аута. Не заменяйте его на waitForTimeout(5000): фиксированная пауза медленнее на быстрой системе и ненадёжна на медленной.
Перехват события — это только начало. Объект Download идентифицирует передачу, но не доказывает, что артефакт содержит ожидаемые бизнес-данные.
2. Правильно проверьте сбой передачи
Метод download.failure() в Playwright ждёт завершения загрузки и возвращает либо сообщение об ошибке, либо null. Он асинхронен и не возвращает объект Error.
const failure = await download.failure();
expect(failure).toBeNull();В API загрузки Playwright нет метода download.finished(). И failure(), и saveAs() ждут завершения загрузки, когда это необходимо. Тесты, вызывающие вымышленный метод завершения, могут выглядеть правдоподобно при ревью, но завершаться ошибкой во время выполнения — именно поэтому сгенерированный тестовый код необходимо сверять с официальной документацией API.
3. Считайте предложенное имя файла ненадёжным
suggestedFilename() формируется на основе данных загрузки, обычно из заголовка Content-Disposition, предоставленного сервером, или из логики загрузки браузера. Это полезные метаданные, а не безопасный путь назначения. Значение может содержать разделители путей, фрагменты обхода пути, вводящие в заблуждение расширения или чрезмерную длину.
Безопасная политика должна:
- оставить только базовое имя;
- заменить символы, не входящие в небольшой разрешённый набор;
- ограничить длину;
- разрешать только ожидаемые расширения;
- выбирать каталог назначения независимо от имени файла.
Метод testInfo.outputPath() в Playwright Test создаёт путь внутри каталога результатов текущего теста. Это снижает вероятность перезаписи артефактов параллельных тестов и сохраняет доказательства вместе с результатом теста.
4. Полный пример на TypeScript
Следующий тест загружает JSON-отчёт, сохраняет его в изолированном каталоге и проверяет транспорт, метаданные файла, структуру и бизнес-контент без дополнительной зависимости для безопасной обработки имени файла.
import { test, expect } from '@playwright/test';
import * as path from 'node:path';
import * as fs from 'node:fs/promises';
function safeDownloadName(rawName: string): string {
const baseName = path.basename(rawName)
.replace(/[^a-zA-Z0-9._-]/g, '_')
.slice(0, 120);
if (!baseName || baseName === '.' || baseName === '..') {
throw new Error('Download did not provide a usable filename');
}
const extension = path.extname(baseName).toLowerCase();
if (extension !== '.json') {
throw new Error(`Unexpected download extension: ${extension || '(none)'}`);
}
return baseName;
}
test('exports the requested customer report', async ({ page }, testInfo) => {
await page.goto('/reports/customers');
const [download] = await Promise.all([
page.waitForEvent('download'),
page.getByRole('button', { name: 'Export JSON' }).click(),
]);
expect(await download.failure()).toBeNull();
const safeName = safeDownloadName(download.suggestedFilename());
const destination = testInfo.outputPath('downloads', safeName);
await fs.mkdir(path.dirname(destination), { recursive: true });
await download.saveAs(destination);
const stats = await fs.stat(destination);
expect(stats.isFile()).toBe(true);
expect(stats.size).toBeGreaterThan(0);
expect(stats.size).toBeLessThan(10 * 1024 * 1024);
const raw = await fs.readFile(destination, 'utf8');
const report: unknown = JSON.parse(raw);
expect(report).toMatchObject({
reportType: 'customers',
requestedBy: 'qa-download-test',
});
const customers = (report as { customers?: unknown }).customers;
expect(Array.isArray(customers)).toBe(true);
expect(customers).not.toHaveLength(0);
});Верхнее ограничение размера не позволяет тесту обрабатывать неожиданно большой артефакт после его сохранения. Это не полноценный механизм управления ресурсами: системы в production-среде также должны устанавливать ограничения по размеру загрузок в приложении, хранилище объектов или шлюзе.
5. Проверьте полезную нагрузку, а не только расширение
Непустой файл с суффиксом .pdf всё ещё может содержать HTML со страницы ошибки. .csv может быть синтаксически читаемым, но содержать вчерашние данные арендатора. Выберите проверки, соответствующие формату и бизнес-риску:
- Убедитесь, что файл существует и имеет правдоподобный размер.
- Проверьте разрешённое расширение, но не рассматривайте его как доказательство типа.
- Проверьте сигнатуру контента, если в формате она есть, например,
%PDF-для PDF илиPKдля форматов на базе ZIP. - Разбирайте структурированные форматы с помощью полноценного парсера. Для CSV учитывайте кавычки, разделители, кодировку и окончания строк, а не разбивайте каждую строку на запятых.
- Проверьте схему или необходимые поля.
- Проверяйте значения, связанные с инициирующим действием: период отчёта, арендатора, фильтры, количество записей, валюту или идентификатор корреляции.
- Используйте контрольную сумму только при детерминированном результате. Временные метки, сгенерированные идентификаторы, метаданные ZIP и порядок строк могут сделать хеши полного содержимого нестабильными даже при правильном результате.
Если приложение показывает метаданные ответа через отдельный API или событие аудита, сравните их с сохранённым артефактом. Не предполагайте, что имя файла или заявленный MIME-тип подтверждают фактический контент.
6. Удалённые браузеры и потоки
download.path() ждёт завершения и возвращает временный путь в локальном запуске. Согласно документации Playwright, при удалённом подключении к браузеру этот метод выбрасывает исключение. Тесты, предназначенные для локального и удалённого выполнения, должны предпочитать saveAs() или createReadStream().
createReadStream() полезен, когда артефакт следует передавать напрямую парсеру или конвейеру вычисления хеша. Потоковая обработка также позволяет контролировать ограничение размера в байтах во время чтения. Какой бы подход вы ни выбрали, сохраняйте достаточно диагностических доказательств — безопасное имя файла, ожидаемый формат, размер и результат валидации — чтобы объяснить сбой без записи конфиденциального содержимого файла в журнал.
Загрузки связаны с контекстом браузера, и Playwright удаляет временные файлы, когда этот контекст закрывается. Сохраняйте все необходимые доказательства до закрытия контекста.
7. Кроссплатформенная и параллельная безопасность
Не создавайте пути с конкатенацией строк или жёстко закодированными сепараторами / и \. Используйте node:path и путь назначения, полученный через testInfo.outputPath().
Изоляция важна даже при правильных названиях файлов. Два параллельных worker-процесса могут одновременно скачивать report.json одновременно. Общая папка создаёт состояния гонки, ложноположительные результаты из-за устаревших файлов и случайные перезаписи. Отдельные выходные пути явно связывают артефакт с тестом и позволяют стандартной политике хранения тестовых артефактов удалять их.
Также избегайте проверок, которые ищут в общей папке загрузок «самый новый файл». Объект Download уже представляет передачу, инициированную тестируемым действием.
8. Вопросы безопасности, которые стоит автоматизировать
Функции скачивания пересекают границу доверия, поэтому добавьте негативные тесты на основе модели угроз продукта:
- Отклоняйте имена с фрагментами обхода пути, абсолютные пути, зарезервированные имена устройств и неожиданные двойные расширения.
- Проверьте авторизацию: один пользователь не должен экспортировать данные другого арендатора.
- Убедитесь, что секреты, токены и скрытые столбцы отсутствуют в артефакте.
- Проверяйте ограничения размера и количества записей.
- Для архивов ограничивайте количество записей, глубину вложения и общий несжатый размер перед извлечением; отклоняйте записи, пути которых выходят за пределы каталога извлечения.
- Храните доказательства с ограниченным доступом и не выводите полное содержимое конфиденциальных файлов в CI-логах.
- Тестируйте отмену загрузки и ошибки сервера, чтобы интерфейс не отображал неудачный экспорт как успешный.
Антивирусное сканирование может быть уместно для типов файлов повышенного риска, но оно скорее дополняет, чем заменяет структурную и бизнес-валидацию.
9. Распространённые антипаттерны
- Сначала выполнять клик, а затем регистрировать
waitForEvent('download'). - Ждать фиксированное время, а затем искать файл в файловой системе.
- Проверять только
suggestedFilename()или расширение. - Сохранять предоставленные сервером имена непосредственно в общий каталог.
- Предполагать, что
download.path()работает с удалённым браузером. - Разбирать CSV с помощью наивного
split(',')в тестах production-уровня. - Повторно запускать неудачный тест загрузки, не сохранив данные о первоначальном сбое.
- Проверять формат файла, но не арендатора, фильтры или бизнес-значения.
10. Чек-лист, готовый к релизу
- Обработчик события регистрируется перед действием, запускающим загрузку.
- Вызов
download.failure()ожидается, а его результат проверяется. - Имя файла нормализовано и ограничено ожидаемыми расширениями.
- Файл сохраняется в каталоге результатов отдельного теста.
- Тест работает с локальными и предусмотренными режимами удалённого запуска браузера.
- Размер, подпись, структура и бизнес-данные проверяются на соответствующем уровне риска.
- Параллельные worker-процессы не могут совместно использовать или перезаписывать артефакты.
- Чувствительный контент не раскрывается в журналах или артефактах без ограничений доступа.
- Архивы извлекаются с явно заданными ограничениями безопасности.
- При сбоях сохраняются краткие диагностические данные.
Заключение
Надёжное тестирование загрузок — это цепочка доказательств: ожидаемое действие запускает одну наблюдаемую загрузку, передача завершается без сообщения о сбое, артефакт сохраняется по изолированному безопасному пути, а независимые проверки подтверждают его структуру и бизнес-смысл. Playwright предоставляет API событий и артефактов; дизайн тестов определяет тестовый оракул.
Оставить комментарий
Поделитесь своим мнением о статье. Регистрация не требуется.
Комментарии
Загрузка комментариев…