Playwrightで、ファイルのダウンロードをテストする方法
Playwright では、page.waitForEvent('download') でダウンロードを受け取り、ファイル名と中身をテストの中で確かめられます。管理画面の「CSV で書き出す」ボタンや、帳票のダウンロードのリンクが、正しい名前と中身のファイルを返すかを自動で確かめたいときに使います。
書き方は短いのですが、waitForEvent を呼ぶ位置を間違えると、通ったり落ちたりするテストになります。私は検証環境で、ダウンロードの方法が違うリンクとボタンを並べたページを作り、正しい書き方と間違った書き方の両方を実行しました。
検証環境は Ubuntu 24.04、Node.js 22.23.4、@playwright/test 1.63.0 です。ブラウザは Playwright 用の Chromium だけで、ページは Node.js の http モジュールで書いた小さなサーバーから配信しました。Firefox・WebKit、Windows・macOS、CI サービス上での実行は試していません。
試したページ
ページには、ダウンロードのさせ方が違うリンクとボタンを、3つ置きました。
<p><a href="/export">売上を CSV で書き出す</a></p>
<p><a href="/files/notes.txt" download="memo.txt">メモをダウンロード</a></p>
<p><button id="make-csv">会員の一覧を作る</button></p>
1つ目の /export は、サーバーが Content-Disposition: attachment; filename="sales-2026-11.csv" のヘッダーを付けて CSV を返します。2つ目は、リンクの download 属性でファイル名を memo.txt にしています。3つ目のボタンは、JavaScript で CSV の文字列から Blob を作り、a 要素の download 属性と click() でダウンロードさせます。
document.getElementById('make-csv').addEventListener('click', () => {
const csv = 'id,name\n1,佐藤\n2,鈴木\n';
const blob = new Blob([csv], { type: 'text/csv' });
const a = document.createElement('a');
a.href = URL.createObjectURL(blob);
a.download = 'members.csv';
a.click();
URL.revokeObjectURL(a.href);
});
playwright.config.ts では、webServer でこのサーバー(node server.mjs)を起動し、baseURL を http://localhost:4173 にしています。
ファイル名と中身を確かめるテスト
基本の形は、公式ドキュメントのダウンロードの説明にあるとおりです。クリックの前に waitForEvent('download') を呼んで Promise を受け取っておき、クリックのあとでその Promise を await します。
import { test, expect } from '@playwright/test';
import { readFile, stat } from 'node:fs/promises';
test('サーバーが指定したファイル名と中身', async ({ page }, testInfo) => {
await page.goto('/');
const downloadPromise = page.waitForEvent('download');
await page.getByRole('link', { name: '売上を CSV で書き出す' }).click();
const download = await downloadPromise;
expect(download.suggestedFilename()).toBe('sales-2026-11.csv');
expect(download.url()).toBe('http://localhost:4173/export');
const file = testInfo.outputPath(download.suggestedFilename());
await download.saveAs(file);
const text = await readFile(file, 'utf8');
expect(text.split('\n')[0]).toBe('date,amount');
expect(text).toContain('2026-11-02,3400');
console.log('saved to', file, (await stat(file)).size, 'bytes');
});
受け取った Download オブジェクトの suggestedFilename() は、ブラウザが決めたファイル名です。API リファレンスによると、ふつうは Content-Disposition ヘッダーか download 属性から決まります。
saveAs() は、ダウンロードしたファイルを指定した場所にコピーします。ダウンロードが終わっていなければ、終わるまで待ちます。保存先に testInfo.outputPath() を使うと、テストごとに分かれたフォルダ(test-results の下)の中のパスになります。公式リファレンスには、並列で実行するテストどうしが干渉しないと書かれています。
実行すると、保存したファイルは 44 バイトで、中身は書き出した CSV のとおりでした(パスは /path/to/app に置き換えています)。
saved to /path/to/app/test-results/download-サーバーが指定したファイル名と中身-chromium/sales-2026-11.csv 44 bytes
✓ 1 [chromium] › tests/download.spec.ts:4:5 › サーバーが指定したファイル名と中身 (174ms)
保存せずに path() で読む
中身を読むだけなら、saveAs() を使わずに path() で、ブラウザがダウンロードした一時ファイルの場所を受け取れます。download 属性のリンクと、JavaScript で作った CSV は、この形で確かめました。
test('download 属性で付けた名前', async ({ page }) => {
await page.goto('/');
const downloadPromise = page.waitForEvent('download');
await page.getByRole('link', { name: 'メモをダウンロード' }).click();
const download = await downloadPromise;
expect(download.suggestedFilename()).toBe('memo.txt');
const path = await download.path();
console.log('path()', path);
expect(await readFile(path, 'utf8')).toBe('メモの本文です\n');
});
test('JavaScript で作った CSV', async ({ page }) => {
await page.goto('/');
const downloadPromise = page.waitForEvent('download');
await page.getByRole('button', { name: '会員の一覧を作る' }).click();
const download = await downloadPromise;
expect(download.suggestedFilename()).toBe('members.csv');
console.log('url()', download.url());
const rows = (await readFile(await download.path(), 'utf8')).trim().split('\n');
expect(rows).toEqual(['id,name', '1,佐藤', '2,鈴木']);
});
どちらも通りました。出力を見ると、path() のファイル名は suggestedFilename() の memo.txt ではなく、ランダムな文字列でした。JavaScript で作った CSV の url() は blob: で始まる URL です。
path() /path/to/app/test-results/.playwright-artifacts-0/5f216e99-a497-49ac-8840-442fb1a02a52
✓ 2 [chromium] › tests/download.spec.ts:21:5 › download 属性で付けた名前 (122ms)
url() blob:http://localhost:4173/86edc50d-7d05-4135-812e-a2d74e25211c
✓ 3 [chromium] › tests/download.spec.ts:33:5 › JavaScript で作った CSV (123ms)
この一時ファイルは、テストが終わると残りません。実行後に test-results の中を見ると、saveAs() で保存した sales-2026-11.csv だけがあり、.playwright-artifacts-0 のフォルダはありませんでした。公式ドキュメントのダウンロードの説明には、ダウンロードしたファイルはブラウザのコンテキストを閉じたときに消えると書かれています。自分でコンテキストを作るテストで、context.close() の前後に existsSync(path) を出してみると、閉じる前は true、閉じたあとは false でした。失敗したときに中身を見返したいファイルは、saveAs() で保存しておきます。
waitForEvent はクリックより前に呼ぶ
公式ドキュメントの例には、クリックの前に待ち始めるように、というコメントが付いています。順番を逆にして、クリックしてから waitForEvent('download') を呼ぶと、どうなるかを試しました。
// 間違った順番:クリックのあとで待ち始める
await page.getByRole('link', { name: '売上を CSV で書き出す' }).click();
await page.waitForEvent('download', { timeout: 3000 });
リンクとボタンのそれぞれで、正しい順番と逆の順番のテストを作り、--repeat-each=20 --workers=1 で20回ずつ実行しました。

