Browser Facade APIs in ego-lite: Playwright-Compatible Methods for Browser Automation

The ego-lite framework provides Playwright-style browser facade APIs—including page, locator, and browser objects—exposed through helperContext() to enable high-level browser automation in agent scripts.

The browser facade APIs in ego-lite emulate Playwright's programming model, allowing AI agents to navigate, interact with DOM elements, and manage browser tabs using familiar async/await patterns. These facades are defined in package/ego-browser/src/helpers.ts and automatically injected into helper contexts, providing a rich surface for web automation without requiring direct Chrome DevTools Protocol (CDP) manipulation.

The Three Core Browser Facades

The helperContext() function in ego-lite assembles three primary facades that mirror Playwright's architecture. Each facade delegates to low-level driver implementations while exposing a clean, promise-based API.

The Page Facade

The page facade handles navigation, viewport management, and global page state. Located in package/ego-browser/src/helpers.ts (lines 84-108), it exposes methods for controlling the browser lifecycle and locating elements.

Key methods include:

• setDefaultTimeout(ms) – Configures implicit wait timeouts
• goto(url) – Navigates to a specific URL
• reload([options]) – Refreshes the current page
• url() and title() – Retrieve current page metadata
• evaluate(expression) – Execute JavaScript in the page context
• screenshot(options) – Capture full-page or element-specific images
• waitForLoadState(state, options) – Pause execution until network becomes idle or DOM loads

The page facade also provides locator factory methods that return locator instances:

• locator(selector) – CSS selector-based targeting
• getByRole(role, options) – ARIA role-based selection
• getByText(text, options) – Text content matching
• getByLabel(text, options), getByPlaceholder(text, options), getByAltText(text, options), getByTitle(text, options) – Semantic attribute targeting
• getByTestId(testId) – Data attribute selection

The Locator Facade

The locator facade represents a collection of DOM elements and provides actions and assertions. Returned by page.locator() or the getBy* shortcuts, these methods are defined in package/ego-browser/src/helpers.ts (lines 20-71).

Interaction methods include:

• click([options]), dblclick([options]), hover([options]) – Pointer events
• fill(value, [options]), clear([options]) – Form input handling
• press(key, [options]), pressSequentially(text, [options]) – Keyboard simulation
• check(), uncheck(), setChecked(checked) – Checkbox manipulation
• selectOption(values) – Dropdown selection
• setInputFiles(files) – File upload simulation
• dragTo(target, [options]) – Drag-and-drop operations
• scrollIntoViewIfNeeded(), focus(), blur() – Element state management

State inspection methods include:

• textContent(), innerText(), innerHTML(), inputValue() – Content extraction
• isVisible(), isHidden(), isEnabled(), isDisabled(), isEditable(), isChecked() – Boolean state checks
• getAttribute(name), boundingBox() – Property access
• count(), allInnerTexts(), allTextContents() – Multi-element queries

Advanced features include:

• evaluate(pageFn, arg) and evaluateAll(pageFn, arg) – Execute scripts in element context
• screenshot([options]) – Capture element-specific images
• waitFor([options]) – Auto-waiting for element visibility

The Browser Facade

The browser facade manages multi-tab contexts and session-level operations. Implemented in package/ego-browser/src/helpers.ts (lines 73-82), it provides tab orchestration capabilities essential for complex workflows.

Available methods:

• listTabs() – Enumerate open tabs
• currentTab() – Get the active tab identifier
• switchTab(target) – Change active tab context
• openOrReuseTab(url, options) – Create or recycle tabs
• closeTab(target) – Terminate specific tabs
• ensureRealTab() – Validate tab existence before operations
• iframeTarget() – Handle nested frame contexts

Implementation Architecture

The browser facade APIs in ego-lite rely on several supporting modules that handle the underlying CDP communication:

