obscura/docs/Use-with-Playwright.md

Setup

obscura serve --port 9222
npm install playwright

Connect

const { chromium } = require('playwright');

const browser = await chromium.connectOverCDP('ws://127.0.0.1:9222');
const context = browser.contexts()[0] || await browser.newContext();
const page = await context.newPage();

Use connectOverCDP, not connect. Playwright's connect speaks Playwright's own protocol.

Navigate

await page.goto('https://example.com');
await page.goto('https://example.com', { waitUntil: 'load' });
await page.goto('https://example.com', { waitUntil: 'networkidle' });

Default is domcontentloaded. Other values: load, networkidle.

Evaluate

const title = await page.evaluate(() => document.title);

const items = await page.$$eval('.item', els => els.map(el => ({
  text: el.textContent,
  href: el.querySelector('a')?.href,
})));

SVG element interfaces

SVG nodes created with document.createElementNS or parsed from SVG markup expose their corresponding interfaces, such as SVGImageElement and SVGUseElement, with prototype ancestry from the SVG IDL and Filter Effects IDL. This supports interface checks in page scripts; it does not imply support for every SVG property, method or rendering feature.

Interact

await page.click('#login-button');
await page.fill('#username', 'alice');
await page.fill('#password', 'secret');

await page.waitForSelector('#dashboard');
await page.waitForFunction(() => window.appReady === true);

Locators

await page.locator('button.submit').click();
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByLabel('Email').fill('alice@example.com');

Cookies

await context.addCookies([{
  name: 'session',
  value: 'abc123',
  domain: 'example.com',
  path: '/',
}]);

const cookies = await context.cookies();

Intercept requests

await page.route('**/*', route => {
  if (route.request().resourceType() === 'image') {
    route.abort();
  } else {
    route.continue();
  }
});

JavaScript heap measurements

const client = await context.newCDPSession(page);
await client.send('HeapProfiler.collectGarbage'); // Optional explicit collection.
const heap = await client.send('Runtime.getHeapUsage');
console.log(heap.usedSize, heap.totalSize, heap.backingStorageSize);
await client.detach();

These are native V8 isolate byte counts, not process memory. Reading them does not run page tasks or force collection. embedderHeapUsedSize is zero because Obscura's Rust DOM is not a V8-managed cppgc heap; Rust allocations and renderer memory are not included.

Application timing

Page scripts can record performance.mark() and performance.measure() entries, retrieve them through the timeline getters, and observe them through PerformanceObserver, including buffered delivery. Measurement options accept named marks or numeric timestamps; detail is structured-cloned.

PerformanceObserver.supportedEntryTypes reports mark and measure only. Navigation, resource, paint, and long-task entries are not emitted. User Timing entries remain available until cleared or the realm is destroyed; applications that continuously record timings should call clearMarks() and clearMeasures(). Legacy performance.timing is still incomplete; measurements using navigation milestone names are not yet reliable.

Multiple pages

const page1 = await context.newPage();
const page2 = await context.newPage();

await Promise.all([
  page1.goto('https://a.example.com'),
  page2.goto('https://b.example.com'),
]);

Pages share one V8 isolate. CPU-bound JS on one page blocks the others.

Screenshots, scrolling, and PDF

await page.setViewportSize({ width: 1440, height: 1000 });
await page.screenshot({ path: 'viewport.png' });

await page.evaluate(() => window.scrollTo(0, 1200));
await page.screenshot({ path: 'scrolled.png' });

await page.screenshot({ path: 'full-page.png', fullPage: true });
await page.pdf({ path: 'page.pdf', format: 'A4', printBackground: true });

A normal screenshot captures the live viewport and scroll position; fullPage: true captures document space. PDF output is raster-backed.

Screencasting

Playwright does not expose CDP screencasting as a page method. Attach a raw CDP session to the page, acknowledge every frame, and detach it when finished:

const client = await context.newCDPSession(page);

client.on('Page.screencastFrame', async ({ data, sessionId }) => {
  const jpeg = Buffer.from(data, 'base64');
  // Consume or forward `jpeg` here.
  await client.send('Page.screencastFrameAck', { sessionId });
});

await client.send('Page.startScreencast', {
  format: 'jpeg',
  quality: 80,
  maxWidth: 1280,
  maxHeight: 720,
});

// ...navigate, scroll, and interact...

await client.send('Page.stopScreencast');
await client.detach();

Frames are activity-driven page captures, not fixed-rate desktop video.

Disconnect

await browser.close();  // closes the CDP connection, leaves obscura serve running

Current limits

• Playwright page.video() and tracing artifacts that require desktop capture are not implemented. Use the raw CDP flow above for page frames.
• BrowserContext storage-state save/restore remains limited; use --storage-dir on obscura serve, as described in Persist cookies and storage.
• Service workers, native media, some Web APIs, long-tail CSS, and compositor behavior remain incomplete relative to Chromium.
• PDF text is not selectable/searchable and tagged PDF is not yet available.