Playwright

Playwright connects to a Surfsky browser over the session’s CDP WebSocket URL instead of launching one itself. The browser runs in Surfsky’s cloud, so you do not need Chromium on your machine. To have a coding agent set this up in your project, give it the setup prompt.

Playwright has known leaks that anti-bot scripts can detect. On sites with bot protection, use a patched fork such as Patchright or rebrowser-playwright.

Use human-emulation commands for clicks, typing, and scrolling. Keep Playwright for navigation, selectors, waiting, and page content.

Prerequisites

Set your API token and base URL. The examples use your account’s default proxy pool. Proxy, fingerprint, and other start options are in the API reference.

Run an example

The examples use a one-time profile. To reuse a saved login, pass a persistent profile UUID to the session call instead.

Python (async)
JavaScript
Java
.NET

Requires Python 3.12 or newer.

pip install surfsky playwright

Save as surfsky_playwright.py:

import asyncio
from playwright.async_api import async_playwright
from surfsky import AsyncSurfsky


async def main():
    async with (
        AsyncSurfsky() as client,
        client.session() as session,
        async_playwright() as pw,
    ):
        browser = await pw.chromium.connect_over_cdp(session.connect_url)
        context = browser.contexts[0]
        page = context.pages[0] if context.pages else await context.new_page()
        await page.goto("https://example.com")
        print(await page.title())


asyncio.run(main())

Run it:

python surfsky_playwright.py

Requires Node.js 24 or newer, or Bun, for await using.

npm install surfsky playwright-core

Save as surfsky-playwright.mjs:

import { chromium } from "playwright-core";
import { Surfsky } from "surfsky";

const client = new Surfsky();
await using session = await client.session();
const browser = await chromium.connectOverCDP(session.ws_url);
try {
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  console.log(await page.title());
} finally {
  await browser.close();
}

Run it:

node surfsky-playwright.mjs

Add Playwright to your project using the official instructions. Start a browser with the REST quickstart and export the returned ws_url as SURFSKY_WS_URL.

import com.microsoft.playwright.*;

public class SurfskyExample {
    public static void main(String[] args) {
        String wsUrl = System.getenv("SURFSKY_WS_URL");
        try (Playwright playwright = Playwright.create()) {
            Browser browser = playwright.chromium().connectOverCDP(wsUrl);
            BrowserContext context = browser.contexts().get(0);
            Page page = context.pages().isEmpty() ? context.newPage() : context.pages().get(0);
            page.navigate("https://example.com");
            System.out.println(page.title());
            browser.newBrowserCDPSession().send("Browser.close");
        }
    }
}

dotnet add package Microsoft.Playwright

Start a browser with the REST quickstart and export the returned ws_url as SURFSKY_WS_URL. Put this in Program.cs:

using Microsoft.Playwright;

var wsUrl = Environment.GetEnvironmentVariable("SURFSKY_WS_URL");
using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Chromium.ConnectOverCDPAsync(wsUrl);
var context = browser.Contexts[0];
var page = context.Pages.Count > 0 ? context.Pages[0] : await context.NewPageAsync();
await page.GotoAsync("https://example.com");
Console.WriteLine(await page.TitleAsync());
var browserCdp = await browser.NewBrowserCDPSessionAsync();
await browserCdp.SendAsync("Browser.close");

Run with dotnet run.

Expected output:

Example Domain

Click, type, and scroll

Prefer human emulation over Playwright’s own click, fill, and scroll. Human.* commands move the cursor and type with human timing, and they run through a page-level CDP session. Replace the selector with an input on your page:

cdp = await page.context.new_cdp_session(page)
await cdp.send("Human.click", {"selector": "input[name='email']"})
await cdp.send("Human.type", {"text": "[email protected]"})
await cdp.send("Human.scroll", {"deltaY": 600, "duration": 1.2})

const cdp = await page.context().newCDPSession(page);
await cdp.send("Human.click", { selector: "input[name='email']" });
await cdp.send("Human.type", { text: "[email protected]" });
await cdp.send("Human.scroll", { deltaY: 600, duration: 1.2 });

CDPSession cdp = page.context().newCDPSession(page);
cdp.send("Human.click", com.google.gson.JsonParser.parseString(
    "{\"selector\":\"input[name='email']\"}").getAsJsonObject());
cdp.send("Human.type", com.google.gson.JsonParser.parseString(
    "{\"text\":\"[email protected]\"}").getAsJsonObject());
cdp.send("Human.scroll", com.google.gson.JsonParser.parseString(
    "{\"deltaY\":600,\"duration\":1.2}").getAsJsonObject());

var cdp = await page.Context.NewCDPSessionAsync(page);
await cdp.SendAsync("Human.click", new() { ["selector"] = "input[name='email']" });
await cdp.SendAsync("Human.type", new() { ["text"] = "[email protected]" });
await cdp.SendAsync("Human.scroll", new() { ["deltaY"] = 600, ["duration"] = 1.2 });

Stop the session

Playwright’s browser.close() only disconnects from a browser attached over CDP. Without the SDK, stop it through CDP as the Java and .NET examples do. In async Python:

cdp = await browser.new_browser_cdp_session()
await cdp.send("Browser.close")

or through the API with the internal_uuid from the start response:

curl --fail-with-body -X POST \
  "$SURFSKY_API_BASE_URL/profiles/INTERNAL_UUID/stop" \
  -H "X-Cloud-Api-Token: $SURFSKY_API_TOKEN"

Otherwise the browser stops after the inactivity timeout.

Get started

Connect your tools

Browser sessions

Browser actions

CAPTCHA guides

Debugging

Performance and limits

About Surfsky

Prerequisites

Run an example

Click, type, and scroll

Stop the session

​Prerequisites

​Run an example

​Click, type, and scroll

​Stop the session

Prerequisites

Run an example

Click, type, and scroll

Stop the session