Selenwright

Connect Playwright to Selenwright’s native WebSocket endpoint:

The Playwright client version and browser image version must match on major and minor version. For example, Playwright 1.56.x should connect to a Selenwright browser entry built for 1.56.x.

Run existing Selenium tests against the WebDriver compatibility endpoint:

If something does not work, you can check that Selenwright is running by opening the status URL:

A successful request should return JSON with browser usage statistics.

To open Selenwright UI navigate to the following page in your browser:

There are two ways to populate the browser catalog:

Where are Selenwright logs?

Selenwright outputs its logs to stdout. Selenwright launched as a binary should output logs to the screen. To see Selenwright logs launched as Docker container type:

To follow the logs add one more flag:

Where are recorded videos stored?

Videos are saved to the directory specified by -video-output-dir flag (default video relative to the working directory). When running in Docker, mount a host directory to this path — see Video Recording for details.

How can I limit overall browsers consumption?

You have to use -limit flag to specify total number of parallel sessions. Default value is 5. See Resources Consumption section on how to determine total number of parallel sessions.

Can I limit per-version browser consumption?

No, this is not supported. We consider the only reasonable limitation should be the overall browsers consumption. This is important to not overload the hardware.

How can I adjust Selenwright timeouts?

The main timeout flag is -timeout, specified as 60s or 2m or 1h. It means maximum amount of time between subsequent HTTP requests to Selenium API. When there are no requests during this time period - session is automatically closed. Selenwright also has more subtle timeouts like:

How many resources browser containers consume?

This depends on your tests. We recommend to start with 1 CPU and 1 Gb of memory per container as a rough estimate and then increase -limit checking that your tests work stably.

Do VNC and non-VNC browser images memory and CPU consumption differ?

The only difference between these images - is a running VNC server (x11vnc) consuming approximately 20 Megabytes of RAM in idle state which is negligible compared to browser memory consumption.

Video feature not working

When running Selenwright as Docker container video feature can be not working (because of misconfiguration). If your video files are named like selenwright607667f7e1c7923779e35506b040300d.mp4 and you are seeing the following log message…​

... then check that:

Can’t get VNC feature to work: Disconnected

Please check that you have enableVNC = true capability in your tests

Can Selenwright pull browser images automatically?

Selenwright does not auto-pull images during session creation to avoid unpredictable latency under load. However, you can use the Browser Discovery feature to scan images already present on the host and adopt them into the catalog. For stack-wide updates, see Docker Compose Stack Management.

Use the following endpoint:

Where:

This route accepts WebSocket connections only.

When a client connects to /playwright/<browser>/<playwright-version>, Selenwright resolves the matching browser entry, starts the container, and registers a session after the WebSocket tunnel is established.

Playwright sessions follow the same operational model as WebDriver sessions:

Companion Playwright images are external to this repository. To work with Selenwright they should follow this contract:

Optional labels mirror the per-field names in browsers.json: tmpfs, env, volumes, hosts, shmSize, mem, cpu, labels, sysctl. As an escape hatch, io.selenwright.config accepts a full Browser JSON blob; when present, per-field labels are ignored. See selenwright-browsers for a working example.

At startup Selenwright prefers Docker HEALTHCHECK when the image provides one. If health status is unavailable, Selenwright falls back to protocol-specific probing. For Playwright images that fallback is a TCP probe against the configured Playwright endpoint.

Playwright client and server versions must match on major and minor version.

For example, a client from Playwright 1.56.x should connect to an image built for Playwright 1.56.x. Keep the image tag, the configured Selenwright version entry, and the client connection URL aligned.

An example browser catalog entry for a native Playwright image (via browsers.json or Browser Discovery):

Selenwright publishes matching companion images — see Browser Images for the full list.

Connect from Playwright with the dedicated Selenwright WebSocket endpoint:

File uploads (page.setInputFiles()) and downloads (page.download()) work natively through the Playwright WebSocket protocol. Selenwright proxies the connection transparently — no additional configuration is needed.

A subset of Special Capabilities can be passed as query parameters on the WebSocket URL:

Supported: enableVNC, name, screenResolution.

