diff --git a/browser-testing.md b/browser-testing.md
index e3f8faa..326c556 100644
--- a/browser-testing.md
+++ b/browser-testing.md
@@ -356,6 +356,15 @@ $page->assertSee('Welcome to Some Subdomain');
+### Downloads
+
+
+
+[expectDownload](#expect-download)
+[expectDownloads](#expect-downloads)
+
+
+
### Debugging tests
@@ -1194,6 +1203,52 @@ The `waitForKey` method opens the current page URL in the default web browser an
$page->waitForKey(); // Useful for debugging
```
+## Downloads
+
+
+### 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();
+```
+
+
+### expectDownloads
+
+The `expectDownloads` method executes a callback and captures multiple downloads:
+
+```php
+$downloads = $page->expectDownloads(
+ fn ($page) => $page->click('#download-all'),
+ count: 3
+);
+
+foreach ($downloads as $download) {
+ $download->assertSuccessful();
+}
+```
+
## Debugging tests