Connect Playwright to Steel
Playwright drives a Steel session over the Chrome DevTools Protocol (CDP). You replace chromium.launch() with chromium.connectOverCDP(), and the rest of your Playwright code runs against a browser in Steel's cloud. Proxies, CAPTCHA solving and the live view come from the session, not from Playwright. Because the browser runs in Steel, you do not run playwright install or install Chrome on your machine.
In this guide, you run a first Playwright program on Steel and watch its browser live. After the run, you replay it in the dashboard. Then you move your own Playwright code over.
Before you begin
- A Steel API key in the
STEEL_API_KEYenvironment variable. See API keys. - Node.js 20 or later, or Python 3.10 or later.
Make a folder for the project, and install the Steel SDK and Playwright in it:
mkdir steel-playwright
cd steel-playwright
npm install steel-sdk playwrightmkdir steel-playwright
cd steel-playwright
python3 -m venv .venv
source .venv/bin/activate
pip install steel-sdk playwright1. Write the program
This program creates a session and prints its session viewer URL. It waits for you to press Enter, so that you can open the URL first. Then it connects Playwright to the session, opens a page and prints the page's title. It releases the session in finally, even when a step fails.
import { createInterface } from "node:readline/promises";
import Steel from "steel-sdk";
import { chromium } from "playwright";
const client = new Steel();
const session = await client.sessions.create();
console.log("Session viewer:", session.sessionViewerUrl);
try {
if (process.stdin.isTTY) {
const prompt = createInterface({ input: process.stdin, output: process.stdout });
await prompt.question("Open the session viewer, then press Enter.");
prompt.close();
}
const browser = await chromium.connectOverCDP(session.websocketUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] ?? (await context.newPage());
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();
} finally {
await client.sessions.release(session.id);
}import sys
from playwright.sync_api import sync_playwright
from steel import Steel
client = Steel()
session = client.sessions.create()
print("Session viewer:", session.session_viewer_url)
try:
if sys.stdin.isatty():
input("Open the session viewer, then press Enter.")
with sync_playwright() as playwright:
browser = playwright.chromium.connect_over_cdp(session.websocket_url)
context = browser.contexts[0]
page = context.pages[0] if context.pages else context.new_page()
page.goto("https://example.com")
print(page.title())
browser.close()
finally:
client.sessions.release(session.id)The Python file is not named playwright.py, because that name would hide the playwright package from the import.
2. Run it and watch it live
Run the program:
npx tsx playwright.mtspython playwright_steel.pyThe program prints the URL of the session viewer, the session's page in the Steel dashboard, and waits:
Session viewer: https://app.steel.dev/sessions/b57916d8-5a9f-44ce-853e-4c382fe23106
Open the session viewer, then press Enter.Open the URL in a browser where you are signed in to Steel. The viewer shows the session's browser, live. Press Enter in the terminal. In the viewer, the browser opens example.com, and the program prints the page's title:
Example Domain3. Replay the run
The program released the session, so the session has ended. Open the same session viewer URL again. It now plays the session's recording, next to its logs and agent traces, which list the page load. Recordings shows how to fetch or embed the video.
4. Move your own Playwright code
To run Playwright code that you already have, make the same change as the program. Create a session, and replace chromium.launch() with chromium.connectOverCDP() and the session's websocketUrl. The URL is the same for every CDP client, and CDP explains it. Then check these parts of your code.
Use the session's context
A session starts with one browser context, and that context already has a page open. Use browser.contexts()[0] (browser.contexts[0] in Python) and its first page, or a new page if it has none, as the program does. To open another tab, call newPage() on that same context.
Do not call browser.newContext(). A new context starts empty, without the cookies that a profile or a session context loads into the session. See CDP.
Close the connection and release the session
browser.close() ends Playwright's connection to the session. It does not end the session. The browser keeps running, and keeps costing browser time, until you call client.sessions.release() or the session times out. Close the browser first, then release the session, as the program does.
If the connection drops while the session still runs, connect again to the session's websocketUrl. If you no longer have the URL, client.sessions.retrieve() returns it. The pages and browser state are still there.
Features that change with a remote browser
- Launch options do not apply. Options such as
headless,proxyorargsbelong tochromium.launch(), which you no longer call. Set the matching options when you create the session, for exampleuseProxyfor a Steel proxy orsolveCaptchafor CAPTCHA solving. See Session configuration. - Downloads stay in the session. A file that the browser downloads is saved in the session, not on your machine. Get it with the Files API. See Files.
Next steps
- Stay signed in across sessions: Sign in once with Playwright, and start the next session signed in.
- Get past bot detection: Find out what blocked a page, and add a proxy or CAPTCHA solving.
- Run sessions at scale: Run many Playwright tasks at once, within your plan's limit.
- Playwright documentation: The library and its API, for TypeScript and for Python.
- Cookbook starters: TypeScript, Python and Go.