core: add emulatedFormFactor setting

lighthouse-cli/cli-flags.js

@@ -57,7 +57,7 @@ function getFlags(manualArgv) {
       .group(
         [
           'save-assets', 'list-all-audits', 'list-trace-categories', 'additional-trace-categories',
-          'config-path', 'preset', 'chrome-flags', 'port', 'hostname',
+          'config-path', 'preset', 'chrome-flags', 'port', 'hostname', 'emulated-form-factor',
           'max-wait-for-load', 'enable-error-reporting', 'gather-mode', 'audit-mode',
           'only-audits', 'only-categories', 'skip-audits',
         ],
@@ -70,7 +70,8 @@ function getFlags(manualArgv) {
         'blocked-url-patterns': 'Block any network requests to the specified URL patterns',
         'disable-storage-reset':
             'Disable clearing the browser cache and other storage APIs before a run',
-        'disable-device-emulation': 'Disable Nexus 5X emulation',
+        'disable-device-emulation': 'Disable all device form factor emulation. Deprecated: use --emulated-form-factor=none instead',
+        'emulated-form-factor': 'Controls the emulated device form factor (mobile vs. desktop) if not disabled',
         'throttling-method': 'Controls throttling method',
         'throttling.rttMs': 'Controls simulated network RTT (TCP layer)',
         'throttling.throughputKbps': 'Controls simulated network download throughput',
@@ -120,6 +121,7 @@ function getFlags(manualArgv) {
         'list-trace-categories', 'view', 'verbose', 'quiet', 'help',
       ])
       .choices('output', printer.getValidOutputOptions())
+      .choices('emulated-form-factor', ['mobile', 'desktop', 'none'])
       .choices('throttling-method', ['devtools', 'provided', 'simulate'])
       .choices('preset', ['full', 'perf', 'mixed-content'])
       // force as an array
@@ -134,6 +136,7 @@ function getFlags(manualArgv) {
       // default values
       .default('chrome-flags', '')
       .default('output', ['html'])
+      .default('emulated-form-factor', 'mobile')
       .default('port', 0)
       .default('hostname', 'localhost')
       .default('enable-error-reporting', undefined) // Undefined so prompted by default

lighthouse-core/config/constants.js

@@ -36,6 +36,7 @@ const defaultSettings = {
   gatherMode: false,
   disableStorageReset: false,
   disableDeviceEmulation: false,
+  emulatedFormFactor: 'mobile',
 
   // the following settings have no defaults but we still want ensure that `key in settings`
   // in config will work in a typechecked way

lighthouse-core/config/lr-desktop-config.js

@@ -10,7 +10,7 @@ const config = {
   extends: 'lighthouse:default',
   settings: {
     maxWaitForLoad: 35 * 1000,
-    disableDeviceEmulation: true,
+    emulatedFormFactor: 'desktop',
     throttling: {
       // Using a "broadband" connection type
       // Corresponds to "Dense 4G 25th percentile" in https://docs.google.com/document/d/1Ft1Bnq9-t4jK5egLSOc28IL4TvR-Tt0se_1faTA4KTY/edit#heading=h.bb7nfy2x9e5v

lighthouse-core/gather/driver.js

@@ -991,8 +991,13 @@ class Driver {
    * @return {Promise<void>}
    */
   async beginEmulation(settings) {
+    // TODO(phulce): remove this flag on next breaking change
     if (!settings.disableDeviceEmulation) {
-      await emulation.enableNexus5X(this);
+      if (settings.emulatedFormFactor === 'mobile') {
+        await emulation.enableNexus5X(this);
+      } else if (settings.emulatedFormFactor === 'desktop') {
+        await emulation.enableDesktop(this);
+      }
     }
 
     await this.setThrottling(settings, {useThrottling: true});

lighthouse-core/lib/emulation.js

@@ -27,9 +27,25 @@ const NEXUS5X_EMULATION_METRICS = {
   },
 };
 
+/**
+ * Desktop metrics adapted from emulated_devices/module.json
+ * @type {LH.Crdp.Emulation.SetDeviceMetricsOverrideRequest}
+ */
+const DESKTOP_EMULATION_METRICS = {
+  mobile: false,
+  width: 1366,
+  height: 768,
+  deviceScaleFactor: 1,
+};
+
 const NEXUS5X_USERAGENT = {
   userAgent: 'Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5 Build/MRA58N) AppleWebKit/537.36' +
-    '(KHTML, like Gecko) Chrome/66.0.3359.30 Mobile Safari/537.36',
+    '(KHTML, like Gecko) Chrome/71.0.3559.0 Mobile Safari/537.36',
+};
+
+const DESKTOP_USERAGENT = {
+  userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 ' +
+    '(KHTML, like Gecko) Chrome/71.0.3559.0 Safari/537.36',
 };
 
 const OFFLINE_METRICS = {
@@ -65,6 +81,20 @@ async function enableNexus5X(driver) {
   ]);
 }
 
+/**
+ * @param {Driver} driver
+ * @return {Promise<void>}
+ */
+async function enableDesktop(driver) {
+  await Promise.all([
+    driver.sendCommand('Emulation.setDeviceMetricsOverride', DESKTOP_EMULATION_METRICS),
+    // Network.enable must be called for UA overriding to work
+    driver.sendCommand('Network.enable'),
+    driver.sendCommand('Network.setUserAgentOverride', DESKTOP_USERAGENT),
+    driver.sendCommand('Emulation.setTouchEmulationEnabled', {enabled: false}),
+  ]);
+}
+
 /**
  * @param {Driver} driver
  * @param {Required<LH.ThrottlingSettings>} throttlingSettings
@@ -121,6 +151,7 @@ function disableCPUThrottling(driver) {
 
 module.exports = {
   enableNexus5X,
+  enableDesktop,
   enableNetworkThrottling,
   clearAllNetworkEmulation,
   enableCPUThrottling,

lighthouse-core/lib/sentry.js

@@ -93,6 +93,7 @@ function init(opts) {
     const context = Object.assign({
       url: opts.url,
       deviceEmulation: !opts.flags.disableDeviceEmulation,
+      emulatedFormFactor: opts.flags.emulatedFormFactor,
       throttlingMethod: opts.flags.throttlingMethod,
     }, opts.flags.throttling);
     Sentry.mergeContext({extra: Object.assign({}, opts.environmentData.extra, context)});

lighthouse-core/report/html/renderer/util.js

@@ -415,7 +415,12 @@ class Util {
         summary = 'Unknown';
     }
 
-    const deviceEmulation = settings.disableDeviceEmulation ? 'No emulation' : 'Emulated Nexus 5X';
+    let deviceEmulation = 'No emulation';
+    if (!settings.disableDeviceEmulation) {
+      if (settings.emulatedFormFactor === 'mobile') deviceEmulation = 'Emulated Nexus 5X';
+      if (settings.emulatedFormFactor === 'desktop') deviceEmulation = 'Emulated Desktop';
+    }
+
     return {
       deviceEmulation,
       cpuThrottling,

lighthouse-core/test/gather/gather-runner-test.js

@@ -176,7 +176,7 @@ describe('GatherRunner', function() {
     );
 
     return GatherRunner.setupDriver(driver, {
-      settings: {},
+      settings: {emulatedFormFactor: 'mobile'},
     }).then(_ => {
       assert.ok(tests.calledDeviceEmulation, 'did not call device emulation');
       assert.deepEqual(tests.calledNetworkEmulation, {
@@ -215,6 +215,25 @@ describe('GatherRunner', function() {
     });
   });
 
+  it('uses correct emulation form factor', async () => {
+    let emulationParams;
+    const driver = getMockedEmulationDriver(
+      params => emulationParams = params,
+      () => true,
+      () => true
+    );
+
+    await GatherRunner.setupDriver(driver, {settings: {emulatedFormFactor: 'mobile'}});
+    expect(emulationParams).toMatchObject({mobile: true});
+
+    await GatherRunner.setupDriver(driver, {settings: {emulatedFormFactor: 'desktop'}});
+    expect(emulationParams).toMatchObject({mobile: false});
+
+    emulationParams = undefined;
+    await GatherRunner.setupDriver(driver, {settings: {emulatedFormFactor: 'none'}});
+    expect(emulationParams).toBe(undefined);
+  });
+
   it('stops throttling when not devtools', () => {
     const tests = {
       calledDeviceEmulation: false,
@@ -233,6 +252,7 @@ describe('GatherRunner', function() {
 
     return GatherRunner.setupDriver(driver, {
       settings: {
+        emulatedFormFactor: 'mobile',
         throttlingMethod: 'provided',
       },
     }).then(_ => {
@@ -262,6 +282,7 @@ describe('GatherRunner', function() {
 
     return GatherRunner.setupDriver(driver, {
       settings: {
+        emulatedFormFactor: 'mobile',
         throttlingMethod: 'devtools',
         throttling: {
           requestLatencyMs: 100,

lighthouse-core/test/report/html/renderer/util-test.js

@@ -94,7 +94,10 @@ describe('util helpers', () => {
   it('builds device emulation string', () => {
     const get = opts => Util.getEmulationDescriptions(opts).deviceEmulation;
     assert.equal(get({disableDeviceEmulation: true}), 'No emulation');
-    assert.equal(get({disableDeviceEmulation: false}), 'Emulated Nexus 5X');
+    assert.equal(get({disableDeviceEmulation: false}), 'No emulation');
+    assert.equal(get({emulatedFormFactor: 'none'}), 'No emulation');
+    assert.equal(get({emulatedFormFactor: 'mobile'}), 'Emulated Nexus 5X');
+    assert.equal(get({emulatedFormFactor: 'desktop'}), 'Emulated Desktop');
   });
 
   it('builds throttling strings when provided', () => {

lighthouse-core/test/results/sample_v2.json

@@ -2779,6 +2779,7 @@
     "gatherMode": false,
     "disableStorageReset": false,
     "disableDeviceEmulation": false,
+    "emulatedFormFactor": "mobile",
     "locale": "en-US",
     "blockedUrlPatterns": null,
     "additionalTraceCategories": null,

readme.md

@@ -63,6 +63,7 @@ Configuration:
   --hostname                     The hostname to use for the debugging protocol.                                              [default: "localhost"]
   --max-wait-for-load            The timeout (in milliseconds) to wait before the page is considered done loading and the run should continue.
                                  WARNING: Very high values can lead to large traces and instability                                 [default: 45000]
+  --emulated-form-factor         Controls the emulated device form factor (mobile vs. desktop) if not disabled                      [choices: "mobile", "desktop", "none"] [default: "mobile"]
   --enable-error-reporting       Enables error reporting, overriding any saved preference. --no-enable-error-reporting will do the opposite. More:
                                  https://git.io/vFFTO
   --gather-mode, -G              Collect artifacts from a connected browser and save to disk. If audit-mode is not also enabled, the run will quit
@@ -83,7 +84,7 @@ Options:
   --version                     Show version number                                                                                        [boolean]
   --blocked-url-patterns        Block any network requests to the specified URL patterns                                                     [array]
   --disable-storage-reset       Disable clearing the browser cache and other storage APIs before a run                                     [boolean]
-  --disable-device-emulation    Disable Nexus 5X emulation                                                                                 [boolean]
+  --disable-device-emulation    Disable all device form factor emulation. Deprecated: use --emulated-form-factor=none instead              [boolean]
   --throttling-method                  Controls throttling method         [choices: "devtools", "provided", "simulate"]
   --throttling.rttMs                   Controls simulated network RTT (TCP layer)
   --throttling.throughputKbps          Controls simulated network download throughput

typings/externs.d.ts

@@ -83,6 +83,7 @@ declare global {
       gatherMode?: boolean | string;
       disableStorageReset?: boolean;
       disableDeviceEmulation?: boolean;
+      emulatedFormFactor?: 'mobile'|'desktop'|'none';
       throttlingMethod?: 'devtools'|'simulate'|'provided';
       throttling?: ThrottlingSettings;
       onlyAudits?: string[] | null;