Handling Downloads
Detect and save files downloaded by the browser.
JavaScript
Section titled “JavaScript”Downloads need a real HTTP server — the browser must receive a Content-Disposition: attachment header to trigger a download.
Quick Example
Section titled “Quick Example”First, save this server as server.js and start it:
const http = require('http');
const server = http.createServer((req, res) => { if (req.url === '/file') { res.writeHead(200, { 'Content-Type': 'text/plain', 'Content-Disposition': 'attachment; filename="hello.txt"', }); return res.end('hello world'); } res.writeHead(200, { 'Content-Type': 'text/html' }); res.end('<a href="/file" id="dl-link">Download hello.txt</a>');});
server.listen(3000, () => console.log('http://localhost:3000'));node server.jsThen in another terminal, run the download script:
const { browser } = require('vibium');
async function main() { const bro = await browser.start(); const vibe = await bro.page(); await vibe.go('http://localhost:3000');
const download = await vibe.capture.download(async () => { await vibe.find({ css: '#dl-link' }).click(); });
console.log(download.suggestedFilename()); // hello.txt await download.saveAs('/tmp/hello.txt');
await bro.stop();}
main();Sync version
const { browser } = require('vibium/sync');
const bro = browser.start();const vibe = bro.page();vibe.go('http://localhost:3000');
const result = vibe.capture.download(() => { vibe.find({ css: '#dl-link' }).click();});
console.log(result.suggestedFilename); // hello.txtresult.saveAs('/tmp/hello.txt');
bro.stop();capture.download
Section titled “capture.download”capture.download() sets up a listener, runs your action, and returns the download:
const { browser } = require('vibium');const fs = require('fs');const os = require('os');const path = require('path');
const bro = await browser.start({ headless: true });const vibe = await bro.page();await vibe.go(baseURL);
const download = await vibe.capture.download(async () => { await vibe.find({ css: '#dl-link' }).click();});
assert.ok(download.url().includes('/file'));assert.strictEqual(download.suggestedFilename(), 'hello.txt');
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vibium-dl-'));try { await download.saveAs(path.join(tmpDir, 'saved.txt')); assert.strictEqual(fs.readFileSync(path.join(tmpDir, 'saved.txt'), 'utf-8'), 'hello world');} finally { fs.rmSync(tmpDir, { recursive: true, force: true });}
await bro.stop();Sync test
const { browser } = require('vibium/sync');const fs = require('fs');const os = require('os');const path = require('path');
const bro = browser.start({ headless: true });const vibe = bro.page();vibe.go(baseURL);
const result = vibe.capture.download(() => { vibe.find({ css: '#dl-link' }).click();});
assert.ok(result.url.includes('/file'));assert.strictEqual(result.suggestedFilename, 'hello.txt');assert.ok(result.path, 'path should be set after download');
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'vibium-dl-'));try { result.saveAs(path.join(tmpDir, 'saved.txt')); assert.strictEqual(fs.readFileSync(path.join(tmpDir, 'saved.txt'), 'utf-8'), 'hello world');} finally { fs.rmSync(tmpDir, { recursive: true, force: true });}
bro.stop();onDownload
Section titled “onDownload”For ongoing monitoring, onDownload() fires on every download:
const { browser } = require('vibium');
const bro = await browser.start({ headless: true });const vibe = await bro.page();await vibe.go(baseURL);
const downloads = [];vibe.onDownload((dl) => downloads.push(dl));
await vibe.find({ css: '#dl-link' }).click();await vibe.wait(1000);
assert.ok(downloads.length >= 1);assert.strictEqual(downloads[0].suggestedFilename(), 'hello.txt');
await bro.stop();Sync test
const { browser } = require('vibium/sync');
const bro = browser.start({ headless: true });const vibe = bro.page();vibe.go(baseURL);
const downloads = [];vibe.onDownload((dl) => downloads.push(dl));
vibe.find({ css: '#dl-link' }).click();vibe.wait(2000);
assert.ok(downloads.length >= 1);assert.strictEqual(downloads[0].suggestedFilename, 'hello.txt');assert.ok(downloads[0].path, 'download should have path');
bro.stop();Call removeAllListeners('download') to stop listening.
Python
Section titled “Python”Downloads need a real HTTP server — the browser must receive a Content-Disposition: attachment header to trigger a download.
Quick Example
Section titled “Quick Example”First, save this server as server.py and start it:
from http.server import HTTPServer, BaseHTTPRequestHandler
class Handler(BaseHTTPRequestHandler): def do_GET(self): if self.path == "/file": self.send_response(200) self.send_header("Content-Type", "text/plain") self.send_header("Content-Disposition", 'attachment; filename="hello.txt"') self.end_headers() self.wfile.write(b"hello world") else: self.send_response(200) self.send_header("Content-Type", "text/html") self.end_headers() self.wfile.write(b'<a href="/file" id="dl-link">Download hello.txt</a>')
server = HTTPServer(("localhost", 3000), Handler)print("http://localhost:3000")server.serve_forever()python server.pyThen in another terminal, run the download script:
from vibium import browser
bro = browser.start()vibe = bro.page()vibe.go("http://localhost:3000")
result = vibe.capture.download(lambda: vibe.find(css="#dl-link").click())
print(result["suggested_filename"]) # hello.txtresult.save_as("/tmp/hello.txt")
bro.stop()Async version
import asynciofrom vibium.async_api import browser
async def main(): bro = await browser.start() vibe = await bro.page() await vibe.go("http://localhost:3000")
async with vibe.capture.download() as cap: el = await vibe.find(css="#dl-link") await el.click()
download = cap.value print(download.suggested_filename()) # hello.txt await download.save_as("/tmp/hello.txt")
await bro.stop()
asyncio.run(main())In async mode you get a Download object with methods and save_as(). In sync mode you get a SyncDownload (dict subclass) with both dict access and save_as().
capture.download
Section titled “capture.download”capture.download() sets up a listener, runs your action, and returns the download:
import osimport tempfileimport shutilfrom vibium import browser
bro = browser.start(headless=True)vibe = bro.page()vibe.go(base_url)
result = vibe.capture.download(lambda: vibe.find(css="#dl-link").click())
assert "/file" in result["url"]assert result["suggested_filename"] == "hello.txt"assert result["path"] is not None
tmp_dir = tempfile.mkdtemp(prefix="vibium-dl-")try: result.save_as(os.path.join(tmp_dir, "saved.txt")) with open(os.path.join(tmp_dir, "saved.txt")) as f: assert f.read() == "hello world"finally: shutil.rmtree(tmp_dir)
bro.stop()Async test
import osimport tempfileimport shutilfrom vibium.async_api import browser
bro = await browser.start(headless=True)vibe = await bro.page()await vibe.go(base_url)
async with vibe.capture.download() as cap: el = await vibe.find(css="#dl-link") await el.click()
download = cap.valueassert "/file" in download.url()assert download.suggested_filename() == "hello.txt"
tmp_dir = tempfile.mkdtemp(prefix="vibium-dl-")try: await download.save_as(os.path.join(tmp_dir, "saved.txt")) with open(os.path.join(tmp_dir, "saved.txt")) as f: assert f.read() == "hello world"finally: shutil.rmtree(tmp_dir)
await bro.stop()on_download
Section titled “on_download”For ongoing monitoring, on_download() fires on every download:
import timefrom vibium import browser
bro = browser.start(headless=True)vibe = bro.page()vibe.go(base_url)
downloads = []vibe.on_download(lambda dl: downloads.append(dl))
vibe.find(css="#dl-link").click()
# The download event arrives asynchronously; poll briefly for it.deadline = time.time() + 15while not downloads and time.time() < deadline: time.sleep(0.1)
assert len(downloads) >= 1assert downloads[0].suggested_filename() == "hello.txt"assert downloads[0]["path"] is not None
bro.stop()Async test
import asynciofrom vibium.async_api import browser
bro = await browser.start(headless=True)vibe = await bro.page()await vibe.go(base_url)
downloads = []vibe.on_download(lambda dl: downloads.append(dl))
el = await vibe.find(css="#dl-link")await el.click()await asyncio.sleep(1)
assert len(downloads) >= 1assert downloads[0].suggested_filename() == "hello.txt"
await bro.stop()Quick Example
Section titled “Quick Example”First, save this server as Server.java and start it:
import com.sun.net.httpserver.HttpServer;import java.net.InetSocketAddress;import java.nio.charset.StandardCharsets;
public class Server { public static void main(String[] args) throws Exception { HttpServer server = HttpServer.create(new InetSocketAddress("localhost", 3000), 0); server.createContext("/", exchange -> { byte[] body; if (exchange.getRequestURI().getPath().equals("/file")) { exchange.getResponseHeaders().add("Content-Type", "text/plain"); exchange.getResponseHeaders().add("Content-Disposition", "attachment; filename=\"hello.txt\""); body = "hello world".getBytes(StandardCharsets.UTF_8); } else { exchange.getResponseHeaders().add("Content-Type", "text/html"); body = "<a href=\"/file\" id=\"dl-link\">Download hello.txt</a>".getBytes(StandardCharsets.UTF_8); } exchange.sendResponseHeaders(200, body.length); exchange.getResponseBody().write(body); exchange.close(); }); server.start(); System.out.println("http://localhost:3000"); }}java Server.javaThen in another terminal, run the download program:
import com.vibium.Download;import com.vibium.Vibium;import com.vibium.types.SelectorOptions;
public class DownloadExample { public static void main(String[] args) { var bro = Vibium.start(); var vibe = bro.page(); vibe.go("http://localhost:3000");
Download download = vibe.capture().download( () -> vibe.find(new SelectorOptions().css("#dl-link")).click());
System.out.println(download.suggestedFilename()); // hello.txt download.saveAs("/tmp/hello.txt");
bro.stop(); }}capture().download
Section titled “capture().download”capture().download() sets up a listener, runs your action, and returns the download:
Download download = vibe.capture().download( () -> vibe.find(new SelectorOptions().css("#dl-link")).click());
download.url(); // ends with /filedownload.suggestedFilename(); // "hello.txt"download.saveAs("/tmp/hello.txt");download.path(); // the browser's temp file, once the download completesonDownload
Section titled “onDownload”onDownload() registers a callback that fires for every download on the page:
List<Download> downloads = new CopyOnWriteArrayList<>();vibe.onDownload(downloads::add);
vibe.find(new SelectorOptions().css("#dl-link")).click();
// The download event arrives asynchronously; poll briefly for it.for (int i = 0; i < 50 && downloads.isEmpty(); i++) { Thread.sleep(100);}
downloads.get(0).suggestedFilename(); // "hello.txt"