PlaywrightPHP

Device Descriptors

The official Playwright device profiles, as PHP objects, for phone and tablet emulation.

The playwright-php/devices package ships the official device descriptors from Microsoft Playwright: viewport, user agent, scale factor, and touch capabilities for phones and tablets, exposed as PHP objects.

bash
composer require --dev playwright-php/devices

Look up a device

php
use Playwright\Device\DeviceRegistry;

$device = (new DeviceRegistry())->get('iPhone 15 Pro');

$device->getName();               // 'iPhone 15 Pro'
$device->getUserAgent();          // 'Mozilla/5.0 (iPhone; CPU ...'
$device->getViewport();           // ['width' => 393, 'height' => 659]
$device->getScreen();             // ['width' => 393, 'height' => 852]
$device->getDeviceScaleFactor();  // 3
$device->isMobile();              // true
$device->hasTouch();              // true
$device->getDefaultBrowserType(); // 'webkit'

Emulate it

Pass the descriptor's properties to a new browser context:

php
$browser->newContext([
    'userAgent' => $device->getUserAgent(),
    'viewport' => $device->getViewport(),
    'screen' => $device->getScreen(),
    'deviceScaleFactor' => $device->getDeviceScaleFactor(),
    'isMobile' => $device->isMobile(),
    'hasTouch' => $device->hasTouch(),
]);

Descriptors track the upstream Playwright source, so profiles stay aligned with what the JavaScript tooling emulates.

Recommended path

Use descriptors for product-level device targets. If your team says "we support iPhone-sized checkout", a named descriptor makes that target visible in the test. If the requirement is only "the layout must work below 400px", use a raw viewport in the core browser context instead.

Keep device setup near the scenario unless many tests share the same environment. A helper named mobileCustomerContext() is clearer than a generic options array that hides viewport, touch, user agent, and storage state.

Operational notes

Do not multiply the whole suite by every descriptor. Run the default desktop lane on every pull request, then add one mobile descriptor for high-value flows. Broader device coverage belongs in scheduled jobs or release gates.

Remember that descriptors configure the browser context. Server-rendered locale, timezone, and feature flags still come from your application environment unless you configure the server too.

Adoption checklist

Before adding device descriptors to the suite, decide:

  • which user flows actually have mobile risk;
  • which descriptor represents your supported product target;
  • whether the server also needs locale, timezone, or feature-flag changes;
  • whether screenshots should be compared across device scale factors;
  • whether the mobile lane runs on every pull request or only in broader checks.

This keeps device testing from becoming a multiplier on every browser test. The point is not to simulate every phone; it is to cover the environments that change product behavior.

What this integration is not

It is not a device farm. It will not prove virtual keyboard behavior, operating-system dialogs, camera input, network radio behavior, memory pressure, or browser UI chrome.

Use descriptors for web behavior. Use real devices when hardware and OS details are the risk.

Troubleshooting

  • Mobile layout does not appear: confirm the context was created with the descriptor before navigation.
  • Touch behavior differs from a phone: descriptors emulate web-facing signals, not hardware or OS chrome.
  • Screenshots differ across machines: pin viewport, scale factor, fonts, locale, and timezone.
  • Too many failures in the mobile lane: run only flows where mobile behavior matters.

FAQ

Can I combine a descriptor with storage state?

Yes. Merge the descriptor options with storageState when you need an authenticated mobile session.

Should I use the descriptor’s default browser type?

Use it when the test is device-faithful. Override it when your product matrix intentionally tests another engine.

See also