core(config): augment settings/passes with defaults

docs/configuration.md

@@ -207,8 +207,7 @@ The stock Lighthouse configurations can be extended if you only need to make sma
 
 The best examples are the ones Lighthouse uses itself! There are several reference configuration files that are maintained as part of Lighthouse.
 
-* [lighthouse-core/config/default.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default.js)
-* [lighthouse-core/config/perf.json](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/perf.json)
+* [lighthouse-core/config/default-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default-config.js)
 * [lighthouse-core/config/plots-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/plots-config.js)
 * [docs/recipes/custom-audit/custom-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/docs/recipes/custom-audit/custom-config.js)
 * [pwmetrics](https://github.com/paulirish/pwmetrics/blob/master/lib/lh-config.ts)

docs/readme.md

@@ -36,15 +36,15 @@ launchChromeAndRunLighthouse('https://example.com', opts).then(results => {
 ### Performance-only Lighthouse run
 
 Many modules consuming Lighthouse are only interested in the performance numbers.
-Lighthouse ships with a [performance-only config](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/perf.json) that you can use:
+You can limit the audits you run to a particular category or set of audits.
 
 ```js
-const perfConfig: any = require('lighthouse/lighthouse-core/config/perf.json');
+const perfConfig = require('lighthouse/lighthouse-core/config/perf-config.js');
 // ...
 launchChromeAndRunLighthouse(url, flags, perfConfig).then( // ...
 ```
 
-You can also craft your own config (e.g. [plots-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/plots-config.js)) for completely custom runs. Also see the [basic custom audit recipe](https://github.com/GoogleChrome/lighthouse/tree/master/docs/recipes/custom-audit).
+You can also craft your own config (e.g. [mixed-content-config.js](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/mixed-content-config.js)) for custom runs. Also see the [basic custom audit recipe](https://github.com/GoogleChrome/lighthouse/tree/master/docs/recipes/custom-audit).
 
 
 ### Turn on logging

docs/recipes/custom-audit/readme.md

@@ -19,7 +19,7 @@ in the report if the search box initializes within 4s.
 - [custom-config.js](custom-config.js) - this file tells Lighthouse where to
 find the gatherer and audit files, when to run them, and how to incorporate their
 output into the Lighthouse report. This example extends [Lighthouse's
-default configuration](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default.js).
+default configuration](https://github.com/GoogleChrome/lighthouse/blob/master/lighthouse-core/config/default-config.js).
 
 **Note**: when extending the default configuration file, passes with the same name are merged together, all other arrays will be concatenated, and primitive values will override the defaults.
 

docs/recipes/gulp/gulpfile.js

@@ -10,7 +10,6 @@ const gulp = require('gulp');
 const connect = require('gulp-connect');
 const lighthouse = require('lighthouse');
 const chromeLauncher = require('chrome-launcher');
-const perfConfig = require('lighthouse/lighthouse-core/config/perf.json');
 const PORT = 8080;
 
 /**
@@ -71,7 +70,8 @@ const flags = {}; // available options - https://github.com/GoogleChrome/lightho
 
 gulp.task('lighthouse', function() {
   startServer();
-  return launchChromeAndRunLighthouse(`http://localhost:${PORT}/index.html`, flags, perfConfig)
+  const config = {settings: {onlyCategories: ['performance']}};
+  return launchChromeAndRunLighthouse(`http://localhost:${PORT}/index.html`, flags, config)
     .then(handleOk)
     .catch(handleError);
 });

lighthouse-cli/bin.js

@@ -14,9 +14,8 @@ const getFlags = require('./cli-flags.js').getFlags;
 const runLighthouse = require('./run').runLighthouse;
 
 const log = require('lighthouse-logger');
-// @ts-ignore
-const perfOnlyConfig = require('../lighthouse-core/config/perf.json');
-const mixedContentConfig = require('../lighthouse-core/config/mixed-content.js');
+const perfOnlyConfig = require('../lighthouse-core/config/perf-config.js');
+const mixedContentConfig = require('../lighthouse-core/config/mixed-content-config.js');
 // @ts-ignore
 const pkg = require('../package.json');
 const Sentry = require('../lighthouse-core/lib/sentry');

lighthouse-cli/test/smokehouse/perf/run-tests.sh

@@ -4,7 +4,7 @@ node lighthouse-cli/test/fixtures/static-server.js &
 
 sleep 0.5s
 
-config="lighthouse-core/config/perf.json"
+config="lighthouse-core/config/perf-config.js"
 expectations="lighthouse-cli/test/smokehouse/perf/expectations.js"
 
 yarn smokehouse --config-path=$config --expectations-path=$expectations

lighthouse-cli/test/smokehouse/tricky-ttci/run-tests.sh

@@ -4,7 +4,7 @@ node lighthouse-cli/test/fixtures/static-server.js &
 
 sleep 0.5s
 
-config="lighthouse-core/config/default.js"
+config="lighthouse-core/config/default-config.js"
 expectations="lighthouse-cli/test/smokehouse/tricky-ttci/expectations.js"
 
 yarn smokehouse --config-path=$config --expectations-path=$expectations

lighthouse-core/audits/load-fast-enough-for-pwa.js

@@ -13,7 +13,7 @@
 
 const Audit = require('./audit');
 const URL = require('../lib/url-shim');
-const Emulation = require('../lib/emulation');
+const targetLatencyMs = require('../config/constants').throttling.mobile3G.rttMs;
 const Sentry = require('../lib/sentry');
 const Util = require('../report/v2/renderer/util.js');
 
@@ -80,7 +80,7 @@ class LoadFastEnough4Pwa extends Audit {
       });
 
       let firstRequestLatencies = Array.from(firstRequestLatenciesByOrigin.values());
-      const latency3gMin = Emulation.settings.MOBILE_3G_THROTTLING.targetLatencyMs - 10;
+      const latency3gMin = targetLatencyMs - 10;
       const areLatenciesAll3G = firstRequestLatencies.every(val => val.latency > latency3gMin);
       firstRequestLatencies = firstRequestLatencies.map(item => ({
         url: item.url,

lighthouse-core/config/config.js

@@ -6,10 +6,12 @@
 // @ts-nocheck
 'use strict';
 
-const defaultConfigPath = './default.js';
-const defaultConfig = require('./default.js');
+const defaultConfigPath = './default-config.js';
+const defaultConfig = require('./default-config.js');
 const fullConfig = require('./full-config.js');
+const constants = require('./constants');
 
+const isDeepEqual = require('lodash.isequal');
 const log = require('lighthouse-logger');
 const path = require('path');
 const Audit = require('../audits/audit');
@@ -118,18 +120,8 @@ function validatePasses(passes, audits) {
 
   // Passes must have unique `passName`s. Throw otherwise.
   const usedNames = new Set();
-  let defaultUsed = false;
-  passes.forEach((pass, index) => {
-    let passName = pass.passName;
-    if (!passName) {
-      if (defaultUsed) {
-        throw new Error(`passes[${index}] requires a passName`);
-      }
-
-      passName = Audit.DEFAULT_PASS;
-      defaultUsed = true;
-    }
-
+  passes.forEach(pass => {
+    const passName = pass.passName;
     if (usedNames.has(passName)) {
       throw new Error(`Passes must have unique names (repeated passName: ${passName}.`);
     }
@@ -259,7 +251,12 @@ function merge(base, extension) {
     return extension;
   } else if (Array.isArray(extension)) {
     if (!Array.isArray(base)) throw new TypeError(`Expected array but got ${typeof base}`);
-    return base.concat(extension);
+    const merged = base.slice();
+    extension.forEach(item => {
+      if (!merged.some(candidate => isDeepEqual(candidate, item))) merged.push(item);
+    });
+
+    return merged;
   } else if (typeof extension === 'object') {
     if (typeof base !== 'object') throw new TypeError(`Expected object but got ${typeof base}`);
     Object.keys(extension).forEach(key => {
@@ -272,7 +269,21 @@ function merge(base, extension) {
 }
 
 function deepClone(json) {
-  return JSON.parse(JSON.stringify(json));
+  const cloned = JSON.parse(JSON.stringify(json));
+
+  // Copy arrays that could contain plugins to allow for programmatic
+  // injection of plugins.
+  if (Array.isArray(json.passes)) {
+    cloned.passes.forEach((pass, i) => {
+      pass.gatherers = Array.from(json.passes[i].gatherers);
+    });
+  }
+
+  if (Array.isArray(json.audits)) {
+    cloned.audits = Array.from(json.audits);
+  }
+
+  return cloned;
 }
 
 class Config {
@@ -294,20 +305,8 @@ class Config {
     }
 
     // We don't want to mutate the original config object
-    const inputConfig = configJSON;
     configJSON = deepClone(configJSON);
 
-    // Copy arrays that could contain plugins to allow for programmatic
-    // injection of plugins.
-    if (Array.isArray(inputConfig.passes)) {
-      configJSON.passes.forEach((pass, i) => {
-        pass.gatherers = Array.from(inputConfig.passes[i].gatherers);
-      });
-    }
-    if (Array.isArray(inputConfig.audits)) {
-      configJSON.audits = Array.from(inputConfig.audits);
-    }
-
     // Extend the default or full config if specified
     if (configJSON.extends === 'lighthouse:full') {
       const explodedFullConfig = Config.extendConfigJSON(deepClone(defaultConfig),
@@ -317,7 +316,10 @@ class Config {
       configJSON = Config.extendConfigJSON(deepClone(defaultConfig), configJSON);
     }
 
-    // Expand audit/gatherer short-hand representations
+    // Augment config with necessary defaults
+    configJSON = Config.augmentWithDefaults(configJSON);
+
+    // Expand audit/gatherer short-hand representations and merge in defaults
     configJSON.audits = Config.expandAuditShorthandAndMergeOptions(configJSON.audits);
     configJSON.passes = Config.expandGathererShorthandAndMergeOptions(configJSON.passes);
 
@@ -358,8 +360,11 @@ class Config {
   static extendConfigJSON(baseJSON, extendJSON) {
     if (extendJSON.passes) {
       extendJSON.passes.forEach(pass => {
-        const basePass = baseJSON.passes.find(candidate => candidate.passName === pass.passName);
-        if (!basePass || !pass.passName) {
+        // use the default pass name if one is not specified
+        const passName = pass.passName || constants.defaultPassConfig.passName;
+        const basePass = baseJSON.passes.find(candidate => candidate.passName === passName);
+
+        if (!basePass) {
           baseJSON.passes.push(pass);
         } else {
           merge(basePass, pass);
@@ -372,6 +377,20 @@ class Config {
     return merge(baseJSON, extendJSON);
   }
 
+  /**
+   * @param {LH.Config} config
+   * @return {LH.Config}
+   */
+  static augmentWithDefaults(config) {
+    const {defaultSettings, defaultPassConfig} = constants;
+    config.settings = merge(deepClone(defaultSettings), config.settings);
+    if (config.passes) {
+      config.passes = config.passes.map(pass => merge(deepClone(defaultPassConfig), pass));
+    }
+
+    return config;
+  }
+
   /**
    * Expands the audits from user-specified to the internal audit definition format.
    *
@@ -418,6 +437,8 @@ class Config {
           return {path: gatherer, options: {}};
         } else if (typeof gatherer === 'function') {
           return {implementation: gatherer, options: {}};
+        } else if (gatherer && typeof gatherer.beforePass === 'function') {
+          return {instance: gatherer, options: {}};
         } else {
           return gatherer;
         }
@@ -464,12 +485,17 @@ class Config {
     config.passes = Config.expandGathererShorthandAndMergeOptions(config.passes);
     config.passes = Config.requireGatherers(config.passes);
 
-    // 1. Filter to just the chosen categories
-    config.categories = Config.filterCategoriesAndAudits(config.categories, categoryIds, auditIds,
-        skipAuditIds);
+    // 1. Filter to just the chosen categories/audits
+    const {categories, audits: requestedAuditNames} = Config.filterCategoriesAndAudits(
+      config.categories,
+      categoryIds,
+      auditIds,
+      skipAuditIds
+    );
+
+    config.categories = categories;
 
     // 2. Resolve which audits will need to run
-    const requestedAuditNames = Config.getAuditIdsInCategories(config.categories);
     const auditPathToNameMap = Config.getMapOfAuditPathToName(config);
     const getAuditName = auditDefn => auditDefn.implementation ?
       auditDefn.implementation.meta.name :
@@ -492,7 +518,7 @@ class Config {
    * @param {!Array<string>=} categoryIds
    * @param {!Array<string>=} auditIds
    * @param {!Array<string>=} skipAuditIds
-   * @return {!Object<string, {audits: !Array<{id: string}>}>}
+   * @return {{categories: Object<string, {audits: !Array<{id: string}>}>, audits: Set<string>}}
    */
   static filterCategoriesAndAudits(oldCategories, categoryIds, auditIds, skipAuditIds) {
     if (auditIds && skipAuditIds) {
@@ -532,6 +558,9 @@ class Config {
       }
     }
 
+    const includedAudits = new Set(auditIds);
+    skipAuditIds.forEach(id => includedAudits.delete(id));
+
     Object.keys(oldCategories).forEach(categoryId => {
       const category = deepClone(oldCategories[categoryId]);
 
@@ -554,25 +583,11 @@ class Config {
 
       if (category.audits.length) {
         categories[categoryId] = category;
+        category.audits.forEach(audit => includedAudits.add(audit.id));
       }
     });
 
-    return categories;
-  }
-
-  /**
-   * Finds the unique set of audit IDs used by the categories object.
-   * @param {!Object<string, {audits: !Array<{id: string}>}>} categories
-   * @return {!Set<string>}
-   */
-  static getAuditIdsInCategories(categories) {
-    /** @type {Array<string>} */
-    let audits = [];
-    for (const category of Object.values(categories)) {
-      audits = audits.concat(category.audits.map(audit => audit.id));
-    }
-
-    return new Set(audits);
+    return {categories, audits: includedAudits};
   }
 
   /**

lighthouse-core/config/constants.js

@@ -0,0 +1,50 @@
+/**
+ * @license Copyright 2018 Google Inc. All Rights Reserved.
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
+ * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+ */
+'use strict';
+
+/**
+ * Adjustments needed for DevTools network throttling to simulate
+ * more realistic network conditions.
+ * See: crbug.com/721112
+ */
+const DEVTOOLS_RTT_ADJUSTMENT_FACTOR = 3.75;
+const DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR = 0.9;
+
+const throttling = {
+  mobile3G: {
+    rttMs: 150,
+    throughputKbps: 1.6 * 1024,
+    requestLatencyMs: 150 * DEVTOOLS_RTT_ADJUSTMENT_FACTOR,
+    downloadThroughputKbps: 1.6 * 1024 * DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR,
+    uploadThroughputKbps: 750 * DEVTOOLS_THROUGHPUT_ADJUSTMENT_FACTOR,
+    cpuSlowdownMultiplier: 4,
+  },
+};
+
+const defaultSettings = {
+  maxWaitForLoad: 45 * 1000,
+  throttlingMethod: 'devtools',
+  throttling: throttling.mobile3G,
+};
+
+const defaultPassConfig = {
+  passName: 'defaultPass',
+  recordTrace: false,
+  useThrottling: false,
+  pauseAfterLoadMs: 0,
+  networkQuietThresholdMs: 0,
+  cpuQuietThresholdMs: 0,
+  blockedUrlPatterns: [],
+  blankPage: 'about:blank',
+  blankDuration: 300,
+  gatherers: [],
+};
+
+module.exports = {
+  throttling,
+  defaultSettings,
+  defaultPassConfig,
+};