From aab92b550ba758d0ceb527fc1406567db6413210 Mon Sep 17 00:00:00 2001
From: Pascal Baljet <pascal@protone.media>
Date: Mon, 12 Jan 2026 15:31:43 +0100
Subject: [PATCH 1/3] Add `expectDownload()` and `expectDownloads()` methods

---
 browser-testing.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 54 insertions(+)

diff --git a/browser-testing.md b/browser-testing.md
index e3f8faa..a86be08 100644
--- a/browser-testing.md
+++ b/browser-testing.md
@@ -356,6 +356,15 @@ $page->assertSee('Welcome to Some Subdomain');
 
 </div>
 
+### Downloads
+
+<div class="collection-method-list" markdown="1">
+
+[expectDownload](#expect-download)
+[expectDownloads](#expect-downloads)
+
+</div>
+
 ### Debugging tests
 
 <div class="collection-method-list" markdown="1">
@@ -1194,6 +1203,51 @@ The `waitForKey` method opens the current page URL in the default web browser an
 $page->waitForKey(); // Useful for debugging
 ```
 
+## Downloads
+
+<a name="expect-download"></a>
+### expectDownload
+
+The `expectDownload` method executes a callback and captures the download it triggers:
+
+```php
+$download = $page->expectDownload(fn ($page) => $page->click('a[download]'));
+
+$download->assertFilename('report.pdf');
+$download->assertSuccessful();
+$download->saveAs('/path/to/report.pdf');
+```
+
+The returned `Download` object provides methods for file access and assertions:
+
+```php
+$download->url();
+$download->suggestedFilename();
+$download->path();
+$download->contents();
+$download->assertFilename('data.csv');
+$download->assertFilenameContains('report');
+$download->assertUrlContains('/export');
+$download->assertContentContains('Name,Email');
+$download->assertSuccessful();
+$download->assertFailed();
+```
+
+<a name="expect-downloads"></a>
+### expectDownloads
+
+The `expectDownloads` method executes a callback and captures multiple downloads:
+
+```php
+$downloads = $page->expectDownloads(
+    fn ($page) => $page->click('#download-all'),
+    count: 3
+);
+
+$downloads->each->assertSuccessful();
+$downloads->each(fn ($download, $i) => $download->saveAs("/path/to/file-{$i}.pdf"));
+```
+
 ## Debugging tests
 
 <a name="debug"></a>

From 3bb8f93fa75f533fa80771275442cd4a50737ad0 Mon Sep 17 00:00:00 2001
From: Pascal Baljet <pascal@protone.media>
Date: Mon, 12 Jan 2026 16:15:45 +0100
Subject: [PATCH 2/3] Update browser-testing.md

---
 browser-testing.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/browser-testing.md b/browser-testing.md
index a86be08..469b633 100644
--- a/browser-testing.md
+++ b/browser-testing.md
@@ -1245,7 +1245,6 @@ $downloads = $page->expectDownloads(
 );
 
 $downloads->each->assertSuccessful();
-$downloads->each(fn ($download, $i) => $download->saveAs("/path/to/file-{$i}.pdf"));
 ```
 
 ## Debugging tests

From c8cd7b5ad2e26e3bc9639b8eb416f1924ee88dc2 Mon Sep 17 00:00:00 2001
From: Pascal Baljet <pascal@protone.media>
Date: Mon, 12 Jan 2026 16:41:47 +0100
Subject: [PATCH 3/3] Update browser-testing.md

---
 browser-testing.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/browser-testing.md b/browser-testing.md
index 469b633..326c556 100644
--- a/browser-testing.md
+++ b/browser-testing.md
@@ -1244,7 +1244,9 @@ $downloads = $page->expectDownloads(
     count: 3
 );
 
-$downloads->each->assertSuccessful();
+foreach ($downloads as $download) {
+    $download->assertSuccessful();
+}
 ```
 
 ## Debugging tests