Session logs (Playwright protocol messages) are captured automatically when artifact history is enabled.

Selenwright honors X-Selenwright-External-Session-ID on the Playwright upgrade request. When the header is present and valid, its value replaces the auto-generated session ID and is used as-is for:

The header is intended for routers (e.g., gridlane) that need to encode routing metadata into the public session ID before the upgrade reaches selenwright — otherwise the router’s advertised ID would not match the one selenwright stored, and side endpoints would 404.

The value must match [a-zA-Z0-9_-]{1,128}; invalid values and collisions with existing sessions are rejected with 400 Bad Request before any browser container is started.

If the header is absent or blank, selenwright falls back to an internally generated 32-hex ID (the original behavior); standalone Playwright clients are unaffected.

You can access recorded video files using the following URL:

To see all available files use:

When Artifact History is enabled, video files are automatically cleaned up by the retention janitor. Otherwise, to limit storage space consumption you have two alternatives:

You can access saved log files using the following URL:

To see all available files use:

When Artifact History is enabled, log files are automatically cleaned up by the retention janitor. Otherwise, either remove log files from the directory using a scheduled job or send log removal requests:

When Selenwright is started with -enable-file-upload, an additional route is registered:

The zip archive must contain exactly one file. Selenwright extracts it into a per-session temp directory and returns that path.

If the flag is not set the route is not registered and the server replies 404 Not Found. Selenium clients that use LocalFileDetector will transparently fall back to the driver-level upload when that happens — you usually do not need to handle 404 yourself.

Both limits reject over-sized requests with 400 Invalid Argument and close the connection — the zip is never written to disk past the limit.

Your tests may need to download files with browsers. To analyze these files a common requirement is then to somehow extract downloaded files from browser containers. A possible solution can be dealing with container volumes. But Selenwright provides a /download API and dramatically simplifies downloading files. Having a running session f2bcd32b-d932-4cdc-a639-687ab8e4f840 you can access all downloaded files using an HTTP request:

In order for this feature to work an HTTP file server should be listening inside browser container on port 8080. Download directory inside container to be used in tests is usually ~/Downloads.

Similarly to delete downloaded files replace GET request with DELETE:

Selenwright supports showing browser screen during test execution. This works with containers having VNC server installed (VNC column of [Browser Image information]). To see browser screen:

Then launch Selenwright UI to see the screen.

This works by proxying VNC port from started container to http://localhost:4444/vnc/<session-id>; to WebSocket, where <session-id> is Selenium session ID.

Selenwright allows you to set custom screen resolution in containers being run:

To enable video recording for session, add:

To enable saving logs for a session, add:

If you wish to automatically save logs for all sessions, you can enable this behavior globally with Selenwright -save-all-logs flag.

By default saved log files are named <session-id>.log where <session-id> is a unique identifier of Selenium session. To provide custom log file name specify:

For debugging purposes it is often useful to give a distinct name to every test case. When working with Selenwright you can set test case name by passing the following capability:

The main application of this capability - is debugging tests in the UI which is showing specified name for every running session.

Sometimes you may want to change idle timeout for selected browser session. To achieve this - pass the following capability:

Timeout is specified Golang duration format e.g. 30m or 10s or 1h5m and can be no more than the value set by -max-timeout flag.

Some tests require particular time zone to be set in operating system. To achieve this with Selenwright use:

You can find most of available time zones here. Without this capability launched browser containers will have the same timezone as Selenwright one.

Override the hostname of the browser container:

Sometimes you may want to set some environment variables for every test case (for example to test with different default locales). To achieve this pass one more capability:

Environment variables from this capability are appended to variables from configuration file.

Sometimes you may need to link browser container to application container running on the same host machine. This allows you to use cool URLs like http://my-cool-app/ in tests. To achieve this simply pass information about one or more desired links via capability:

Although you can configure a separate list of /etc/hosts entries for every browser image in Browsers Configuration File sometimes you may need to add more entries for particular test cases. This can be easily achieved with:

Entries will be inserted to /etc/hosts before entries from browsers configuration file. Thus entries from capabilities override entries from configuration file if some hosts are equal.

