SOP 002: Connect with Playwright

Fresh

Field	Value
SOP ID	SOP-002
Version	1.0
Status	Active
Source	Playwright Guide

Overview

Connect Playwright to Steel sessions for browser automation. Two methods available: one-line change (simplest) or create-and-connect (full control).

Prerequisites

• steel-sdk and playwright installed
• Steel API key configured

Connection Methods

Method 1: One-Line Change (Easiest)

Replace your existing chromium.launch() with:

const browser = await chromium.connectOverCDP(
  'wss://connect.steel.dev?apiKey=MY_STEEL_API_KEY'
);

This auto-creates a session with default settings. Session releases when you call browser.close().

Custom Session ID

import { v4 as uuidv4 } from 'uuid';

const sessionId = uuidv4();
const browser = await chromium.connectOverCDP(
  `wss://connect.steel.dev?apiKey=${process.env.STEEL_API_KEY}&sessionId=${sessionId}`
);

Method 2: Create and Connect (Full Control)

import Steel from 'steel-sdk';
import { chromium } from 'playwright';

const client = new Steel({
  steelAPIKey: process.env.STEEL_API_KEY,
});

async function main() {
  // Create session with features
  const session = await client.sessions.create({
    useProxy: true,
    solveCaptcha: true,
  });

  // Connect Playwright
  const browser = await chromium.connectOverCDP(
    `wss://connect.steel.dev?apiKey=${process.env.STEEL_API_KEY}&sessionId=${session.id}`
  );

  // Use existing context for session recording
  const page = browser.contexts()[0].pages()[0];
  await page.goto('https://example.com');

  // Clean up
  await browser.close();
  await client.sessions.release(session.id);
}

main();

Important

Use browser.contexts()[0].pages()[0] instead of creating a new context. This ensures the session is recorded in the live viewer.

Verification Checklist

• [ ] Playwright connects via WebSocket without errors
• [ ] Page navigation works (page.goto())
• [ ] Session visible in live viewer
• [ ] Session properly released after automation

Troubleshooting

Issue	Solution
Connection refused	Check API key and session ID format
Session not recorded in viewer	Use existing context, don't create new one
Timeout on connect	Increase connection timeout, check network

See Also

• SOP 001: Create & Manage Sessions
• SOP 003: Configure Proxies