feat: Add initial support for Lighthouse settings (#474)

Add a new settings property, which enables testing as Desktop and setting a custom locale when generating reports

Author: jackbrewer

.env.example

@@ -3,4 +3,6 @@ AUDITS=[{"url":"https://www.example.com","thresholds":{"performance":0.5}},{"pat
 # Ignored when a url is configured for an audit
 PUBLISH_DIR=FULL_PATH_TO_LOCAL_BUILD_DIRECTORY
 # JSON string of thresholds to enforce
-THRESHOLDS={"performance":0.9,"accessibility":0.9,"best-practices":0.9,"seo":0.9,"pwa":0.9}
+THRESHOLDS={"performance":0.9,"accessibility":0.9,"best-practices":0.9,"seo":0.9,"pwa":0.9}
+# SETTINGS
+SETTINGS={"locale":"en", "preset":"desktop"}

.gitignore

@@ -7,3 +7,4 @@ yarn-error.log
 reports
 cypress/videos
 cypress/screenshots
+coverage

README.md

@@ -8,7 +8,7 @@ If you would like to run the Lighthouse build plugin for multiple site paths, su
 
 ### Install plugin through the Netlify UI
 
-You can install this plugin in the Netlify UI from this [direct in-app installation link](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install) or from the [Plugins directory](https://app.netlify.com/plugins). 
+You can install this plugin in the Netlify UI from this [direct in-app installation link](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install) or from the [Plugins directory](https://app.netlify.com/plugins).
 
 ### Install plugin through the `netlify.toml` file
 
@@ -71,22 +71,22 @@ Example `netlify.toml` file that audits the site root path and a contact page:
 ```
 [[plugins]]
   package = "@netlify/plugin-lighthouse"
-  
+
   # Generate a Lighthouse report for the site's root path
   [[plugins.inputs.audits]]
   path = ""
-        
+
   # Generate a Lighthouse report for the contact site path
   [[plugins.inputs.audits]]
   path = "contact"
 
 ```
 
-
 The lighthouse report results are automatically printed to the **Deploy log** in the Netlify UI. For example:
+
 ```
 2:35:07 PM: ────────────────────────────────────────────────────────────────
-2:35:07 PM:   2. onPostBuild command from @netlify/plugin-lighthouse        
+2:35:07 PM:   2. onPostBuild command from @netlify/plugin-lighthouse
 2:35:07 PM: ────────────────────────────────────────────────────────────────
 2:35:07 PM: ​
 2:35:07 PM: Serving and scanning site from directory dist
@@ -104,6 +104,17 @@ The lighthouse report results are automatically printed to the **Deploy log** in
 2:35:17 PM: }
 ```
 
+We currently support the following settings, which are passed directly to Lighthouse:
+
+```
+[[plugins]]
+  package = "@netlify/plugin-lighthouse"
+
+  [plugins.inputs.settings]
+    preset = "desktop" # Optionally run Lighthouse using a desktop configuration
+    locale = "es" # Any Lighthouse-supported locale, used to generate reports in a different language
+```
+
 ## Running Locally
 
 Fork and clone this repo.
@@ -126,6 +137,7 @@ If you have multiple audits (directories, paths, etc) defined in your build, we
 <img width="1400" alt="Deploy details with multiple audit Lighthouse results" src="https://user-images.githubusercontent.com/79875905/160019057-d29dffab-49f3-4fbf-a1ac-1f314e0cd837.png">
 
 Some items of note:
+
 - The [Lighthouse Build Plugin](https://app.netlify.com/plugins/@netlify/plugin-lighthouse/install) must be installed on your site(s) in order for these score visualizations to be displayed.
 - This Labs feature is currently only enabled at the user-level, so it will need to be enabled for each individual team member that wishes to see the Lighthouse scores displayed.
 

manifest.yml

@@ -16,3 +16,7 @@ inputs:
   - name: audits
     required: false
     description: A list of audits to perform. Each list item is an object with either a url/path to scan and an optional thresholds mapping.
+
+  - name: settings
+    required: false
+    description: Lighthouse-specific settings, used to modify reporting criteria

src/index.js

@@ -6,6 +6,7 @@ const chalk = require('chalk');
 const fs = require('fs').promises;
 const minify = require('html-minifier').minify;
 const { getConfiguration } = require('./config');
+const { getSettings } = require('./settings');
 const { getBrowserPath, runLighthouse } = require('./lighthouse');
 const { makeReplacements } = require('./replacements');
 
@@ -136,14 +137,18 @@ const getUtils = ({ utils }) => {
   return { failBuild, show };
 };
 
-const runAudit = async ({ path, url, thresholds, output_path }) => {
+const runAudit = async ({ path, url, thresholds, output_path, settings }) => {
   try {
     const { server } = getServer({ serveDir: path, auditUrl: url });
     const browserPath = await getBrowserPath();
     const { error, results } = await new Promise((resolve) => {
       const instance = server.listen(async () => {
         try {
-          const results = await runLighthouse(browserPath, server.url);
+          const results = await runLighthouse(
+            browserPath,
+            server.url,
+            settings,
+          );
           resolve({ error: false, results });
         } catch (error) {
           resolve({ error });
@@ -261,6 +266,8 @@ module.exports = {
         inputs,
       });
 
+      const settings = getSettings(inputs?.settings);
+
       const allErrors = [];
       const data = [];
       for (const { path, url, thresholds, output_path } of audits) {
@@ -269,6 +276,7 @@ module.exports = {
           url,
           thresholds,
           output_path,
+          settings,
         });
         if (summary) {
           console.log({ results: summary });

src/lighthouse.js

@@ -30,7 +30,7 @@ const getBrowserPath = async () => {
   return info.executablePath;
 };
 
-const runLighthouse = async (browserPath, url) => {
+const runLighthouse = async (browserPath, url, settings) => {
   let chrome;
   try {
     const logLevel = 'info';
@@ -45,11 +45,15 @@ const runLighthouse = async (browserPath, url) => {
       ],
       logLevel,
     });
-    const results = await lighthouse(url, {
-      port: chrome.port,
-      output: 'html',
-      logLevel,
-    });
+    const results = await lighthouse(
+      url,
+      {
+        port: chrome.port,
+        output: 'html',
+        logLevel,
+      },
+      settings,
+    );
     if (results.lhr.runtimeError) {
       throw new Error(results.lhr.runtimeError.message);
     }

src/settings.js

@@ -0,0 +1,43 @@
+const desktopConfig = require('lighthouse/lighthouse-core/config/desktop-config');
+const fullConfig = require('lighthouse/lighthouse-core/config/full-config');
+
+/*
+ * Check for settings added in `.env` file and merge with input settings
+ * specified in `netlify.toml`
+ */
+const mergeSettingsSources = (inputSettings = {}) => {
+  let envSettings = {};
+  if (typeof process.env.SETTINGS === 'string') {
+    try {
+      envSettings = JSON.parse(process.env.SETTINGS);
+    } catch (e) {
+      throw new Error(`Invalid JSON for 'settings' input: ${e.message}`);
+    }
+  }
+
+  // Shallow merge of input and env settings, with input taking priority.
+  // Review the need for a deep merge if/when more complex settings are added.
+  return Object.assign({}, envSettings, inputSettings);
+};
+
+const getSettings = (inputSettings) => {
+  const settings = mergeSettingsSources(inputSettings);
+  if (Object.keys(settings).length === 0) return;
+
+  // Set a base-level config based on the preset input value
+  // (desktop is currently the only supported option)
+  const derivedSettings =
+    settings.preset === 'desktop' ? desktopConfig : fullConfig;
+
+  // The following are added to the `settings` object of the selected base config
+  // We add individually to avoid passing anything unexpected to Lighthouse.
+  if (settings.locale) {
+    derivedSettings.settings.locale = settings.locale;
+  }
+
+  return derivedSettings;
+};
+
+module.exports = {
+  getSettings,
+};

src/settings.test.js

@@ -0,0 +1,41 @@
+const { getSettings } = require('./settings');
+
+describe('replacements', () => {
+  it('should return nothing with no settings set', () => {
+    expect(getSettings()).toEqual(undefined);
+  });
+
+  it('should return a template config with preset set to desktop', () => {
+    const derivedSettings = getSettings({ preset: 'desktop' });
+    expect(derivedSettings.extends).toEqual('lighthouse:default');
+    expect(derivedSettings.settings.formFactor).toEqual('desktop');
+  });
+
+  it('should add a locale if set', () => {
+    const derivedSettings = getSettings({ locale: 'es' });
+    expect(derivedSettings.settings.locale).toEqual('es');
+  });
+
+  it('should use values from process.env.SETTINGS', () => {
+    process.env.SETTINGS = JSON.stringify({
+      preset: 'desktop',
+      locale: 'ar',
+    });
+    const derivedSettings = getSettings();
+    expect(derivedSettings.settings.formFactor).toEqual('desktop');
+    expect(derivedSettings.settings.locale).toEqual('ar');
+  });
+
+  it('should prefer values from input over process.env.SETTINGS', () => {
+    process.env.SETTINGS = JSON.stringify({
+      locale: 'ar',
+    });
+    const derivedSettings = getSettings({ locale: 'es' });
+    expect(derivedSettings.settings.locale).toEqual('es');
+  });
+
+  it('should error with incorrect syntax for process.env.SETTINGS', () => {
+    process.env.SETTINGS = 'not json';
+    expect(getSettings).toThrow(/Invalid JSON/);
+  });
+});