By default Selenwright browser containers are using global DNS settings of Docker daemon. Sometimes you may need to override used DNS servers list for particular test cases. This can be easily achieved with:

By default Selenwright browser containers are started in Docker network specified by -container-network flag. If you tested application is running in another network you may need to connect browser container to this network:

In big clusters you may want to pass additional metadata to every browser session: environment, VCS revision, build number and so on. These labels can be then used to enrich session logs and send them to a centralized log storage. Later this metadata can be used for more efficient search through logs.

Labels from this capability override labels from browsers configuration file. When name capability is specified - it is automatically added as a label to container.

This capability allows to override S3 key pattern (specified by -s3-key-pattern flag) used when uploading files to S3.

The same key placeholders are supported. Please refer to Uploading Files To S3 section for more details.

Some Selenium clients allow passing only a limited number of capabilities specified in WebDriver specification. For such cases Selenwright supports reading capabilities using WebDriver protocol extensions feature. The following two examples deliver the same result. Usually capabilities are passed like this:

Selenwright reads the selenoid:options key for protocol extension capabilities (kept for backward compatibility with existing test suites):

Returns the current artifact history configuration:

Updates artifact history settings. Changes take effect immediately.

This endpoint does not require authentication (open path).

Persisted downloads are served at:

The ?json parameter returns a JSON listing instead of the HTML directory view. Individual files can be downloaded directly by path.

Log files and videos are available at their respective endpoints (/logs/, /video/) as documented in Saving Session Logs and Video Recording.

All mutation endpoints require admin access (see Authentication and Authorization).

Sending SIGHUP to the Selenwright process also triggers a catalog rebuild from the current adopted set.

Selenwright detects its own Compose deployment by reading Docker container labels (com.docker.compose.project, com.docker.compose.service, etc.) from its own container. When these labels are present, the stack management endpoints become available.

Selenwright can expose a Prometheus-compatible metrics endpoint for monitoring session usage and server health.

The metrics endpoint is not gated by the configured authenticator. It is expected to live behind the same network boundary as the Prometheus scraper.

When -log-json is set, Selenwright emits logs as one JSON object per line with fields: event, request_id, fields, level, time. Default is the legacy bracketed text format.

The -event-workers flag (default 16) controls the number of goroutines that dispatch session-lifecycle events (FileCreated, SessionStopped) to registered listeners such as S3 upload handlers. Bounds fan-out so a single slow listener cannot leak goroutines.

Selenwright uses a standard htpasswd file with bcrypt passwords. Create it with Docker:

This creates a file users.htpasswd with two users: alice and bob. To add more users later, run the same command again — it appends to the file.

Pass the -htpasswd flag pointing to this file. As a binary:

As a Docker container — mount the file and pass the flag:

Or in Docker Compose:

Now alice and bob can create sessions using HTTP Basic Auth:

htpasswd passwords are the right fit for humans logging into the UI. For Playwright/Selenium clients running in CI or on a developer’s laptop, selenwright supports bearer tokens so credentials never need to be pasted into a URL (where they leak into shell history, logs, and screenshots).

An admin mints a token on behalf of a user, the user drops it into SELENWRIGHT_TOKEN (or however the client reads secrets), and the client sends Authorization: Bearer <token> with every request. The token inherits the owner’s groups at creation time, so group-based session ACL still applies.

Tokens are stored hashed (bcrypt) in <state-dir>/auth/tokens.json. Plaintext is shown to the admin once — distribute it through a secret manager (1Password, Bitwarden, Keybase). Never paste tokens into Slack, tickets, or email.

By default all users are regular (non-admin). To promote users to admin, list them in -admin-users:

Now alice is admin, bob is a regular user. Admins can:

Edit the htpasswd file (add/remove/change passwords), then send SIGHUP:

Selenwright reloads the file without dropping running sessions.

You can disable auth entirely with either spelling:

--no-auth is a convenience alias for -auth-mode=none. Both are accepted on any listen address, including :4444. When the listen address is not a loopback interface, selenwright logs a warning that the service is reachable without authentication — the operator is responsible for network-level protection (firewall, overlay network, bastion, reverse proxy).

