Connect with Playwright
Use Playwright’s connect() method in your application with the BrowserThing
WebSocket URL. The server selects an available worker that matches the browser
type and the client’s Playwright major and minor version.
Application -> Playwright commands -> Browser worker <- Results <-BrowserThing v0.10.0 images use Playwright 1.65.0. A client needs
the same major and minor version, so any 1.65 release works. The
Python package does not publish every patch release, so the Python example can
use an earlier patch. Use wss:// when your endpoint has TLS.
The examples save a screenshot as a small browser task. Use the same connection
for the browser actions your application needs. They read the API key from
BROWSERTHING_API_KEY.
Node.js
Section titled “Node.js”npm install playwright@1.65.0Save this as connect.mjs:
import { chromium } from 'playwright';
const browser = await chromium.connect('ws://localhost:8080', { headers: { Authorization: `Bearer ${process.env.BROWSERTHING_API_KEY}` },});try { const context = await browser.newContext({ viewport: { width: 1280, height: 720 }, }); const page = await context.newPage(); await page.goto('https://example.com'); await page.screenshot({ path: 'preview.png', fullPage: true });} finally { await browser.close();}Run node connect.mjs. It saves preview.png in the current directory on the
client machine. Replace https://example.com with your application’s page URL.
Python
Section titled “Python”python -m pip install playwright==1.65.0Save this as connect.py:
import asyncioimport os
from playwright.async_api import async_playwright
async def main(): async with async_playwright() as p: browser = await p.chromium.connect( "ws://localhost:8080", headers={"Authorization": f"Bearer {os.environ['BROWSERTHING_API_KEY']}"}, ) try: context = await browser.new_context() page = await context.new_page() await page.goto("https://example.com") await page.screenshot(path="preview.png", full_page=True) finally: await browser.close()
asyncio.run(main())Run python connect.py. It saves preview.png in the current directory on the
client machine.
Java and .NET clients use their corresponding BrowserType.connect() /
ConnectAsync() methods with the same endpoint and version requirement.
PDF exports
Section titled “PDF exports”Use a Chromium worker for PDF generation. In either example above, replace the screenshot call with a PDF call after the page has loaded:
await page.pdf({ path: 'report.pdf', format: 'A4', printBackground: true });await page.pdf(path="report.pdf", format="A4", print_background=True)Playwright saves report.pdf on the client machine. PDF generation uses print
styles by default. To use screen styles, call page.emulateMedia({ media: 'screen' })
in Node.js or page.emulate_media(media="screen") in Python before the PDF call.
For an application response or file upload, omit path from screenshot() or
pdf() and use the returned bytes. Your application decides where to store or
send the result.
Firefox and WebKit
Section titled “Firefox and WebKit”Start a worker with BROWSER_TYPE=firefox or BROWSER_TYPE=webkit first. A worker
serves one browser type. Then select it in the connection URL:
import { firefox, webkit } from 'playwright';
const firefoxBrowser = await firefox.connect( 'ws://localhost:8080/?browser=firefox',);await firefoxBrowser.close();
const webkitBrowser = await webkit.connect( 'ws://localhost:8080/?browser=webkit',);await webkitBrowser.close();The repository’s local Compose file shows a stack with all three browser types. It builds from source and requires a repository checkout.
Worker pools
Section titled “Worker pools”If the deployment has worker pools,
add ?pool=<name> to the connection URL. Without it, the session uses the
pool named default. For example, to use a pool named long:
const browser = await chromium.connect('ws://localhost:8080/?pool=long', { headers: { Authorization: `Bearer ${process.env.BROWSERTHING_API_KEY}` },});Combine it with a browser type as ?browser=firefox&pool=long. A session goes
only to workers in its pool. If the pool has no matching worker, the connection
waits in the queue and then fails with a message that names the pool.
API keys
Section titled “API keys”Clients must send an API key with each connection. For a Node.js client, use an authorization header:
const browser = await chromium.connect('wss://grid.example.com', { headers: { Authorization: `Bearer ${process.env.BROWSERTHING_API_KEY}` },});Clients can also pass ?token=pwd_... in the URL. Keep keys out of source control
and shared logs. Every valid key has full access to the service. See
security.
Session lifetime
Section titled “Session lifetime”Create your own browser context after you connect. Close the browser connection
in a finally block so the worker can release the session slot.
A session ends when its connection closes. If the server sets
MAX_SESSION_DURATION, it also closes sessions that stay connected for longer
than that limit. Reconnecting to a completed session is not supported. The
API guide explains how to create a pending session
and attach to it by ID.