Connect with Playwright (Python)

This guide shows you how to drive Steel's cloud browser sessions using Playwright with Python. Looking for Node.js/TypeScript? Check out our Playwright Node.js guide.

Steel sessions are designed to be easily driven by Playwright. There are two main methods for connecting to & driving a Steel session with Playwright.

Method #1: One-line change (easiest)Copied!

Most Playwright scripts start with chromium.launch() function to launch your browser with desired args that looks something like this:

browser = chromium.launch()

Simply change this line to the following (replacing MY_STEEL_API_KEY with your api key):

browser = chromium.connect_over_cdp(
    'wss://connect.steel.dev?apiKey=MY_STEEL_API_KEY'
)

and voila! This will automatically start and connect to a Steel session for you with all default parameters set. Your subsequent calls will work as they did previously.

When you're done, the session automatically releases when your script calls browser.close(), browser.disconnect(), or ends the connection.

Advanced: Custom Session IDs

This doesn’t support other UTM parameters to add args (that is what Method #2 is for) other than one - sessionId. This allows you to set a custom session id (UUIDv4 format) for the session.

This is helpful because you don’t get any data returned from connecting like this but by setting your own session ID, you can use the API/SDKs to retrieve data or taking actions on the session like manually releasing it.

Example:

from uuid import uuid4
from playwright.sync_api import sync_playwright

session_id = str(uuid4())  # '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'

playwright = sync_playwright().start()
browser = playwright.chromium.connect_over_cdp(
    f'wss://connect.steel.dev?apiKey={os.getenv("STEEL_API_KEY")}&sessionId={session_id}'
)

Method #2: Create and connectCopied!

Use this method when you need to drive a session with non-default features like proxy support or CAPTCHA solving. The main difference is that you'll:

1. Start a session via API

2. Connect to it via chromium.connect_over_cdp()

3. Release the session when finished

import os
from dotenv import load_dotenv
from playwright.sync_api import sync_playwright
from steel import Steel

load_dotenv()

client = Steel(
    steel_api_key=os.getenv('STEEL_API_KEY'),
)

def main():
    # Create a session with additional features
    session = client.sessions.create(
        use_proxy=True,
        solve_captcha=True,
    )

    # Connect with Playwright
    playwright = sync_playwright().start()
    browser = playwright.chromium.connect_over_cdp(
        f'wss://connect.steel.dev?apiKey={os.getenv("STEEL_API_KEY")}&sessionId={session.id}'
    )

    # Create page at existing context to ensure session is recorded.
    currentContext = browser.contexts[0]
    page = currentContext.new_page()

    # Run your automation
    page.goto('https://example.com')

    # Always clean up when done
    browser.close()
    client.sessions.release(session.id)

if __name__ == "__main__":
    main()

Important: With Method #2, sessions remain active until explicitly released or timed out. It’s best practise to call client.sessions.release() when finished instead of waiting for the session to timeout to be released.

Example Project: Scraping Hacker NewsCopied!

Here's a working example that scrapes Hacker News with proper error handling and session management:

To run it:

1. Add your STEEL_API_KEY to the secrets pane. It's located under "Tools" on the left hand pane.

2. Hit Run

The example includes:

• Complete session configuration options

• Error handling best practices

• A working Hacker News scraper example

You can also clone it on Github or Replit to start editing it yourself!