@dyyz1993/xpage

Browser automation engine library based on Playwright — recording, playback, page structure extraction, and command execution.

Overview

@dyyz1993/xpage is a powerful browser automation engine built on top of Playwright. It provides:

• Unified Command Interface — All operations through (page, args) => Promise<result>
• Recording & Playback — Record user interactions and replay them
• Page Structure Extraction — Get semantic layout trees
• Accessibility Tree — Extract ARIA accessibility information
• Command Chaining — Execute multiple commands in sequence

Install

npm install @dyyz1993/xpage

Requires Node.js >= 18.0.0.

Quick Start

Get started in minutes:

import { executePageCommand } from '@dyyz1993/xpage';
import { chromium } from 'playwright-core';

async function run() {
  const browser = await chromium.launch();
  const page = await browser.newPage();

  // Navigate
  await executePageCommand(page, 'goto', { url: 'https://example.com' });

  // Get title
  const { title } = await executePageCommand(page, 'title', {});
  console.log(title);

  // Take screenshot
  await executePageCommand(page, 'screenshot', { path: 'example.png' });

  await browser.close();
}

run();

See the Quick Start Guide for more examples.

Documentation

• Quick Start Guide — Get started in minutes
• API Reference — Complete API documentation
• Recording & Playback — Record and replay user actions
• Page Structure — Extract semantic layouts

Core Capabilities

1. Page Commands

Unified command interface, all operations via (page, args) => Promise<result>:

| Command | Description | Parameters | |---------|-------------|------------| | goto | Navigate to URL | url, waitUntil?, timeout? | | goBack | Go back | — | | goForward | Go forward | — | | reload | Reload page | — | | title | Get page title | — | | url | Get current URL | — | | click | Click element | selector, timeout?, force? | | fill | Fill input | selector, value, timeout? | | type | Type text | selector, text, delay? | | press | Press key | selector, key | | hover | Hover element | selector, timeout? | | scroll | Scroll page | selector?, x?, y? | | select | Select option | selector, value | | check | Check checkbox | selector | | waitForSelector | Wait for element | selector, timeout? | | query | CSS selector query | selector | | find | Find by text | text, tag?, exact? | | html | Get HTML | selector?, clean? | | text | Get text content | selector? | | textContent | Get element text | selector | | inputValue | Get input value | selector | | getAttribute | Get attribute | selector, name | | structure | Page structure extraction | selector?, maxDepth? | | screenshot | Screenshot to file | path?, fullPage? | | screenshotBase64 | Screenshot as Base64 | fullPage?, type? | | a11y | Accessibility tree | selector?, format? | | snapshot | ARIA snapshot | selector? | | evaluate | Execute JS expression | expression | | evaluateRaw | Execute async JS | script | | wait | Wait milliseconds | timeout |

import { executePageCommand } from '@dyyz1993/xpage';
import { chromium } from 'playwright-core';

const browser = await chromium.launch();
const page = await browser.newPage();

await executePageCommand(page, 'goto', { url: 'https://example.com' });
const { title } = await executePageCommand(page, 'title', {});
const { snapshot } = await executePageCommand(page, 'snapshot', { selector: 'body' });

await browser.close();

2. Recorder (RecorderController)

Record user actions in a real browser, producing structured YAML.

import { RecorderController } from '@dyyz1993/xpage';

const recorder = new RecorderController(page);
await recorder.start({ url: 'https://example.com', name: 'my-recording' });
// ... user interacts with browser ...
const { path, session } = await recorder.stop('./recordings/my-recording.yaml');

3. Player (PlaybackEngine)

Load recordings and replay them automatically.

import { PlaybackEngine } from '@dyyz1993/xpage';

const player = await PlaybackEngine.fromFile(page, './recordings/my-recording.yaml');
const result = await player.play({ slowMo: 1, stopOnError: true });

4. Structure Extraction

Extract semantic layout tree from pages.

const { structure, yaml } = await executePageCommand(page, 'structure', { selector: 'body' });

5. Accessibility Tree

const { snapshot } = await executePageCommand(page, 'a11y', { selector: 'main', format: 'yaml' });
const { snapshot } = await executePageCommand(page, 'snapshot', { selector: 'body' });

API Reference

Command Execution

import { executePageCommand, getCommandHandler, hasCommand } from '@dyyz1993/xpage';

const handler = getCommandHandler('click');
const exists = hasCommand('goto');
const result = await executePageCommand(page, 'click', { selector: '#btn' });

Command Definitions & Parsing

import { commands, getCommandNames, parseArgsToRecord, parseCommandChain } from '@dyyz1993/xpage';

commands['goto'].schema;
getCommandNames();
const parsed = parseCommandChain('goto url=https://example.com && click selector=#btn');

Client IPC

import { executeCommand, executePipeline, executeCommandChain, sendRequest } from '@dyyz1993/xpage';

Session Management

import {
  ensureStorage, getSessionPath, loadSessionInfo,
  saveSessionInfo, deleteSessionInfo, listSessions,
} from '@dyyz1993/xpage';

Related Projects

• @dyyz1993/xcli-core — Plugin-based CLI framework built on this engine
• create-xcli — Project scaffolding tool
• @dyyz1993/xcli-browser — Browser domain reference implementation

Development

npm run typecheck   # Type check
npm run lint        # ESLint
npm run build       # Build (tsup)
npm test            # Run tests
npm run validate    # typecheck + lint + build + test

License

MIT