Improved testing options

.husky/pre-commit

@@ -2,3 +2,11 @@
 . "$(dirname -- "$0")/_/husky.sh"
 
 npm exec lint-staged
+
+echo "Checking for leftover it.only's..."
+grep it.only test/*/* && exit 1
+
+echo "Checking for leftover browser.debug's..."
+grep browser.debug test/*/* && exit 1
+
+exit 0

docs/contributing.md → CONTRIBUTING.md

@@ -22,6 +22,20 @@ use GitHub pull requests for this purpose. Consult
 [GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
 information on using pull requests.
 
+## Testing
+
+To test the full suite run `npm run test`.
+
+To test an individual browser or metric, run the following in separate terminals:
+
+- `npm run watch`
+- `npm run test:server`
+- `npm run test:e2e -- --browser=chrome --metric=TTFB`
+
+To run an individual test, change `it('test name')` to `it.only('test name')`.
+
+You can also add `await browser.debug()` lines to the individual test files to pause execution, and press `CTRL+C` in the command line to continue the tests.
+
 ## Community Guidelines
 
 This project follows [Google's Open Source Community

README.md

@@ -639,6 +639,7 @@ interface Metric {
    * `undefined` if the browser doesn't support that API), with the following
    * exceptions:
    * - 'back-forward-cache': for pages that are restored from the bfcache.
+   * - 'back_forward' is renamed to 'back-forward' for consistency.
    * - 'prerender': for pages that were prerendered.
    * - 'restore': for pages that were discarded by the browser and then
    * restored by the user.

package.json

@@ -176,7 +176,8 @@
     "rollup": "^4.9.1",
     "selenium-standalone": "^9.3.1",
     "typescript": "^5.3.3",
-    "wdio-chromedriver-service": "^8.1.1"
+    "wdio-chromedriver-service": "^8.1.1",
+    "yargs": "^17.7.2"
   },
   "lint-staged": {
     "**/*.{js,ts}": "eslint --fix --ignore-path .gitignore",

src/attribution/onFCP.ts

@@ -17,6 +17,7 @@
 import {getBFCacheRestoreTime} from '../lib/bfcache.js';
 import {getLoadState} from '../lib/getLoadState.js';
 import {getNavigationEntry} from '../lib/getNavigationEntry.js';
+import {isInvalidTimestamp} from '../lib/isInvalidTimestamp.js';
 import {onFCP as unattributedOnFCP} from '../onFCP.js';
 import {
   FCPMetric,
@@ -32,8 +33,11 @@ const attributeFCP = (metric: FCPMetric): void => {
     const fcpEntry = metric.entries[metric.entries.length - 1];
 
     if (navigationEntry) {
+      const responseStart = navigationEntry.responseStart;
+      if (isInvalidTimestamp(responseStart)) return;
+
       const activationStart = navigationEntry.activationStart || 0;
-      const ttfb = Math.max(0, navigationEntry.responseStart - activationStart);
+      const ttfb = Math.max(0, responseStart - activationStart);
 
       (metric as FCPMetricWithAttribution).attribution = {
         timeToFirstByte: ttfb,

src/attribution/onLCP.ts

@@ -16,6 +16,7 @@
 
 import {getNavigationEntry} from '../lib/getNavigationEntry.js';
 import {getSelector} from '../lib/getSelector.js';
+import {isInvalidTimestamp} from '../lib/isInvalidTimestamp.js';
 import {onLCP as unattributedOnLCP} from '../onLCP.js';
 import {
   LCPAttribution,
@@ -31,6 +32,9 @@ const attributeLCP = (metric: LCPMetric) => {
     const navigationEntry = getNavigationEntry();
 
     if (navigationEntry) {
+      const responseStart = navigationEntry.responseStart;
+      if (isInvalidTimestamp(responseStart)) return;
+
       const activationStart = navigationEntry.activationStart || 0;
       const lcpEntry = metric.entries[metric.entries.length - 1];
       const lcpResourceEntry =
@@ -39,7 +43,7 @@ const attributeLCP = (metric: LCPMetric) => {
           .getEntriesByType('resource')
           .filter((e) => e.name === lcpEntry.url)[0];
 
-      const ttfb = Math.max(0, navigationEntry.responseStart - activationStart);
+      const ttfb = Math.max(0, responseStart - activationStart);
 
       const lcpRequestStart = Math.max(
         ttfb,
@@ -55,7 +59,7 @@ const attributeLCP = (metric: LCPMetric) => {
       );
       const lcpRenderTime = Math.max(
         lcpResponseEnd,
-        lcpEntry ? lcpEntry.startTime - activationStart : 0,
+        lcpEntry.startTime - activationStart,
       );
 
       const attribution: LCPAttribution = {

src/lib/isInvalidTimestamp.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * 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
+ *
+ *     https://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.
+ */
+
+export const isInvalidTimestamp = (timestamp: DOMHighResTimeStamp) => {
+  // In some cases no value is reported by the browser (for
+  // privacy/security reasons), and in other cases (bugs) the value is
+  // negative or is larger than the current page time. Ignore these cases:
+  // https://github.com/GoogleChrome/web-vitals/issues/137
+  // https://github.com/GoogleChrome/web-vitals/issues/162
+  // https://github.com/GoogleChrome/web-vitals/issues/275
+  return timestamp <= 0 || timestamp > performance.now();
+};

src/onTTFB.ts

@@ -16,6 +16,7 @@
 
 import {bindReporter} from './lib/bindReporter.js';
 import {initMetric} from './lib/initMetric.js';
+import {isInvalidTimestamp} from './lib/isInvalidTimestamp.js';
 import {onBFCacheRestore} from './lib/bfcache.js';
 import {getNavigationEntry} from './lib/getNavigationEntry.js';
 import {
@@ -77,13 +78,7 @@ export const onTTFB = (onReport: TTFBReportCallback, opts?: ReportOpts) => {
     if (navEntry) {
       const responseStart = navEntry.responseStart;
 
-      // In some cases no value is reported by the browser (for
-      // privacy/security reasons), and in other cases (bugs) the value is
-      // negative or is larger than the current page time. Ignore these cases:
-      // https://github.com/GoogleChrome/web-vitals/issues/137
-      // https://github.com/GoogleChrome/web-vitals/issues/162
-      // https://github.com/GoogleChrome/web-vitals/issues/275
-      if (responseStart <= 0 || responseStart > performance.now()) return;
+      if (isInvalidTimestamp(responseStart)) return;
 
       // The activationStart reference is used because TTFB should be
       // relative to page activation rather than navigation start if the

src/types/base.ts

@@ -78,6 +78,7 @@ export interface Metric {
    * `undefined` if the browser doesn't support that API), with the following
    * exceptions:
    * - 'back-forward-cache': for pages that are restored from the bfcache.
+   * - 'back_forward' is renamed to 'back-forward' for consistency.
    * - 'prerender': for pages that were prerendered.
    * - 'restore': for pages that were discarded by the browser and then
    * restored by the user.

wdio.conf.cjs

@@ -13,6 +13,13 @@
  limitations under the License.
 */
 
+const argv = require('yargs').argv;
+
+// Check if a metric has been provided as an argument and if so, limit tests to that metric
+const specs = argv.metric
+  ? `test/e2e/on${argv.metric}-test.js`
+  : 'test/e2e/*-test.js';
+
 module.exports.config = {
   //
   // ====================
@@ -36,7 +43,7 @@ module.exports.config = {
   // then the current working directory is where your `package.json` resides, so `wdio`
   // will be called from there.
   //
-  specs: ['test/e2e/*-test.js'],
+  specs: [specs],
   // Patterns to exclude.
   exclude: [
     // 'path/to/excluded/files'
@@ -331,3 +338,15 @@ module.exports.config = {
   // afterAssertion: function(params) {
   // }
 };
+
+// Check if a browser has been provided as an argument and, if so, remove the other browsers
+if (argv.browser) {
+  console.log('Limiting to browser:', argv.browser);
+  const capabilities = exports.config.capabilities;
+  Object.keys(exports.config.capabilities).forEach((key) => {
+    if (capabilities[key].browserName != argv.browser) {
+      console.log('Skipping', capabilities[key].browserName);
+      delete capabilities[key];
+    }
+  });
+}