Kitesurf

Extends CDPBrowser

Kitesurf is a cloud browser helper that extends CDPBrowser to run tests against Cloudflare’s Browser Run service (Kitesurf browser). It automates real browser sessions in Cloudflare’s cloud infrastructure, eliminating the need to manage local browser instances.

Status: Beta

Requirements

Cloudflare account with Browser Run enabled
API token with Browser Rendering Edit permission

Setup

To create an API token with Browser Rendering Edit permission:

Log in to your Cloudflare dashboard
Go to My Profile > API Tokens
Click “Create Token”
Use the “Custom token” template
Under “Permissions”, select “Browser Rendering” > “Edit”
Set the account scope to your target account
Copy the token and set it as CF_API_TOKEN environment variable

For more details, see:

Example

{
  helpers: {
    Kitesurf: {
      url: 'https://example.com',
      accountId: process.env.CF_ACCOUNT_ID,
      apiToken: process.env.CF_API_TOKEN,
    }
  }
}

Or set environment variables and rely on defaults:

export CF_ACCOUNT_ID="your-account-id"
export CF_API_TOKEN="your-api-token"

Configuration

This helper should be configured in codecept.conf.js. It accepts everything CDPBrowser accepts (see its config table), plus:

Type: object

Properties

url string? base URL for tests
accountId string? Cloudflare account ID; defaults to CF_ACCOUNT_ID env var
apiToken string? Cloudflare API token; defaults to CF_API_TOKEN env var
keepAlive number? session keep-alive time in milliseconds
apiBase string? Cloudflare API base URL
input string? input method for user actions; defaults to ‘cdp’ for Kitesurf’s real layout engine, but can be overridden
capabilities object? pre-configured capabilities; Kitesurf uses { layout: ‘real’, screenshot: true }

Methods

Parameters

config KitesurfConfig

_finishTest

Closes the target as CDPBrowser._finishTest does, then releases the cloud session acquired in _resolveEndpoint via the Cloudflare API so it does not linger for the full keepAlive window. The release runs in a finally so a rejection while closing the CDP connection still frees the cloud session instead of leaving the browser alive until keepAlive expires; the session id is cleared before the request, so a repeated call never releases it twice.

_resolveEndpoint

Acquires a Kitesurf browser session from the Cloudflare Browser Run API and resolves it to the wss:// debugger URL CDPConnection connects to. Overrides CDPBrowser._resolveEndpoint, which resolves a fixed local endpoint instead of provisioning a cloud session per test.

Returns Promise<string> a wss:// debugger URL ready to be passed to CDPConnection.