• package/ego-browser/src/helpers.ts – Central hub assembling the facades and exporting helperContext() and help() functions. Contains the FACADE_HELP map documenting all available methods.
• package/ego-browser/src/driver/* – Low-level drivers for specific input types, including driver/pointer.ts for mouse actions and driver/keyboard.ts for key events.
• package/ego-browser/src/cdp-eval.ts – Provides JavaScript evaluation capabilities used by page.evaluate() and locator methods.
• package/ego-browser/src/browser-runtime.ts – Manages CDP transport sessions and browser instance lifecycle.

Practical Usage Examples

The following examples demonstrate typical patterns using the ego-lite browser facades:

Navigation and Page Information

await page.goto('https://example.com');
const currentUrl = await page.url();
const pageTitle = await page.title();

Element Interaction and Form Handling

// Direct locator usage
const submitButton = page.locator('button.submit');
await submitButton.waitFor();
await submitButton.click();

// Playwright-style shortcuts
await page.getByText('Accept terms').click();
await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');

// Keyboard simulation
await page.keyboard.type('Hello, world!');

Screenshots and Visual Testing

const logo = page.getByAltText('Company logo');
await logo.screenshot({ path: 'logo.png' });

Multi-Tab Management

await browser.openOrReuseTab('https://news.ycombinator.com');
await browser.switchTab(2);
await browser.closeTab(2);

Complex Interactions

// Drag and drop
const source = page.getByTestId('draggable-item');
const target = page.getByTestId('drop-zone');
await source.dragTo(target);

// File upload
const fileInput = page.getByLabel('Upload document');
await fileInput.setInputFiles(['/path/to/file.pdf']);

// Sequential key presses
const searchBox = page.getByPlaceholder('Search...');
await searchBox.pressSequentially('ego-lite browser API');
await searchBox.press('Enter');

Summary

• ego-lite provides Playwright-compatible browser facades through helperContext(), exposing page, locator, and browser objects.
• The page facade in package/ego-browser/src/helpers.ts handles navigation, screenshots, and locator factories like getByRole() and getByText().
• The locator facade offers 30+ methods for element interaction, including click(), fill(), screenshot(), and state checks like isVisible().
• The browser facade manages tab lifecycle with openOrReuseTab(), switchTab(), and closeTab().
• Use help('page') or help('locator') in scripts to access inline documentation from the FACADE_HELP map.
• Low-level implementations reside in package/ego-browser/src/driver/ and CDP evaluation modules.

Frequently Asked Questions

How do I access the browser facade APIs in ego-lite?

Access the facades through the helperContext() function, which is automatically injected into agent scripts running within the ego-lite environment. Once injected, page, locator, and browser objects are available globally, or you can destructure them from the context. Use the help() function (e.g., help('page')) to retrieve inline documentation for any facade method.

What is the difference between page.locator() and getByText()?

page.locator() accepts a raw CSS selector string and returns a locator instance for that query. In contrast, getByText() is a semantic helper that constructs a locator based on visible text content, similar to Playwright's text-based selection. Both return locator objects with identical interaction methods, but getByText() and other getBy* methods (like getByRole or getByLabel) provide more resilient, accessibility-driven targeting that survives DOM structure changes.

Can I use async/await with these facade methods?

Yes, all browser facade APIs in ego-lite return Promises and are designed for async/await patterns. Methods like goto(), click(), fill(), and screenshot() are asynchronous operations that wait for the underlying CDP commands to complete. This enables sequential, readable automation code that handles implicit waiting and network idle states automatically.

Where are the Playwright-style methods actually implemented?

The facade interfaces are defined in package/ego-browser/src/helpers.ts, which aggregates methods from specialized driver modules. Mouse and keyboard actions delegate to package/ego-browser/src/driver/pointer.ts and package/ego-browser/src/driver/keyboard.ts. Navigation and evaluation use package/ego-browser/src/cdp-eval.ts and package/ego-browser/src/browser-runtime.ts for Chrome DevTools Protocol communication. This modular architecture separates the high-level Playwright-compatible API from low-level browser control logic.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}