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

> Discover Playwright-compatible browser facade APIs in ego-lite, including page, locator, and browser objects, for powerful agent-based browser automation.

- Repository: [CitroLabs/ego-lite](https://github.com/citrolabs/ego-lite)
- Tags: api-reference
- Published: 2026-08-22

---

**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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/driver/pointer.ts) for mouse actions and [`driver/keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/driver/keyboard.ts) for key events.
- **[`package/ego-browser/src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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

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

```

### Element Interaction and Form Handling

```typescript
// 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

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

```

### Multi-Tab Management

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

```

### Complex Interactions

```typescript
// 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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/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`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/pointer.ts) and [`package/ego-browser/src/driver/keyboard.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/driver/keyboard.ts). Navigation and evaluation use [`package/ego-browser/src/cdp-eval.ts`](https://github.com/citrolabs/ego-lite/blob/main/package/ego-browser/src/cdp-eval.ts) and [`package/ego-browser/src/browser-runtime.ts`](https://github.com/citrolabs/ego-lite/blob/main/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.