クリックの前に待ち始めたテストは、リンクもボタンも20回すべて通りました。あとで待ち始めると、リンクは20回のうち5回、JavaScript でダウンロードさせるボタンは20回すべてが、3秒待って TimeoutError: page.waitForEvent: Timeout 3000ms exceeded while waiting for event "download" で落ちました。
リンクのほうは、落ちるのが20回のうち5回だけです。何度か実行して通ったからといって、順番が正しいとは限りません。書き方を「Promise を受け取る → クリック → await」の順にそろえれば、リンクでもボタンでも20回とも通りました。
ダウンロードが起きないときのエラー
クリックしてもダウンロードが起きないときは、waitForEvent の待ち時間の上限を過ぎて落ちます。何もしないボタンで、上限を5秒にして試した出力です。
TimeoutError: page.waitForEvent: Timeout 5000ms exceeded while waiting for event "download"
=========================== logs ===========================
waiting for event "download"
============================================================
page.waitForEvent() の API リファレンスによると、timeout の初期値は 0(上限なし)です。timeout を指定せずに同じボタンで試すと、テスト全体の上限の 30 秒まで待って、Test timeout of 30000ms exceeded. で落ちました。ボタンを押しても何も起きない不具合を早く見つけたいなら、timeout を短めに指定しておくと、失敗までの時間が短くなります。
途中で切れたダウンロードを見分ける
ダウンロードが始まったあとで失敗したかどうかは、failure() で分かります。成功していれば null が返ります。試しに、Content-Length ヘッダーでは 1,000,000 バイトと伝え、1,000 バイト送ったところで接続を切るリンクを作りました。
test('途中で切れたダウンロード', async ({ page }) => {
await page.goto('/');
const downloadPromise = page.waitForEvent('download');
await page.getByRole('link', { name: '大きなファイル' }).click();
const download = await downloadPromise;
console.log('failure()', await download.failure());
expect(await download.failure()).not.toBeNull();
});
failure() canceled
✓ 4 [chromium] › tests/download.spec.ts:45:5 › 途中で切れたダウンロード (1.3s)
Download の API リファレンスによると、download イベントはダウンロードが始まった時点で出ます。そのため、接続が切れても download イベントは届き、テストは失敗しませんでした。failure() が返した値は canceled です。テストのコードからダウンロードを止めたわけではありませんが、Chromium ではこの値になりました。
同じリンクで failure() を見ずに path() を呼ぶと、path() が例外を投げ、テストはそこで落ちます。
Error: download.path: canceled
path() で中身を読むテストなら、途中で切れたときはここで落ちるので、失敗を見逃しません。中身を読まずにファイル名だけを確かめるテストでは、expect(await download.failure()).toBeNull() を足しておきます。最後まで届いた CSV のリンクで failure() を出してみると、null でした。
acceptDownloads が false のときに failure() が返す文
コンテキストの acceptDownloads は、browser.newContext() の API リファレンスによると初期値が true で、ダウンロードをすべて受け付けます。test.use({ acceptDownloads: false }) で false にして CSV のリンクを押すと、download イベントは届き、failure() は次の文を返しました。
failure() Pass { acceptDownloads: true } when you are creating your browser context.
failure() がこの文を返したら、設定ファイルの use やテストの test.use() で、acceptDownloads が false になっていないかを見直します。





