lighthouse 9.5.0-dev.20221113 → 9.5.0-dev.20221115

package/core/index.js

@@ -10,9 +10,13 @@ import {Runner} from './runner.js';
 import {CriConnection} from './legacy/gather/connections/cri.js';
 import {Config} from './legacy/config/config.js';
 import UrlUtils from './lib/url-utils.js';
-import * as fraggleRock from './api.js';
 import {Driver} from './legacy/gather/driver.js';
 import {initializeConfig} from './config/config.js';
+import {UserFlow, auditGatherSteps} from './user-flow.js';
+import {ReportGenerator} from '../report/generator/report-generator.js';
+import {startTimespanGather} from './gather/timespan-runner.js';
+import {snapshotGather} from './gather/snapshot-runner.js';
+import {navigationGather} from './gather/navigation-runner.js';
 
 /** @typedef {import('./legacy/gather/connections/connection.js').Connection} Connection */
 
@@ -40,7 +44,7 @@ import {initializeConfig} from './config/config.js';
  * @return {Promise<LH.RunnerResult|undefined>}
  */
 async function lighthouse(url, flags = {}, configJSON, page) {
-  return fraggleRock.navigation(page, url, {config: configJSON, flags});
+  return navigation(page, url, {config: configJSON, flags});
 }
 
 /**
@@ -73,6 +77,75 @@ async function legacyNavigation(url, flags = {}, configJSON, userConnection) {
   return Runner.audit(artifacts, options);
 }
 
+/**
+ * @param {LH.Puppeteer.Page} page
+ * @param {LH.UserFlow.Options} [options]
+ */
+async function startFlow(page, options) {
+  return new UserFlow(page, options);
+}
+
+/**
+ * @param {LH.Puppeteer.Page|undefined} page
+ * @param {LH.NavigationRequestor|undefined} requestor
+ * @param {{config?: LH.Config.Json, flags?: LH.Flags}} [options]
+ * @return {Promise<LH.RunnerResult|undefined>}
+ */
+async function navigation(page, requestor, options) {
+  const gatherResult = await navigationGather(page, requestor, options);
+  return Runner.audit(gatherResult.artifacts, gatherResult.runnerOptions);
+}
+
+/**
+ * @param {LH.Puppeteer.Page} page
+ * @param {{config?: LH.Config.Json, flags?: LH.Flags}} [options]
+ * @return {Promise<LH.RunnerResult|undefined>}
+ */
+async function snapshot(page, options) {
+  const gatherResult = await snapshotGather(page, options);
+  return Runner.audit(gatherResult.artifacts, gatherResult.runnerOptions);
+}
+
+/**
+ * @param {LH.Puppeteer.Page} page
+ * @param {{config?: LH.Config.Json, flags?: LH.Flags}} [options]
+ * @return {Promise<{endTimespan: () => Promise<LH.RunnerResult|undefined>}>}
+ */
+async function startTimespan(page, options) {
+  const {endTimespanGather} = await startTimespanGather(page, options);
+  const endTimespan = async () => {
+    const gatherResult = await endTimespanGather();
+    return Runner.audit(gatherResult.artifacts, gatherResult.runnerOptions);
+  };
+  return {endTimespan};
+}
+
+/**
+ * @template {LH.Result|LH.FlowResult} R
+ * @param {R} result
+ * @param {[R] extends [LH.Result] ? LH.OutputMode : Exclude<LH.OutputMode, 'csv'>} [format]
+ * @return {string}
+ */
+function generateReport(result, format = 'html') {
+  const reportOutput = ReportGenerator.generateReport(result, format);
+  if (Array.isArray(reportOutput)) {
+    // In theory the output should never be an array.
+    // This is mostly for type checking.
+    return reportOutput[0];
+  } else {
+    return reportOutput;
+  }
+}
+
+/**
+ * @param {LH.UserFlow.FlowArtifacts} flowArtifacts
+ * @param {LH.Config.Json} [config]
+ */
+async function auditFlowArtifacts(flowArtifacts, config) {
+  const {gatherSteps, name} = flowArtifacts;
+  return await auditGatherSteps(gatherSteps, {name, config});
+}
+
 /**
  * Generate a Lighthouse Config.
  * @param {LH.Config.Json=} configJson Configuration for the Lighthouse run. If
@@ -113,6 +186,12 @@ export {default as Gatherer} from './gather/base-gatherer.js';
 export {NetworkRecords} from './computed/network-records.js';
 export {
   legacyNavigation,
+  startFlow,
+  navigation,
+  startTimespan,
+  snapshot,
+  generateReport,
+  auditFlowArtifacts,
   generateConfig,
   generateLegacyConfig,
   getAuditList,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "lighthouse",
   "type": "module",
-  "version": "9.5.0-dev.20221113",
+  "version": "9.5.0-dev.20221115",
   "description": "Automated auditing, performance metrics, and best practices for the web.",
   "main": "./core/index.js",
   "bin": {

package/report/generator/report-generator.js

@@ -146,28 +146,42 @@ class ReportGenerator {
       .join(CRLF);
   }
 
+  /**
+   * @param {LHResult|FlowResult} result
+   * @return {result is FlowResult}
+   */
+  static isFlowResult(result) {
+    return 'steps' in result;
+  }
+
   /**
    * Creates the results output in a format based on the `mode`.
-   * @param {LHResult} lhr
+   * @param {LHResult|FlowResult} result
    * @param {LHResult['configSettings']['output']} outputModes
    * @return {string|string[]}
    */
