File Downloads

View as Markdown

Browser runtimes can download files triggered by page interactions. Downloaded files are saved to the runtime’s workspace storage and can be retrieved via the storage client.

Enabling downloads

Playwright

Downloads are accepted by default. You can explicitly control this via context options:

1const runtime = await workspace.runtimes.browser("main").playwright({
2 mode: "ephemeral",
3 driverOptions: {
4 acceptDownloads: true,
5 },
6});

Puppeteer

Configure download behavior on the browser context:

1const runtime = await workspace.runtimes.browser("main").puppeteer({
2 mode: "ephemeral",
3 driverOptions: {
4 downloadBehavior: {
5 policy: "allow",
6 },
7 },
8});
PolicyDescription
allowAllow downloads, save to default location
allowAndNameAllow downloads with a specific naming scheme
denyBlock all downloads
defaultUse browser default behavior

Triggering a download

Click a download link or button as you normally would:

1// Playwright
2await runtime.page.locator("a[href$='.csv']").click();
3
4// Puppeteer
5await runtime.page.$eval("a[href$='.csv']", (el) => el.click());

Downloaded files are automatically captured and stored in the workspace’s storage.

Retrieving downloads

Use the storage client to access downloaded files:

1const storage = bctrl.storage("my-workspace");
2
3// List downloaded files
4const objects = await storage.listObjects({ source: "download" });
5
6// Download a specific file
7const data = await storage.downloadObject(objects[0].id);
8
9// Get a download URL
10const url = await storage.getObjectDownloadUrl(objects[0].id);
11
12// Download everything as a ZIP
13const zip = await storage.getDownloadsZip();

Example: export and retrieve a CSV

1// Navigate to a report page
2await runtime.page.goto("https://app.example.com/reports");
3
4// Click the export button
5await runtime.page.locator("#export-csv").click();
6
7// Wait for the download to appear in storage
8await new Promise((r) => setTimeout(r, 3000));
9
10// Retrieve the file
11const storage = bctrl.storage("my-workspace");
12const objects = await storage.listObjects({ source: "download" });
13const csv = await storage.downloadObject(objects[0].id);