core(fr): add basic timespan support

lighthouse-core/fraggle-rock/api.js

@@ -5,61 +5,10 @@
  */
 'use strict';
 
-const Driver = require('./gather/driver.js');
-const Runner = require('../runner.js');
-const {initializeConfig} = require('./config/config.js');
-
-/** @param {{page: import('puppeteer').Page, config?: LH.Config.Json}} options */
-async function snapshot(options) {
-  const {config} = initializeConfig(options.config, {gatherMode: 'snapshot'});
-  const driver = new Driver(options.page);
-  await driver.connect();
-
-  const url = await options.page.url();
-
-  return Runner.run(
-    async () => {
-      /** @type {LH.BaseArtifacts} */
-      const baseArtifacts = {
-        fetchTime: new Date().toJSON(),
-        LighthouseRunWarnings: [],
-        URL: {requestedUrl: url, finalUrl: url},
-        Timing: [],
-        Stacks: [],
-        settings: config.settings,
-        // TODO(FR-COMPAT): convert these to regular artifacts
-        HostFormFactor: 'mobile',
-        HostUserAgent: 'unknown',
-        NetworkUserAgent: 'unknown',
-        BenchmarkIndex: 0,
-        InstallabilityErrors: {errors: []},
-        traces: {},
-        devtoolsLogs: {},
-        WebAppManifest: null,
-        PageLoadError: null,
-      };
-
-      /** @type {Partial<LH.GathererArtifacts>} */
-      const artifacts = {};
-
-      for (const {id, gatherer} of config.artifacts || []) {
-        const artifactName = /** @type {keyof LH.GathererArtifacts} */ (id);
-        const artifact = await Promise.resolve()
-          .then(() => gatherer.instance.snapshot({gatherMode: 'snapshot', driver}))
-          .catch(err => err);
-
-        artifacts[artifactName] = artifact;
-      }
-
-      return /** @type {LH.Artifacts} */ ({...baseArtifacts, ...artifacts}); // Cast to drop Partial<>
-    },
-    {
-      url,
-      config,
-    }
-  );
-}
+const {snapshot} = require('./gather/snapshot-runner.js');
+const {startTimespan} = require('./gather/timespan-runner.js');
 
 module.exports = {
   snapshot,
+  startTimespan,
 };

lighthouse-core/fraggle-rock/config/default-config.js

