Успішна перевірка кліку не доводить, що завантажений файл правильний. Браузер може почати завантаження, а сервер — повернути неправильний звіт, порожній архів, застарілі дані або зловмисну назву файлу. Тому для надійного тестування завантажень потрібні два незалежні результати: Playwright має зафіксувати очікуване завантаження, а тест — перевірити збережений артефакт.
1. Зареєструйте обробник події перед дією
Сторінка Playwright генерує подію download, коли починається завантаження. Обробник має бути зареєстрований до кліку, що запускає завантаження, інакше швидку відповідь можна пропустити. Поєднайте проміс очікування події з дією:
const [download] = await Promise.all([
page.waitForEvent('download'),
page.getByRole('button', { name: 'Export report' }).click(),
]);Цей шаблон очікує спостережувану подію браузера, а не довільний тайм-аут. Не замінюйте цей підхід на waitForTimeout(5000): фіксована пауза сповільнює тест у швидкій системі й залишається ненадійною в повільній.
Перехоплення події — лише початок. Об’єкт Download ідентифікує передавання, але не доводить, що артефакт містить очікувані бізнес-дані.
2. Правильно перевіряйте, чи не сталося помилки завантаження
Метод Playwright download.failure() очікує завершення завантаження й повертає повідомлення про помилку або null. Він асинхронний і не повертає об’єкт Error.
const failure = await download.failure();
expect(failure).toBeNull();В API Download Playwright немає методу download.finished(). І failure(), і saveAs() за потреби очікують завершення завантаження. Тести, які викликають вигаданий метод завершення, можуть здаватися правдоподібними під час перевірки коду, але завершуватися помилкою під час виконання. Саме тому згенерований тестовий код потрібно звіряти з офіційним API.
3. Вважайте запропоновану назву файлу недовіреною
Значення suggestedFilename() походить із даних завантаження — зазвичай із наданого сервером заголовка Content-Disposition або з логіки браузера. Це корисні метадані, але не безпечний шлях призначення. Значення може містити роздільники шляхів, послідовності для обходу каталогів, оманливі розширення або бути надмірно довгим.
Безпечна політика має:
- звести значення до базового імені файлу;
- замінити символи поза невеликим дозволеним набором;
- обмежити довжину;
- дозволити лише очікувані розширення;
- вибрати каталог призначення окремо.
Метод Playwright Test testInfo.outputPath() створює шлях у каталозі результатів поточного тесту. Це зменшує ризик того, що паралельні тести перезапишуть артефакти один одного, і зберігає докази разом із результатом тесту.
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);
});Обмеження розміру не дає тесту обробляти несподівано великий артефакт після збереження. Це не повноцінний механізм контролю ресурсів: робочі системи також мають обмежувати розмір завантаження на рівні застосунку, сховища об’єктів або шлюзу.
5. Перевіряйте вміст, а не лише розширення
Непорожній файл із суфіксом .pdf усе одно може містити HTML зі сторінки помилки. Файл .csv може бути синтаксично коректним, але містити вчорашні дані тенанта. Вибирайте перевірки відповідно до формату й бізнес-ризику:
- Переконайтеся, що файл існує та має правдоподібний розмір.
- Перевірте дозволене розширення, але не вважайте його доказом типу файлу.
- Перевірте сигнатуру вмісту, якщо формат її має, наприклад
%PDF-для PDF абоPKдля форматів на основі ZIP. - Аналізуйте структуровані формати за допомогою справжнього парсера. Для CSV враховуйте лапки, роздільники, кодування та символи завершення рядків замість поділу кожного рядка за комами.
- Перевірте схему або обов’язкові поля.
- Перевірте значення, пов’язані з дією, що ініціювала завантаження: період звіту, тенант, фільтри, кількість записів, валюту або ідентифікатор кореляції.
- Використовуйте контрольну суму лише для детермінованого результату. Часові мітки, згенеровані ідентифікатори, метадані ZIP і порядок рядків можуть робити побайтові хеші нестабільними, навіть якщо результат правильний.
Якщо застосунок надає метадані відповіді через окремий API або подію аудиту, порівняйте їх зі збереженим артефактом. Не припускайте, що ім’я файлу або заявлений тип медіа підтверджує фактичний вміст.
6. Віддалені браузери та потоки
Метод download.path() очікує завершення завантаження й повертає тимчасовий шлях під час локального виконання. Згідно з документацією API Playwright, метод генерує виняток, коли браузер підключено віддалено. У тестах для локального та віддаленого виконання варто віддавати перевагу saveAs() або createReadStream().
Метод createReadStream() корисний, коли артефакт потрібно передати безпосередньо парсеру або конвеєру обчислення хешу. Потокове читання також дає змогу обмежити кількість байтів під час читання. Незалежно від обраного підходу зберігайте достатньо діагностичних доказів — безпечне ім’я файлу, очікуваний формат, розмір і результат валідації, — щоб пояснити збій без запису конфіденційного вмісту файлу до журналу.
Завантаження належать до контексту браузера, і Playwright видаляє тимчасові файли після його закриття. Збережіть усі необхідні докази до закриття контексту.
7. Міжплатформна безпека та безпека паралельного виконання
Не будуйте шляхи конкатенацією рядків або за допомогою жорстко заданих роздільників / і \. Використовуйте node:path і шлях призначення, отриманий за допомогою testInfo.outputPath().
Ізоляція важлива, навіть якщо імена файлів правильні. Два паралельні воркери можуть цілком коректно завантажувати report.json одночасно. Спільний каталог створює стани гонитви, хибнопозитивні результати через застарілі файли та ризик випадкового перезапису. Окремі шляхи результатів кожного тесту чітко визначають належність артефактів і дають стандартній політиці їх зберігання в засобі запуску тестів належним чином очищати докази.
Також уникайте перевірок, які шукають «найновіший файл» у спільному каталозі завантажень. Об’єкт Download уже представляє передавання, спричинене перевірюваною дією.
8. Сценарії безпеки, які варто автоматизувати
Функції завантаження перетинають межу довіри, тому додайте негативні тести на основі моделі загроз продукту:
- Відхиляйте імена з послідовностями обходу каталогів, абсолютні шляхи, зарезервовані імена пристроїв і неочікувані подвійні розширення.
- Перевірте авторизацію: один користувач не повинен мати змоги експортувати дані іншого тенанта.
- Переконайтеся, що в артефакті немає секретів, токенів і прихованих стовпців.
- Застосовуйте очікувані обмеження розміру й кількості записів.
- Для архівів обмежуйте кількість елементів, глибину вкладення та загальний нестиснений розмір до розпакування; відхиляйте елементи, що виходять за межі каталогу розпакування.
- Зберігайте докази з обмеженим доступом і не виводьте повний конфіденційний вміст у журнали CI.
- Тестуйте скасування та помилки сервера, щоб інтерфейс не показував невдалий експорт як успішний.
Антивірусне сканування може бути доречним для типів файлів із високим ризиком, але воно доповнює, а не замінює структурну й бізнес-валідацію.
9. Поширені антипатерни
- Клік перед реєстрацією
waitForEvent('download'). - Очікування протягом фіксованого часу з подальшим пошуком у файловій системі.
- Перевірка лише
suggestedFilename()або розширення. - Збереження наданих сервером імен безпосередньо у спільному каталозі.
- Припущення, що
download.path()працює з віддаленим браузером. - Аналіз CSV за допомогою наївного
split(',')у тестах промислового рівня. - Повторний запуск невдалого тесту завантаження без фіксації початкової помилки.
- Перевірка формату файлу без перевірки тенанта, фільтрів або бізнес-значень.
10. Перелік перевірок для релізу
- Обробник реєструється до дії, що запускає завантаження.
- Виклик
download.failure()очікується за допомогоюawait, а його результат перевіряється. - Ім’я файлу нормалізовано й обмежено очікуваними розширеннями.
- Файл зберігається в окремому каталозі результатів тесту.
- Тест працює в локальному та передбачених віддалених режимах браузера.
- Розмір, сигнатура, структура й бізнес-дані перевіряються відповідно до рівня ризику.
- Паралельні воркери не можуть спільно використовувати або перезаписувати артефакти.
- Конфіденційний вміст не розкривається в журналах або артефактах із необмеженим доступом.
- Для розпакування архівів установлено чіткі обмеження безпеки.
- У разі збоїв зберігаються стислі діагностичні докази.
Висновок
Надійне тестування завантажень — це ланцюг доказів: очікувана дія запускає одне спостережуване завантаження, передавання завершується без повідомлення про помилку, артефакт зберігається за ізольованим безпечним шляхом, а незалежні перевірки підтверджують його структуру та бізнес-значення. Playwright надає API для роботи з подіями й артефактами, а QA-підхід визначає оракул.
Залишити коментар
Поділіться думкою про статтю. Реєстрація не потрібна.
Коментарі
Завантаження коментарів…