feat(cli): add user-timing assertion support (#280)

Author: patrickhulce

docs/assertions.md

@@ -101,6 +101,23 @@ The below example warns when FCP is above 2 seconds on _all_ pages and warns whe
 }
 ```
 
+### User Timings
+
+Your custom user timings using [`performance.mark`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) and [`performance.measure`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/measure) can be asserted against as well.
+
+The general format for asserting against a user timing value is `"user-timings:<kebab-cased-name>": ["<level>", {maxNumericValue: <value in milliseconds>}]`. For example, if you wanted to assert that a mark with name `My Custom Mark` started within the first 2s of page load and that a measure `my:custom-@-Measure` lasted fewer than 50 ms you would use the following assertions config.
+
+Note that only the first matching entry with the name will be used from each run and the rest will be ignored.
+
+```json
+{
+  "assertions": {
+    "user-timings:my-custom-mark": ["warn", {"maxNumericValue": 2000}],
+    "user-timings:my-custom-measure": ["error", {"maxNumericValue": 50}]
+  }
+}
+```
+
 ## Presets
 
 There are three presets available to provide a good starting point. Presets can be extended with manual assertions.

packages/utils/src/assertions.js

@@ -311,6 +311,22 @@ function getAssertionResultsForAudit(auditId, auditProperty, auditResults, asser
       ...result,
       auditProperty: auditProperty.join('.'),
     }));
+  } else if (auditId === 'user-timings' && auditProperty) {
+    const userTimingName = _.kebabCase(auditProperty.join('-'), {alphanumericOnly: true});
+    const psuedoAuditResults = auditResults.map(result => {
+      if (!result || !result.details || !result.details.items) return;
+      const item = result.details.items.find(
+        item => _.kebabCase(item.name, {alphanumericOnly: true}) === userTimingName
+      );
+      if (!item) return;
+      const numericValue = Number.isFinite(item.duration) ? item.duration : item.startTime;
+      return {...result, numericValue};
+    });
+
+    return getStandardAssertionResults(psuedoAuditResults, assertionOptions).map(result => ({
+      ...result,
+      auditProperty: userTimingName,
+    }));
   } else {
     return getStandardAssertionResults(auditResults, assertionOptions);
   }
@@ -342,7 +358,7 @@ function resolveAssertionOptionsAndLhrs(baseOptions, unfilteredLhrs) {
     lhrs.map(lhr => /** @type {[LH.Result, LH.Result]} */ ([lhr, lhr])),
   ]);
 
-  const auditsToAssert = [...new Set(Object.keys(assertions).map(_.kebabCase))].map(
+  const auditsToAssert = [...new Set(Object.keys(assertions).map(key => _.kebabCase(key)))].map(
     assertionKey => {
       const [auditId, ...rest] = assertionKey.split(/\.|:/g).filter(Boolean);
       const auditInstances = lhrs.map(lhr => lhr.audits[auditId]).filter(Boolean);

packages/utils/src/lodash.js

@@ -44,9 +44,17 @@ function merge(v1, v2) {
 /**
  * Converts a string from camelCase to kebab-case.
  * @param {string} s
+ * @param {{alphanumericOnly?: boolean}} [opts]
  */
-function kebabCase(s) {
-  return s.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase();
+function kebabCase(s, opts) {
+  let kebabed = s.replace(/([a-z])([A-Z])/g, '$1-$2');
+  if (opts && opts.alphanumericOnly) {
+    kebabed = kebabed
+      .replace(/[^a-z0-9]+/gi, '-')
+      .replace(/-+/g, '-')
+      .replace(/(^-|-$)/g, '');
+  }
+  return kebabed.toLowerCase();
 }
 
 /**

packages/utils/test/assertions.test.js

@@ -701,6 +701,105 @@ describe('getAllAssertionResults', () => {
     });
   });
 
+  describe('user timings', () => {
+    let lhrWithUserTimings;
+
+    beforeEach(() => {
+      lhrWithUserTimings = {
+        finalUrl: 'http://example.com',
+        audits: {
+          'user-timings': {
+            details: {
+              items: [
+                {name: 'Core initializer', startTime: 757, duration: 123, timingType: 'Measure'},
+                {name: 'super_Cool_Measure', startTime: 999, duration: 52, timingType: 'Measure'},
+                {name: 'ultraCoolMark', startTime: 5231, timingType: 'Mark'},
+                {name: 'other:%Cool.Mark', startTime: 12052, timingType: 'Mark'},
+                // Duplicates will be ignored
+                {name: 'super_Cool_Measure', startTime: 0, duration: 4252, timingType: 'Measure'},
+              ],
+            },
+          },
+        },
+      };
+    });
+
+    it('should assert user timing keys', () => {
+      const assertions = {
+        'user-timings.core-initializer': ['error', {maxNumericValue: 100}],
+        'user-timings.super-cool-measure': ['warn', {maxNumericValue: 100}],
+        'user-timings:ultra-cool-mark': ['warn', {maxNumericValue: 5000}],
+        'user-timings:other-cool-mark': ['error', {maxNumericValue: 10000}],
+        'user-timings:missing-timing': ['error', {maxNumericValue: 10000}],
+      };
+
+      const lhrs = [lhrWithUserTimings, lhrWithUserTimings];
+      const results = getAllAssertionResults({assertions, includePassedAssertions: true}, lhrs);
+      expect(results).toEqual([
+        {
+          actual: 123,
+          auditId: 'user-timings',
+          auditProperty: 'core-initializer',
+          expected: 100,
+          level: 'error',
+          name: 'maxNumericValue',
+          operator: '<=',
+          passed: false,
+          url: 'http://example.com',
+          values: [123, 123],
+        },
+        {
+          actual: 52,
+          auditId: 'user-timings',
+          auditProperty: 'super-cool-measure',
+          expected: 100,
+          level: 'warn',
+          name: 'maxNumericValue',
+          operator: '<=',
+          passed: true,
+          url: 'http://example.com',
+          values: [52, 52],
+        },
+        {
+          actual: 5231,
+          auditId: 'user-timings',
+          auditProperty: 'ultra-cool-mark',
+          expected: 5000,
+          level: 'warn',
+          name: 'maxNumericValue',
+          operator: '<=',
+          passed: false,
+          url: 'http://example.com',
+          values: [5231, 5231],
+        },
+        {
+          actual: 12052,
+          auditId: 'user-timings',
+          auditProperty: 'other-cool-mark',
+          expected: 10000,
+          level: 'error',
+          name: 'maxNumericValue',
+          operator: '<=',
+          passed: false,
+          url: 'http://example.com',
+          values: [12052, 12052],
+        },
+        {
+          actual: 0,
+          auditId: 'user-timings',
+          auditProperty: 'missing-timing',
+          expected: 1,
+          level: 'error',
+          name: 'auditRan',
+          operator: '>=',
+          passed: false,
+          url: 'http://example.com',
+          values: [0, 0],
+        },
+      ]);
+    });
+  });
+
   describe('URL-grouping', () => {
     beforeEach(() => {
       for (const lhr of [...lhrs]) {

packages/utils/test/lodash.test.js

@@ -135,12 +135,31 @@ describe('lodash.js', () => {
       // WAI
       expect(_.kebabCase('camelCase')).toEqual('camel-case');
       expect(_.kebabCase('kebab-case')).toEqual('kebab-case');
+      expect(_.kebabCase('exampleURL')).toEqual('example-url');
 
       // Not implemented but should probably work consistently at some point.
       // Tests just for documentation.
+      expect(_.kebabCase('kebab-case:document.type')).toEqual('kebab-case:document.type');
+      expect(_.kebabCase('mixed-Case3_Issues+')).toEqual('mixed-case3_issues+');
       expect(_.kebabCase('ALL CAPS')).toEqual('all caps');
       expect(_.kebabCase('snake_case')).toEqual('snake_case');
     });
+
+    it('should convert strings to kebab-case alphanumericOnly', () => {
+      // WAI
+      expect(_.kebabCase('camelCase', {alphanumericOnly: true})).toEqual('camel-case');
+      expect(_.kebabCase('kebab-case', {alphanumericOnly: true})).toEqual('kebab-case');
+      expect(_.kebabCase('kebab-case:document.type', {alphanumericOnly: true})).toEqual(
+        'kebab-case-document-type'
+      );
+      expect(_.kebabCase('exampleURL', {alphanumericOnly: true})).toEqual('example-url');
+      expect(_.kebabCase('!exampleURL', {alphanumericOnly: true})).toEqual('example-url');
+      expect(_.kebabCase('mixed-Case3_Issues+', {alphanumericOnly: true})).toEqual(
+        'mixed-case3-issues'
+      );
+      expect(_.kebabCase('ALL CAPS', {alphanumericOnly: true})).toEqual('all-caps');
+      expect(_.kebabCase('snake_case', {alphanumericOnly: true})).toEqual('snake-case');
+    });
   });
 
   describe('#startCase', () => {