Add custom audit recipe (#2255)

* add custom audit recipe

* feedback

docs/recipes/custom-audit/custom-config.js

@@ -0,0 +1,46 @@
+/**
+ * Copyright 2017 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';
+
+module.exports = {
+  // 1. Run your custom tests along with all the default Lighthouse tests.
+  extends: 'lighthouse:default',
+
+  // 2. Add gatherer to the default Lighthouse load ('pass') of the page.
+  passes: [{
+    passName: 'defaultPass',
+    gatherers: [
+      'searchable-gatherer'
+    ],
+  }],
+
+  // 3. Add custom audit to the list of audits 'lighthouse:default' will run.
+  audits: [
+    'searchable-audit'
+  ],
+
+  // 4. Create a new 'My site metrics' section in the default report for our results.
+  categories: {
+    mysite: {
+      name: 'My site metrics',
+      description: 'Metrics for our super awesome site',
+      audits: [
+        // When we add more custom audits, `weight` controls how they're averaged together.
+        {id: 'searchable-audit', weight: 1}
+      ]
+    }
+  }
+};

docs/recipes/custom-audit/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "custom-lighthouse-recipe",
+  "private": true,
+  "scripts": {},
+  "devDependencies": {
+    "lighthouse": "^2.x"
+  }
+}

docs/recipes/custom-audit/readme.md

@@ -0,0 +1,11 @@
+# Basic custom audit recipe for Lighthouse
+
+A hypothetical site measures the time from navigation start to when the page has initialized and the main search box is ready to be used. It saves that value in a global variable, `window.myLoadMetrics.searchableTime`.
+
+This Lighthouse [gatherer](searchable-gatherer.js)/[audit](searchable-audit.js) pair will take that value from the context of the page and test whether or not it stays below a test threshold.
+
+The config 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.
+
+## Run
+With site running:
+`lighthouse --config-path=custom-config.js https://test-site.url`

docs/recipes/custom-audit/searchable-audit.js

@@ -0,0 +1,55 @@
+/**
+ * Copyright 2017 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';
+
+const Audit = require('lighthouse').Audit;
+
+const MAX_SEARCHABLE_TIME = 4000;
+
+/**
+ * @fileoverview Tests that `window.myLoadMetrics.searchableTime` was below the
+ * test threshold value.
+ */
+
+class LoadAudit extends Audit {
+  static get meta() {
+    return {
+      category: 'MyCustomCategory',
+      name: 'searchable-audit',
+      description: 'Search box initialized and ready',
+      helpText: 'Used to measure time from navigationStart to when the search' +
+          ' box is initialized and ready to search.',
+
+      // The name of the custom gatherer class that provides input to this audit.
+      requiredArtifacts: ['TimeToSearchable']
+    };
+  }
+
+  static audit(artifacts) {
+    const loadMetrics = artifacts.TimeToSearchable;
+
+    // Audit will pass when the search box loaded in less time than our threshold.
+    // This score will be binary, so will get a red ✘ or green ✓ in the report.
+    const belowThreshold = loadMetrics.searchableTime <= MAX_SEARCHABLE_TIME;
+
+    return {
+      rawValue: loadMetrics.searchableTime,
+      score: belowThreshold
+    };
+  }
+}
+
+module.exports = LoadAudit;

docs/recipes/custom-audit/searchable-gatherer.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright 2017 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';
+
+const Gatherer = require('lighthouse').Gatherer;
+
+/**
+ * @fileoverview Extracts `window.myLoadMetrics` from the test page.
+ */
+
+class TimeToSearchable extends Gatherer {
+  afterPass(options) {
+    const driver = options.driver;
+
+    return driver.evaluateAsync('window.myLoadMetrics')
+      // Ensure returned value is what we expect.
+      .then(loadMetrics => {
+        if (!loadMetrics || loadMetrics.searchableTime === undefined) {
+          // Throw if page didn't provide the metrics we expect. This isn't
+          // fatal -- the Lighthouse run will continue, but any audits that
+          // depend on this gatherer will show this error string in the report.
+          throw new Error('Unable to find load metrics in page');
+        }
+        return loadMetrics;
+      });
+  }
+}
+
+module.exports = TimeToSearchable;