@@ -11,6 +11,7 @@ const legacyDefaultConfig = require('../../config/default-config.js');
 const defaultConfig = {
   artifacts: [
     {id: 'Accessibility', gatherer: 'accessibility'},
+    {id: 'ConsoleMessages', gatherer: 'console-messages'},
   ],
   settings: legacyDefaultConfig.settings,
   audits: legacyDefaultConfig.audits,

lighthouse-core/fraggle-rock/gather/base-artifacts.js

@@ -0,0 +1,34 @@
+/**
+ * @license Copyright 2021 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.
+ */
+'use strict';
+
+/**
+ * @param {LH.Config.FRConfig} config
+ * @return {LH.BaseArtifacts}
+ */
+function getBaseArtifacts(config) {
+  // TODO(FR-COMPAT): convert these to regular artifacts
+
+  return {
+    fetchTime: new Date().toJSON(),
+    LighthouseRunWarnings: [],
+    URL: {requestedUrl: '', finalUrl: ''},
+    Timing: [],
+    Stacks: [],
+    settings: config.settings,
+    HostFormFactor: 'mobile',
+    HostUserAgent: 'unknown',
+    NetworkUserAgent: 'unknown',
+    BenchmarkIndex: 0,
+    InstallabilityErrors: {errors: []},
+    traces: {},
+    devtoolsLogs: {},
+    WebAppManifest: null,
+    PageLoadError: null,
+  };
+}
+
+module.exports = {getBaseArtifacts};

lighthouse-core/fraggle-rock/gather/base-gatherer.js

@@ -26,6 +26,20 @@ class FRGatherer {
    */
   snapshot(passContext) { }
 
+  /**
+   * Method to start observing a page for an arbitrary period of time.
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   * @return {Promise<void>|void}
+   */
+  beforeTimespan(passContext) { }
+
+  /**
+   * Method to end observing a page after an arbitrary period of time and return the results.
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
+   * @return {LH.Gatherer.PhaseResult}
+   */
+  afterTimespan(passContext) { }
+
   /**
    * Legacy property used to define the artifact ID. In Fraggle Rock, the artifact ID lives on the config.
    * @return {keyof LH.GathererArtifacts}
@@ -38,9 +52,11 @@ class FRGatherer {
   /**
    * Legacy method. Called before navigation to target url, roughly corresponds to `beforeTimespan`.
    * @param {LH.Gatherer.PassContext} passContext
-   * @return {LH.Gatherer.PhaseResult}
+   * @return {Promise<LH.Gatherer.PhaseResultNonPromise>}
    */
-  beforePass(passContext) { }
+  async beforePass(passContext) {
+    await this.beforeTimespan(passContext);
+  }
 
   /**
    * Legacy method. Should never be used by a Fraggle Rock gatherer, here for compat only.
@@ -53,9 +69,13 @@ class FRGatherer {
    * Legacy method. Roughly corresponds to `afterTimespan` or `snapshot` depending on type of gatherer.
    * @param {LH.Gatherer.PassContext} passContext
    * @param {LH.Gatherer.LoadData} loadData
-   * @return {LH.Gatherer.PhaseResult}
+   * @return {Promise<LH.Gatherer.PhaseResultNonPromise>}
    */
-  afterPass(passContext, loadData) {
+  async afterPass(passContext, loadData) {
+    if (this.meta.supportedModes.includes('timespan')) {
+      return this.afterTimespan(passContext);
+    }
+
     return this.snapshot(passContext);
   }
 }

lighthouse-core/fraggle-rock/gather/snapshot-runner.js

@@ -0,0 +1,50 @@
+/**
+ * @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.
+ */
+'use strict';
+
+const Driver = require('./driver.js');
+const Runner = require('../../runner.js');
+const {initializeConfig} = require('../config/config.js');
+const {getBaseArtifacts} = require('./base-artifacts.js');
+
+/** @param {{page: import('puppeteer').Page, config?: LH.Config.Json}} options */
+async function snapshot(options) {
+  const {config} = initializeConfig(options.config, {gatherMode: 'snapshot'});
+  const driver = new Driver(options.page);
+  await driver.connect();
+
+  const url = await options.page.url();
+
+  return Runner.run(
+    async () => {
+      const baseArtifacts = getBaseArtifacts(config);
+      baseArtifacts.URL.requestedUrl = url;
+      baseArtifacts.URL.finalUrl = url;
+
+      /** @type {Partial<LH.GathererArtifacts>} */
+      const artifacts = {};
+
+      for (const {id, gatherer} of config.artifacts || []) {
+        const artifactName = /** @type {keyof LH.GathererArtifacts} */ (id);
+        const artifact = await Promise.resolve()
+          .then(() => gatherer.instance.snapshot({gatherMode: 'snapshot', driver}))
+          .catch(err => err);
+
+        artifacts[artifactName] = artifact;
+      }
+
+      return /** @type {LH.Artifacts} */ ({...baseArtifacts, ...artifacts}); // Cast to drop Partial<>
+    },
+    {
+      url,
+      config,
+    }
+  );
+}
+
+module.exports = {
+  snapshot,
+};

lighthouse-core/fraggle-rock/gather/timespan-runner.js

@@ -0,0 +1,69 @@
+/**
+ * @license Copyright 2021 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.
+ */
+'use strict';
+
+const Driver = require('./driver.js');
+const Runner = require('../../runner.js');
+const {initializeConfig} = require('../config/config.js');
+const {getBaseArtifacts} = require('./base-artifacts.js');
+
+/**
+ * @param {{page: import('puppeteer').Page, config?: LH.Config.Json}} options
+ * @return {Promise<{endTimespan(): Promise<LH.RunnerResult|undefined>}>}
+ */
+async function startTimespan(options) {
+  const {config} = initializeConfig(options.config, {gatherMode: 'timespan'});
+  const driver = new Driver(options.page);
+  await driver.connect();
+
+  const requestedUrl = await options.page.url();
+
+  /** @type {Record<string, Promise<Error|undefined>>} */
+  const artifactErrors = {};
+
+  for (const {id, gatherer} of config.artifacts || []) {
+    artifactErrors[id] = await Promise.resolve()
+      .then(() => gatherer.instance.beforeTimespan({gatherMode: 'timespan', driver}))
+      .catch(err => err);
+  }
+
+  return {
+    async endTimespan() {
+      const finalUrl = await options.page.url();
+      return Runner.run(
+        async () => {
+          const baseArtifacts = getBaseArtifacts(config);
+          baseArtifacts.URL.requestedUrl = requestedUrl;
+          baseArtifacts.URL.finalUrl = finalUrl;
+
+          /** @type {Partial<LH.GathererArtifacts>} */
+          const artifacts = {};
+
+          for (const {id, gatherer} of config.artifacts || []) {
+            const artifactName = /** @type {keyof LH.GathererArtifacts} */ (id);
+            const artifact = artifactErrors[id]
+              ? Promise.reject(artifactErrors[id])
+              : await Promise.resolve()
+                  .then(() => gatherer.instance.afterTimespan({gatherMode: 'timespan', driver}))
+                  .catch(err => err);
+
+            artifacts[artifactName] = artifact;
+          }
+
+          return /** @type {LH.Artifacts} */ ({...baseArtifacts, ...artifacts}); // Cast to drop Partial<>
+        },
+        {
+          url: finalUrl,
+          config,
+        }
+      );
+    },
+  };
+}
+
+module.exports = {
+  startTimespan,
+};

lighthouse-core/gather/gatherers/console-messages.js

@@ -11,7 +11,7 @@
 
 'use strict';
 
-const Gatherer = require('./gatherer.js');
+const Gatherer = require('../../fraggle-rock/gather/base-gatherer.js');
 
 /**
  * @param {LH.Crdp.Runtime.RemoteObject} obj
@@ -30,7 +30,16 @@ function remoteObjectToString(obj) {
   return `[${type} ${className}]`;
 }
 
+/**
+ * @implements {LH.Gatherer.GathererInstance}
+ * @implements {LH.Gatherer.FRGathererInstance}
+ */
 class ConsoleMessages extends Gatherer {
+  /** @type {LH.Gatherer.GathererMeta} */
+  meta = {
+    supportedModes: ['timespan', 'navigation'],
+  }
+
   constructor() {
     super();
     /** @type {LH.Artifacts.ConsoleMessage[]} */
@@ -120,33 +129,33 @@ class ConsoleMessages extends Gatherer {
   }
 
   /**
-   * @param {LH.Gatherer.PassContext} passContext
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
    */
-  async beforePass(passContext) {
-    const driver = passContext.driver;
+  async beforeTimespan(passContext) {
+    const session = passContext.driver.defaultSession;
 
-    driver.on('Log.entryAdded', this._onLogEntryAdded);
-    await driver.sendCommand('Log.enable');
-    await driver.sendCommand('Log.startViolationsReport', {
+    session.on('Log.entryAdded', this._onLogEntryAdded);
+    await session.sendCommand('Log.enable');
+    await session.sendCommand('Log.startViolationsReport', {
       config: [{name: 'discouragedAPIUse', threshold: -1}],
     });
 
-    driver.on('Runtime.consoleAPICalled', this._onConsoleAPICalled);
-    driver.on('Runtime.exceptionThrown', this._onExceptionThrown);
-    await driver.sendCommand('Runtime.enable');
+    session.on('Runtime.consoleAPICalled', this._onConsoleAPICalled);
+    session.on('Runtime.exceptionThrown', this._onExceptionThrown);
+    await session.sendCommand('Runtime.enable');
   }
 
   /**
-   * @param {LH.Gatherer.PassContext} passContext
+   * @param {LH.Gatherer.FRTransitionalContext} passContext
    * @return {Promise<LH.Artifacts['ConsoleMessages']>}
    */
-  async afterPass({driver}) {
-    await driver.sendCommand('Log.stopViolationsReport');
-    await driver.off('Log.entryAdded', this._onLogEntryAdded);
-    await driver.sendCommand('Log.disable');
-    await driver.off('Runtime.consoleAPICalled', this._onConsoleAPICalled);
-    await driver.off('Runtime.exceptionThrown', this._onExceptionThrown);
-    await driver.sendCommand('Runtime.disable');
+  async afterTimespan({driver}) {
+    await driver.defaultSession.sendCommand('Log.stopViolationsReport');
+    await driver.defaultSession.off('Log.entryAdded', this._onLogEntryAdded);
+    await driver.defaultSession.sendCommand('Log.disable');
+    await driver.defaultSession.off('Runtime.consoleAPICalled', this._onConsoleAPICalled);
+    await driver.defaultSession.off('Runtime.exceptionThrown', this._onExceptionThrown);
+    await driver.defaultSession.sendCommand('Runtime.disable');
     return this._logEntries;
   }
 }

lighthouse-core/test/fixtures/fraggle-rock/snapshot-basic/onclick.html

@@ -32,8 +32,11 @@
 
     document.addEventListener('click', () => {
       addTemplate('#violations');
+      console.error('Accessibility violations added!');
     });
 
+    // Add the click target with JavaScript so when we `waitFor('#click-target')` we know that
+    // the listener has been installed too.
     addTemplate('#click-target');
   </script>
 </body>