@shim-works/playwright-embedded

Playwright-compatible automation for embedded browser applications — smart TVs, infotainment systems, kiosks, and other devices where standard Playwright can't reach.

Write tests exactly like normal Playwright. The library handles device communication, DOM synchronization, and assertions against real hardware.

Installation

npm install @shim-works/playwright-embedded

Usage

Three entry points — import only what your runtime needs:

// Inject into the device app (browser context)
import { load } from '@shim-works/playwright-embedded/client';

// Start the relay server (Node)
import { createServer } from '@shim-works/playwright-embedded/server';

// Connect to a device in your Playwright tests (Node)
import { connect, getConnectedDevices } from '@shim-works/playwright-embedded/playwright';

Quick start

// In your device app (browser side)
import { load } from '@shim-works/playwright-embedded/client';
load({ url: 'ws://relay-host:8080' });

// In your Playwright test
import { connect, Keys } from '@shim-works/playwright-embedded/playwright';

const { page, device } = await connect({
  testServerUrl: 'http://relay-host:8080',
  deviceName: 'my-tv',
});

await device.keyboard.press(Keys.ArrowDown);
await expect(page.getByRole('heading')).toHaveText('Now Playing');

await device.disconnect();

What It Does

• Input delivery — send key events to real devices from your test suite
• DOM assertions — query and assert against a live snapshot of the device's DOM using standard Playwright locators
• Auto-sync — the DOM mirror is refreshed after every keyboard.press() call; no manual sync step required
• Relay server — a thin bridge that pairs your test runner with one or more devices over a standard network connection

Capabilities & Limitations

Works well for

• Functional testing (navigation, focus, content)
• DOM structure and style validation across resolutions
• Testing on actual embedded hardware with no OS-level integration
• Remote debugging of device state

Doesn't cover

• Native platform interactions (voice remotes, HDMI-CEC)
• Network throttling or latency simulation
• Visual pixel-level regression (DOM-based only)

Requirements

• Device app must render via DOM (not canvas-only)
• Device must be reachable from the relay server over a standard network connection
• JavaScript execution must be available on the device (typically dev/QA builds)