Improve Playwright Test and CDP Compatibility

[ricardo-costa0405]

First-Class Playwright Test Compatibility over CDP

Description

Lightpanda should provide first-class compatibility with Playwright Test over CDP, without requiring custom browser, context, or page fixtures or reducing test isolation.

Playwright Test normally uses the Playwright protocol, while Lightpanda exposes CDP. Although chromium.connectOverCDP() provides a connection path, standard Playwright Test suites currently require additional integration work and may encounter unsupported commands, incomplete isolation, timeouts, or silently degraded behavior.

Goal

Standard Playwright Test suites should run against Lightpanda with minimal configuration changes:

npx playwright test --project=lightpanda

Unsupported features should fail immediately with clear errors instead of timing out or silently degrading.

Compatibility Areas

Playwright Test connection

Provide an official integration path based on:

chromium.connectOverCDP(endpointURL)

The integration should expose the standard Playwright Test fixtures:

test('example', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page.getByRole('heading')).toBeVisible();
});

Users should not need to create custom browser, context, or page fixtures.

Browser contexts and parallelism

Support isolated browser.newContext() flows so Playwright workers can run safely in parallel.

Expected behavior includes:

• isolated cookies and storage;
• isolated permissions and HTTP credentials;
• isolated network routes and headers;
• storage-state import and export;
• independent downloads;
• reliable context cleanup;
• no state leakage between workers.

The following configuration should run safely:

export default defineConfig({
  fullyParallel: true,
  workers: 4,
});

Emulation defaults

Support or explicitly no-op commonly used CDP commands, including:

• Emulation.setLocaleOverride
• Emulation.setTimezoneOverride
• Emulation.setDeviceMetricsOverride
• Emulation.setTouchEmulationEnabled
• Emulation.setEmulatedMedia
• Emulation.setUserAgentOverride
• Emulation.setGeolocationOverride
• Browser.setDownloadBehavior

Unsupported commands should return a clear CDP error and must not remain unresolved.

Form controls

Ensure native form controls are compatible with Playwright locators.

In particular, locator.selectOption() should support selection by:

await locator.selectOption('value');
await locator.selectOption({ value: 'value' });
await locator.selectOption({ label: 'Visible label' });
await locator.selectOption({ index: 1 });

Expected behavior:

• update the selected value;
• update the relevant <option> state;
• support single and multiple selection;
• dispatch input and change events;
• return the selected values;
• handle disabled or missing options consistently.

Device descriptors

Document a safe path for using Playwright device presets without requiring Chrome or Firefox user-agent impersonation where that conflicts with Lightpanda policy.

Clearly identify which device properties are:

• supported;
• partially supported;
• ignored;
• rejected.

Artifacts and debugging

Support or document the behavior of:

• traces;
• screenshots;
• videos;
• console logs;
• page errors;
• network logs;
• downloads;
• failure attachments.

Features that depend on graphical rendering may remain unsupported, but Playwright should receive an explicit error rather than an empty or invalid artifact.

Compatibility contract

Publish and maintain a Playwright compatibility matrix covering:

Area	Expected coverage
Connection and lifecycle	CDP connection, disconnect and cleanup
Navigation	redirects, reloads, history and wait states
Locators	role, text, label, CSS and test ID
Actions	click, fill, press, check and select
Frames	iframe navigation and frameLocator
Forms	inputs, selects, checkboxes and uploads
Storage	cookies, local storage and storage state
Dialogs	alert, confirm, prompt and beforeunload
Networking	interception, headers and responses
Contexts	multiple isolated contexts
Parallelism	multiple Playwright workers
Downloads	events, paths and cleanup
Tracing	supported, partial or unsupported
Screenshots	supported, partial or unsupported
Videos	supported, partial or unsupported
Mobile emulation	viewport, touch, locale and timezone

Compatibility should be tested against the latest stable Playwright release and at least one previous minor release.

Acceptance Criteria

• A standard Playwright Test can use the built-in page, context, and browser fixtures.
• Multiple browser.newContext() instances remain isolated.
• Tests run with multiple workers without cross-test state leakage.
• Common Playwright emulation commands either work or fail clearly.
• locator.selectOption() works by value, label, and index.
• Unsupported features fail immediately with actionable errors.
• A maintained Playwright compatibility matrix is published.
• A compatibility test suite runs in CI against supported Playwright versions.

Example Target Configuration

import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'lightpanda',
      use: {
        // Official Lightpanda CDP integration or adapter.
      },
    },
  ],
});

The final goal is to allow existing Playwright Test suites to run against Lightpanda with minimal configuration changes while preserving predictable isolation, execution, and failure behavior.