When authentication is enabled (-auth-mode=embedded or -auth-mode=trusted-proxy), these endpoints are deliberately left open and do not require a credential:

Everything else — /status, /config, /history/settings, /downloads/, /stack/status, /wd/hub/, /playwright/, /vnc/, /video/, /logs/, /download/, /clipboard/, /devtools/, the admin token REST surface — requires a valid BasicAuth header, bearer token, or session cookie. An anonymous scrape of /status was previously possible and leaked live session IDs, container IPs, and owner quotas; it now returns 401.

Human-readable Prometheus/Grafana setups still work: Prometheus scrapes /metrics (the open one), which carries lifecycle counters and queue depth gauges but none of the per-session detail that /status exposes.

Controlled by -auth-mode (default: embedded).

When using trusted-proxy mode, you need to ensure that only your proxy can reach Selenwright — otherwise anyone can set the X-Forwarded-User header. Source trust adds that protection. When multiple checks are configured, all must pass.

Source trust configuration is reloaded on SIGHUP.

Controlled by -caps-policy (default: strict).

Some capabilities give the user control over the container environment. Under strict policy, these are admin-only:

Regular users requesting these get a 400 error. Set -caps-policy=permissive to allow all users to use all capabilities (legacy behavior).

Every session is bound to the user who created it:

Ownership is enforced uniformly for both Selenium (DELETE /wd/hub/session/{id}) and Playwright (DELETE /playwright/session/{id}) termination, as well as for VNC, devtools, downloads, clipboard and live log endpoints.

The default user == owner rule is too narrow when sessions are created by a shared service account — for example, jenkins-bot launching tests from CI. Without groups, no human user can terminate those sessions through the UI except the admin.

Groups solve this. Members of the same group can manage each other’s sessions (including sessions owned by service accounts in the group). Admin behavior is unchanged.

You may want to limit memory and CPU consumption for each browser container. Use -mem and -cpu flags:

Values are specified in Docker format. -mem accepts units like 128m or 1g. -cpu is a float representing the number of CPUs per container.

These can also be set per-browser in the browser catalog — see Browsers Configuration File.

Browser name and version are just strings that are matched against Selenium desired capabilities:

For native Playwright connections the same entries are selected from the request path:

If no version capability is present default version is used. When there is no exact version match we also try to match by prefix. That means version string in JSON should start with version string from capabilities.

Image by default is a string with container specification in Docker format (hub.example.com/project/image:tag).

Image must be already pulled.

When running via Docker Compose, use the Docker Compose Stack Management endpoints (or the UI) to pull updated images and recreate the stack.

In that case bridge network mode should be used for all services:

In that case you have to add -container-network flag to Selenwright as follows:

By default Selenwright uses a bracketed text format:

Every line contains:

Not all fields are present in every line — it depends on the event type.

Pass -log-json to emit structured logs:

Session lifecycle: NEW_REQUEST, NEW_REQUEST_ACCEPTED, SESSION_ATTEMPTED, SESSION_CREATED, SESSION_DELETED, SESSION_TIMED_OUT, SESSION_FAILED, CLIENT_DISCONNECTED

Container management: CREATING_CONTAINER, STARTING_CONTAINER, CONTAINER_STARTED, CONTAINER_REMOVED, SERVICE_STARTED, SERVICE_STARTUP_FAILED

Playwright: PLAYWRIGHT_SESSION_CREATED, PLAYWRIGHT_SESSION_STOPPED, PLAYWRIGHT_CLIENT_DISCONNECTED, PLAYWRIGHT_UPSTREAM_DISCONNECTED

Features: VNC_ENABLED, DEVTOOLS_*, DOWNLOADING_FILE, UPLOADED_FILE, VIDEO_ERROR, LOG_ERROR

Discovery: DISCOVERY — browser image scanning, adopt, dismiss, catalog rebuild

Server: INIT, SIGHUP, SHUTTING_DOWN

When set, these checks are AND’d together — all configured conditions must pass.

See Uploading Files To Browser for the POST /file request format and size limits.

As a binary:

As a Docker container:

The following flags are supported by selenwright command when compiled with S3 support: