Browser

The Browser entity launches a headless Chromium browser via Playwright, exposing a WebSocket endpoint for remote automation.

Prerequisites

Install the Chromium binary (one-time setup):

bunx playwright install chromium

Import

import { Browser } from "sigil";

Constructor

new Browser(name: string, config?: Partial<Omit<BrowserConfig, "name">>)

Config

interface BrowserConfig {
  name: string
  headless?: boolean          // default: true
  viewport?: {
    width: number             // default: 1280
    height: number            // default: 720
  }
}

Properties

browserInterface

browser.browserInterface: BrowserInterface

The WebSocket interface. Provides the WebSocket endpoint for connecting automation tools.

wsEndpoint

browser.wsEndpoint: string

Convenience getter for the WebSocket URL. Returns an empty string before start() is called.

status

Inherited from Entity. One of: "pending", "starting", "running", "stopping", "stopped", "error".

Lifecycle

start()

1. Calls chromium.launchServer() from playwright-core
2. Sets the WebSocket endpoint on the BrowserInterface
3. Logs the WS URL for connection

If Chromium is not installed, prints a helpful error message directing you to run bunx playwright install chromium.

stop()

Closes the browser server and releases all resources.

Examples

Basic usage

const browser = env.add(
  new Browser("chrome", { headless: true })
);

// After env.up(), the WS endpoint is available:
console.log(browser.wsEndpoint);
// "ws://localhost:54321/abc123..."

Connecting from Playwright

import { chromium } from "playwright-core";

// Connect to the Sigil-managed browser
const browser = await chromium.connect(sigilBrowser.wsEndpoint);
const page = await browser.newPage();
await page.goto("http://localhost:3000");

In a full-stack environment

import { Environment, Postgres, Service, Browser, APIInterface, BrowserInterface } from "sigil";

const env = new Environment("my-app");

const db = env.add(new Postgres("db", { database: "myapp" }));

env.add(
  new Service("backend", {
    command: ["node", "server.js"],
    env: { DATABASE_URL: db.connectionString },
    readyCheck: { url: "http://localhost:8000/health" },
  }, [new APIInterface(8000)])
);

env.add(
  new Service("frontend", {
    command: ["bun", "run", "dev"],
    readyCheck: { url: "http://localhost:3000" },
  }, [new BrowserInterface(3000)])
);

// Browser starts last — all services are ready
env.add(new Browser("chrome", { headless: true }));

export default env;