All audits must specify helpText and failureDescription (#2737)

Author: paulirish

docs/recipes/custom-audit/searchable-audit.js

@@ -20,6 +20,7 @@ class LoadAudit extends Audit {
       category: 'MyCustomCategory',
       name: 'searchable-audit',
       description: 'Search box initialized and ready',
+      failureDescription: 'Search box slow to initialize',
       helpText: 'Used to measure time from navigationStart to when the search' +
           ' box is initialized and ready to search.',
 

lighthouse-core/audits/dobetterweb/password-inputs-can-be-pasted-into.js

@@ -17,7 +17,8 @@ class PasswordInputsCanBePastedIntoAudit extends Audit {
       name: 'password-inputs-can-be-pasted-into',
       description: 'Allows users to paste into password fields',
       failureDescription: 'Prevents users to paste into password fields',
-      helpText: '',
+      helpText: 'Preventing password pasting undermines good security policy. ' +
+          '[Learn more](https://www.ncsc.gov.uk/blog-post/let-them-paste-passwords)',
       requiredArtifacts: ['PasswordInputsWithPreventedPaste']
     };
   }

lighthouse-core/config/config.js

@@ -193,13 +193,17 @@ function assertValidAudit(auditDefinition, auditPath) {
   if (typeof auditDefinition.meta.failureDescription !== 'string' &&
     auditDefinition.meta.informative !== true &&
     auditDefinition.meta.scoringMode !== Audit.SCORING_MODES.NUMERIC) {
-    log.warn('config', `${auditName} has no failureDescription and should.`);
+    throw new Error(`${auditName} has no failureDescription and should.`);
   }
 
   if (typeof auditDefinition.meta.helpText !== 'string') {
     throw new Error(
       `${auditName} has no meta.helpText property, or the property is not a string.`
     );
+  } else if (auditDefinition.meta.helpText === '') {
+    throw new Error(
+      `${auditName} has an empty meta.helpText string. Please add a description for the UI.`
+    );
   }
 
   if (!Array.isArray(auditDefinition.meta.requiredArtifacts)) {

lighthouse-core/test/config/config-test.js

@@ -38,7 +38,8 @@ describe('Config', () => {
           name: 'MyAudit',
           category: 'mine',
           description: 'My audit',
-          helpText: '',
+          failureDescription: 'My failing audit',
+          helpText: '.',
           requiredArtifacts: []
         };
       }
@@ -443,6 +444,7 @@ describe('Config', () => {
           name: 'custom-audit',
           category: 'none',
           description: 'none',
+          failureDescription: 'none',
           helpText: 'none',
           requiredArtifacts: [],
         };

lighthouse-core/test/fixtures/invalid-audits/missing-audit.js

@@ -25,7 +25,7 @@ class MissingRequiredArtifacts extends LighthouseAudit {
       name: 'missing-category',
       category: 'Custom',
       description: 'Missing required artifacts',
-      helpText: '',
+      helpText: 'This is missing required artifacts',
       requiredArtifacts: ['HTML']
     };
   }

lighthouse-core/test/fixtures/invalid-audits/missing-category.js

@@ -24,7 +24,7 @@ class MissingRequiredArtifacts extends LighthouseAudit {
     return {
       name: 'missing-category',
       description: 'Missing required artifacts',
-      helpText: '',
+      helpText: 'This is missing a required category',
       requiredArtifacts: ['HTML']
     };
   }

lighthouse-core/test/fixtures/invalid-audits/missing-description.js

@@ -24,7 +24,7 @@ class MissingRequiredArtifacts extends LighthouseAudit {
     return {
       name: 'missing-description',
       category: 'Custom',
-      helpText: '',
+      helpText: 'This is missing required description (and failure description)',
       requiredArtifacts: ['HTML']
     };
   }

lighthouse-core/test/fixtures/invalid-audits/missing-generate-audit-result.js

@@ -23,7 +23,7 @@ class MissingRequiredArtifacts {
       category: 'Custom',
       name: 'missing-required-artifacts',
       description: 'Missing required artifacts',
-      helpText: '',
+      helpText: 'This is missing required artifacts',
       requiredArtifacts: ['HTML']
     };
   }

lighthouse-core/test/fixtures/invalid-audits/missing-help-text.js

@@ -25,6 +25,7 @@ class MissingRequiredArtifacts extends LighthouseAudit {
       name: 'missing-description',
       category: 'Custom',
       description: 'Missing required artifacts',
+      failureDescription: 'Missing required artifacts is failing',
       requiredArtifacts: ['HTML']
     };
   }

lighthouse-core/test/fixtures/invalid-audits/missing-name.js

@@ -24,7 +24,7 @@ class MissingRequiredArtifacts extends LighthouseAudit {
     return {
       category: 'Custom',
       description: 'Missing name',
-      helpText: '',
+      helpText: 'This is missing required name',
       requiredArtifacts: ['HTML']
     };
   }