Eine erfolgreiche Prüfung des Klicks beweist nicht, dass eine heruntergeladene Datei korrekt ist. Der Browser kann einen Download starten, während der Server einen falschen Bericht, ein leeres Archiv, veraltete Daten oder einen manipulierten Dateinamen zurückgibt. Zuverlässige Download-Tests erfordern daher zwei unabhängige Ergebnisse: Playwright muss den erwarteten Download erfassen, und der Test muss das gespeicherte Artefakt validieren.
1. Den Listener vor der Aktion registrieren
Playwright löst auf der Seite das Ereignis download aus, sobald ein Download beginnt. Der Listener muss vor dem auslösenden Klick registriert sein; andernfalls kann ein schneller Download übersehen werden. Warten Sie parallel auf das Ereignis und führen Sie die Aktion aus:
const [download] = await Promise.all([
page.waitForEvent('download'),
page.getByRole('button', { name: 'Export report' }).click(),
]);Dieses Muster wartet auf ein beobachtbares Browserereignis statt auf ein willkürlich gewähltes Timeout. Ersetzen Sie es nicht durch waitForTimeout(5000): Eine feste Pause verlangsamt den Test auf einem schnellen System und ist auf einem langsamen System unzuverlässig.
Das Erfassen des Ereignisses ist nur der Anfang. Ein Download-Objekt identifiziert die Übertragung, beweist jedoch nicht, dass das Artefakt die erwarteten Geschäftsdaten enthält.
2. Übertragungsfehler korrekt prüfen
Playwrights download.failure() wartet auf den Abschluss des Downloads und gibt entweder eine Fehlermeldung oder null zurück. Die Methode ist asynchron und gibt kein Error-Objekt zurück.
const failure = await download.failure();
expect(failure).toBeNull();In der Playwright Download API gibt es keine Methode download.finished(). Sowohl failure() als auch saveAs() warten bei Bedarf auf den Abschluss des Downloads. Tests, die eine nicht vorhandene Abschlussmethode aufrufen, können beim Review plausibel erscheinen, aber zur Laufzeit scheitern. Genau deshalb muss generierter Testcode anhand der offiziellen API überprüft werden.
3. Den vorgeschlagenen Dateinamen als nicht vertrauenswürdig behandeln
suggestedFilename() wird aus dem Download abgeleitet, in der Regel aus dem vom Server bereitgestellten Content-Disposition-Header oder aus der Downloadlogik des Browsers. Der Wert ist eine nützliche Metainformation, aber kein sicherer Zielpfad. Er kann Pfadtrennzeichen, Pfadtraversierungssequenzen, irreführende Dateierweiterungen oder eine übermäßige Länge enthalten.
Eine sichere Richtlinie sollte:
- den Wert auf einen Basisnamen reduzieren;
- Zeichen außerhalb einer kleinen erlaubten Menge ersetzen;
- die Länge begrenzen;
- nur erwartete Dateierweiterungen zulassen;
- das Zielverzeichnis unabhängig auswählen.
In Playwright Test erzeugt testInfo.outputPath() einen Pfad innerhalb des Ausgabeverzeichnisses des aktuellen Tests. Dadurch wird verhindert, dass parallele Tests gegenseitig ihre Artefakte überschreiben, und die Nachweise bleiben dem jeweiligen Testergebnis zugeordnet.
4. Ein vollständiges TypeScript-Beispiel
Der folgende Test lädt einen JSON-Bericht herunter, speichert ihn in einem isolierten Verzeichnis und überprüft Übertragung, Dateimetadaten, Struktur und Geschäftsinhalte, ohne eine zusätzliche Abhängigkeit für die Bereinigung des Dateinamens einzuführen.
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);
});Die Größenobergrenze verhindert, dass der Test ein unerwartet großes Artefakt verarbeitet, nachdem es gespeichert wurde. Sie ist kein vollständiger Mechanismus zur Ressourcenbegrenzung: Produktionssysteme sollten Download-Größenbeschränkungen zusätzlich in der Anwendung, im Objektspeicher oder am Gateway durchsetzen.
5. Die Nutzlast validieren, nicht nur die Dateierweiterung
Eine nicht leere Datei mit der Dateierweiterung .pdf kann dennoch HTML aus einer Fehlerseite enthalten. Eine .csv-Datei kann syntaktisch lesbar sein, aber Mandantendaten vom Vortag enthalten. Wählen Sie Prüfungen, die zum Format und zum geschäftlichen Risiko passen:
- Bestätigen Sie, dass die Datei existiert und eine plausible Größe hat.
- Prüfen Sie die zulässige Dateierweiterung, behandeln Sie sie aber nicht als Nachweis für den Dateityp.
- Prüfen Sie eine Inhaltssignatur, sofern das Format eine besitzt, beispielsweise
%PDF-für PDF oderPKfür ZIP-basierte Formate. - Parsen Sie strukturierte Formate mit einem echten Parser. Berücksichtigen Sie bei CSV Anführungszeichen, Trennzeichen, Zeichenkodierung und Zeilenenden, statt jede Zeile an Kommas zu teilen.
- Validieren Sie ein Schema oder die erforderlichen Felder.
- Prüfen Sie Werte, die mit der auslösenden Aktion zusammenhängen: Berichtszeitraum, Mandant, Filter, Datensatzanzahl, Währung oder Korrelations-ID.
- Verwenden Sie eine Prüfsumme nur bei deterministischer Ausgabe. Zeitstempel, generierte IDs, ZIP-Metadaten und die Reihenfolge von Zeilen können Byte-für-Byte-Hashes instabil machen, obwohl das Ergebnis korrekt ist.
Wenn die Anwendung Antwortmetadaten über eine separate API oder ein Audit-Event bereitstellt, vergleichen Sie diese mit dem gespeicherten Artefakt. Gehen Sie nicht davon aus, dass ein Dateiname oder ein deklarierter Medientyp den tatsächlichen Inhalt belegt.
6. Remote-Browser und Streams
download.path() wartet auf den Abschluss und gibt bei einem lokalen Lauf den temporären Pfad zurück. Laut der Playwright-API-Dokumentation löst die Methode einen Fehler aus, wenn der Browser remote verbunden ist. Tests, die sowohl lokal als auch mit einem Remote-Browser ausgeführt werden sollen, sollten saveAs() oder createReadStream() bevorzugen.
createReadStream() ist nützlich, wenn das Artefakt direkt an einen Parser oder eine Hashing-Pipeline weitergeleitet werden soll. Beim Streaming kann außerdem während des Lesens ein Byte-Limit durchgesetzt werden. Unabhängig vom gewählten Ansatz sollten genügend Diagnoseinformationen erhalten bleiben – sicherer Dateiname, erwartetes Format, Größe und Validierungsergebnis –, damit sich ein Fehler erklären lässt, ohne sensible Dateiinhalte zu protokollieren.
Downloads gehören zum Browserkontext, und Playwright löscht ihre temporären Dateien, wenn dieser Kontext geschlossen wird. Speichern Sie alle erforderlichen Nachweise vor dem Teardown.
7. Plattformübergreifende und parallele Sicherheit
Erstellen Sie Pfade nicht durch String-Konkatenation oder mit fest codierten Trennzeichen wie / und \. Verwenden Sie node:path und ein von testInfo.outputPath() erzeugtes Ziel.
Isolation ist auch bei korrekten Dateinamen wichtig. Zwei parallele Worker können berechtigterweise gleichzeitig report.json herunterladen. Ein gemeinsam verwendetes Verzeichnis verursacht Race Conditions, False Positives durch veraltete Dateien und unbeabsichtigtes Überschreiben. Separate Ausgabepfade pro Test machen die Zuordnung eindeutig und ermöglichen es der üblichen Aufbewahrungsrichtlinie des Testrunners, die Artefakte zu bereinigen.
Vermeiden Sie außerdem Assertions, die einen allgemeinen Downloadordner nach der „neuesten Datei“ durchsuchen. Das Download-Objekt repräsentiert bereits die durch die getestete Aktion ausgelöste Übertragung.
8. Sicherheitsfälle, die automatisiert werden sollten
Downloadfunktionen überschreiten eine Vertrauensgrenze. Ergänzen Sie daher negative Tests auf Grundlage des Bedrohungsmodells des Produkts:
- Lehnen Sie Dateinamen mit Pfadtraversierung, absolute Pfade, reservierte Gerätenamen und unerwartete doppelte Dateierweiterungen ab.
- Prüfen Sie die Autorisierung: Ein Nutzer darf nicht die Daten eines anderen Mandanten exportieren.
- Stellen Sie sicher, dass das Artefakt keine Secrets, Tokens oder verborgenen Spalten enthält.
- Setzen Sie die erwarteten Grenzwerte für Größe und Datensatzanzahl durch.
- Begrenzen Sie bei Archiven vor der Extraktion die Anzahl der Einträge, die Verschachtelungstiefe und die gesamte unkomprimierte Größe. Lehnen Sie Einträge ab, die aus dem Extraktionsverzeichnis ausbrechen.
- Speichern Sie Nachweise mit eingeschränktem Zugriff und geben Sie vollständige sensible Nutzlasten nicht in CI-Logs aus.
- Testen Sie Abbrüche und Serverfehler, damit die Benutzeroberfläche einen fehlgeschlagenen Export nicht als erfolgreich darstellt.
Ein Antiviren-Scan kann bei Dateitypen mit hohem Risiko angemessen sein, ergänzt jedoch strukturelle und fachliche Validierungen, statt sie zu ersetzen.
9. Häufige Antimuster
- Zuerst klicken und
waitForEvent('download')erst danach registrieren. - Für eine feste Dauer warten und anschließend das Dateisystem durchsuchen.
- Nur
suggestedFilename()oder die Dateierweiterung prüfen. - Vom Server bereitgestellte Namen direkt in einem gemeinsam verwendeten Verzeichnis speichern.
- Davon ausgehen, dass
download.path()mit einem Remote-Browser funktioniert. - CSV in produktionsnahen Tests mit einem naiven
split(',')parsen. - Einen fehlgeschlagenen Download-Test wiederholen, ohne den ursprünglichen Fehler zu protokollieren.
- Das Dateiformat prüfen, nicht aber den Mandanten, die Filter oder die Geschäftswerte.
10. Checkliste für die Release-Freigabe
- Der Listener wird vor der auslösenden Aktion registriert.
download.failure()wird mitawaitabgewartet und das Ergebnis geprüft.- Der Dateiname wird normalisiert und auf die erwarteten Dateierweiterungen beschränkt.
- Die Datei wird in einem separaten Ausgabeverzeichnis pro Test gespeichert.
- Der Test funktioniert sowohl lokal als auch in den vorgesehenen Remote-Browser-Modi.
- Größe, Signatur, Struktur und Geschäftsdaten werden entsprechend dem jeweiligen Risikoniveau validiert.
- Parallele Worker können Artefakte weder gemeinsam verwenden noch überschreiben.
- Sensible Inhalte werden weder in Logs noch in uneingeschränkt zugänglichen Artefakten offengelegt.
- Für die Extraktion von Archiven gelten explizite Sicherheitsgrenzen.
- Bei Fehlern bleiben aussagekräftige Diagnoseinformationen erhalten.
Fazit
Zuverlässiges Download-Testing ist eine Nachweiskette: Die erwartete Aktion löst einen beobachtbaren Download aus, die Übertragung wird ohne gemeldeten Fehler abgeschlossen, das Artefakt wird unter einem isolierten, sicheren Pfad gespeichert, und unabhängige Prüfungen bestätigen seine Struktur und fachliche Bedeutung. Playwright stellt die Ereignis- und Artefakt-APIs bereit; das QA-Design liefert das Testorakel.
Kommentar hinterlassen
Teilen Sie Ihre Gedanken zum Artikel. Kein Konto erforderlich.
Kommentare
Kommentare werden geladen…