-  static generateReport(lhr, outputModes) {
+  static generateReport(result, outputModes) {
     const outputAsArray = Array.isArray(outputModes);
     if (typeof outputModes === 'string') outputModes = [outputModes];
 
     const output = outputModes.map(outputMode => {
       // HTML report.
       if (outputMode === 'html') {
-        return ReportGenerator.generateReportHtml(lhr);
+        if (ReportGenerator.isFlowResult(result)) {
+          return ReportGenerator.generateFlowReportHtml(result);
+        }
+        return ReportGenerator.generateReportHtml(result);
       }
       // CSV report.
       if (outputMode === 'csv') {
-        return ReportGenerator.generateReportCSV(lhr);
+        if (ReportGenerator.isFlowResult(result)) {
+          throw new Error('CSV output is not support for user flows');
+        }
+        return ReportGenerator.generateReportCSV(result);
       }
       // JSON report.
       if (outputMode === 'json') {
-        return JSON.stringify(lhr, null, 2);
+        return JSON.stringify(result, null, 2);
       }
 
       throw new Error('Invalid output mode: ' + outputMode);

package/report/test/generator/report-generator-test.js

@@ -16,6 +16,7 @@ import {ReportGenerator} from '../../generator/report-generator.js';
 import {readJson} from '../../../core/test/test-utils.js';
 
 const sampleResults = readJson('core/test/results/sample_v2.json');
+const sampleFlowResult = readJson('core/test/fixtures/fraggle-rock/reports/sample-flow-result.json');
 
 describe('ReportGenerator', () => {
   describe('#replaceStrings', () => {
@@ -75,12 +76,23 @@ describe('ReportGenerator', () => {
       assert.doesNotThrow(_ => JSON.parse(jsonOutput));
     });
 
+    it('creates JSON for flow result', () => {
+      const jsonOutput = ReportGenerator.generateReport(sampleFlowResult, 'json');
+      assert.doesNotThrow(_ => JSON.parse(jsonOutput));
+    });
+
     it('creates HTML for results', () => {
       const htmlOutput = ReportGenerator.generateReport(sampleResults, 'html');
       assert.ok(/<!doctype/gim.test(htmlOutput));
       assert.ok(/<html lang="en"/gim.test(htmlOutput));
     });
 
+    it('creates HTML for flow result', () => {
+      const htmlOutput = ReportGenerator.generateReport(sampleFlowResult, 'html');
+      assert.ok(/<!doctype/gim.test(htmlOutput));
+      assert.ok(/<html lang="en"/gim.test(htmlOutput));
+    });
+
     it('creates CSV for results', async () => {
       const path = './.results-as-csv.csv';
 
@@ -126,6 +138,12 @@ category,audit,score,displayValue,description
       expect(csvOutput).toContain('pwa');
     });
 
+    it('throws when creating CSV for flow result', () => {
+      expect(() => {
+        ReportGenerator.generateReport(sampleFlowResult, 'csv');
+      }).toThrow('CSV output is not support for user flows');
+    });
+
     it('writes extended info', () => {
       const htmlOutput = ReportGenerator.generateReport(sampleResults, 'html');
       const outputCheck = new RegExp('dobetterweb/dbw_tester.css', 'i');

package/core/api.js

@@ -1,80 +0,0 @@
-/**
- * @license Copyright 2020 The Lighthouse Authors. 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.
- */
-
-import {UserFlow, auditGatherSteps} from './user-flow.js';
-import {snapshotGather} from './gather/snapshot-runner.js';
-import {startTimespanGather} from './gather/timespan-runner.js';
-import {navigationGather} from './gather/navigation-runner.js';
-import {ReportGenerator} from '../report/generator/report-generator.js';
-import {Runner} from './runner.js';
-
-/**
- * @param {LH.Puppeteer.Page} page
- * @param {LH.UserFlow.Options} [options]
- */
-async function startFlow(page, options) {
-  return new UserFlow(page, options);
-}
-
-/**
- * @param {LH.Puppeteer.Page|undefined} page
- * @param {LH.NavigationRequestor|undefined} requestor
- * @param {{config?: LH.Config.Json, flags?: LH.Flags}} [options]
- * @return {Promise<LH.RunnerResult|undefined>}
- */
-async function navigation(page, requestor, options) {
-  const gatherResult = await navigationGather(page, requestor, options);
-  return Runner.audit(gatherResult.artifacts, gatherResult.runnerOptions);
-}
-
-/**
- * @param {LH.Puppeteer.Page} page
- * @param {{config?: LH.Config.Json, flags?: LH.Flags}} [options]
- * @return {Promise<LH.RunnerResult|undefined>}
- */
-async function snapshot(page, options) {
-  const gatherResult = await snapshotGather(page, options);
-  return Runner.audit(gatherResult.artifacts, gatherResult.runnerOptions);
-}
-
-/**
- * @param {LH.Puppeteer.Page} page
- * @param {{config?: LH.Config.Json, flags?: LH.Flags}} [options]
- * @return {Promise<{endTimespan: () => Promise<LH.RunnerResult|undefined>}>}
- */
-async function startTimespan(page, options) {
-  const {endTimespanGather} = await startTimespanGather(page, options);
-  const endTimespan = async () => {
-    const gatherResult = await endTimespanGather();
-    return Runner.audit(gatherResult.artifacts, gatherResult.runnerOptions);
-  };
-  return {endTimespan};
-}
-
-/**
- * @param {LH.FlowResult} flowResult
- */
-async function generateFlowReport(flowResult) {
-  return ReportGenerator.generateFlowReportHtml(flowResult);
-}
-
-/**
- * @param {LH.UserFlow.FlowArtifacts} flowArtifacts
- * @param {LH.Config.Json} [config]
- */
-async function auditFlowArtifacts(flowArtifacts, config) {
-  const {gatherSteps, name} = flowArtifacts;
-  return await auditGatherSteps(gatherSteps, {name, config});
-}
-
-export {
-  snapshot,
-  startTimespan,
-  navigation,
-  startFlow,
-  generateFlowReport,
-  auditFlowArtifacts,
-};