Device emulation

Lighthouse emulates a mobile device by default. Learn how to configure screen emulation, user agent spoofing, and form factor for desktop or real-device testing.

Lighthouse emulates a mobile device by default, applying screen dimensions, device scale factor, and a mobile user agent string. This simulates how a typical mobile user experiences your page, independent of the device running Lighthouse.

“Emulation” in Lighthouse refers specifically to screen and user agent emulation. Network and CPU throttling are covered separately in Throttling.

Mobile vs desktop

By default, Lighthouse runs in mobile mode. To run with desktop settings and scoring calibration, use the --preset=desktop flag.

# Run with desktop emulation and scoring
lighthouse --preset=desktop https://example.com

--preset=desktop is the recommended way to test desktop performance. It replaces the older --emulated-form-factor=desktop flag, which was removed in Lighthouse v7.

The --form-factor flag

The formFactor setting does not control emulation directly. Instead, it tells Lighthouse how to interpret the run — specifically for scoring performance metrics and skipping mobile-only tests when running in desktop mode.

You must always set formFactor when configuring emulation externally. The allowed values are mobile (default) and desktop.

lighthouse --form-factor=desktop https://example.com

Screen emulation

The screenEmulation setting controls the viewport applied to the page. It accepts an object with the following fields:

Field	Type	Description
width	number	Viewport width in pixels.
height	number	Viewport height in pixels.
deviceScaleFactor	number	Device pixel ratio.
mobile	boolean	Enables overlay scrollbars and other mobile-specific rendering behaviors.
disabled	boolean	When true, Lighthouse skips applying screen emulation entirely.

To disable screen emulation — for example, when running against a real device or when emulation is applied externally by Puppeteer:

lighthouse --screenEmulation.disabled https://example.com

User agent emulation

By default, Lighthouse spoofs a mobile user agent string to ensure pages return their mobile variants. The emulatedUserAgent setting controls this behavior.

Value	Behavior
true (default)	Apply the default Lighthouse user agent string.
false	Disable user agent spoofing.
A string	Apply the provided user agent string.

Disabling user agent spoofing is safe to do redundantly — if the real device is already sending the correct user agent, setting emulatedUserAgent: false has no negative effect.

Testing on a real mobile device

When running Lighthouse against Chrome on an actual mobile device, you should disable Lighthouse’s own screen emulation and CPU throttling, since the device provides real conditions.

lighthouse \
  --screenEmulation.disabled \
  --throttling.cpuSlowdownMultiplier=1 \
  https://example.com

--form-factor=mobile is the default and does not need to be set explicitly in this case.

Changes in v7

Lighthouse v7 overhauled the emulation configuration to be more explicit and consistent. Key changes:

Status	Property
Removed	emulatedFormFactor — replaced by formFactor
Removed	TestedAsMobileDevice artifact — replaced by explicit formFactor
Removed	internalDisableDeviceScreenEmulation — replaced by screenEmulation.disabled
Added	formFactor
Added	screenEmulation
Added	emulatedUserAgent

The throttling and throttlingMethod settings were not changed in v7.