All audits must specify helpText and failureDescription (#2737)

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']
     };
   }

lighthouse-core/test/fixtures/invalid-audits/missing-required-artifacts.js

@@ -25,7 +25,8 @@ class MissingRequiredArtifacts extends LighthouseAudit {
       category: 'Custom',
       name: 'missing-required-artifacts',
       description: 'Missing required artifacts',
-      helpText: '',
+      failureDescription: 'Missing required artifacts is failing',
+      helpText: 'This is missing required artifacts',
     };
   }
 

lighthouse-core/test/fixtures/invalid-audits/require-error.js

@@ -25,7 +25,7 @@ class RequireErrorAudit extends LighthouseAudit {
       name: 'require-error',
       category: 'Custom',
       description: 'Require Error',
-      helpText: '',
+      helpText: 'This one has a bad require()',
       requiredArtifacts: ['HTML']
     };
   }

lighthouse-core/test/fixtures/valid-custom-audit.js

@@ -25,6 +25,7 @@ class ValidCustomAudit extends LighthouseAudit {
       name: 'valid-audit',
       category: 'Custom',
       description: 'Valid Audit',
+      failureDescription: 'Valid failing Audit',
       helpText: 'Valid-sounding helpText',
       requiredArtifacts: ['HTML']
     };

lighthouse-core/test/report/v2/renderer/category-renderer-test.js

@@ -59,20 +59,20 @@ describe('CategoryRenderer', () => {
   it('renders an audit debug str when appropriate', () => {
     const audit1 = renderer._renderAudit({
       scoringMode: 'binary', score: 0,
-      result: {helpText: '', debugString: 'Debug string', description: 'Audit title'},
+      result: {helpText: 'help text', debugString: 'Debug string', description: 'Audit title'},
     });
     assert.ok(audit1.querySelector('.lh-debug'));
 
     const audit2 = renderer._renderAudit({
-      scoringMode: 'binary', score: 0, result: {helpText: '', description: 'Audit title'},
+      scoringMode: 'binary', score: 0, result: {helpText: 'help text', description: 'Audit title'},
     });
     assert.ok(!audit2.querySelector('.lh-debug'));
   });
 
   it('renders an informative audit', () => {
     const auditDOM = renderer._renderAudit({
       id: 'informative', score: 0,
-      result: {description: 'It informs', helpText: '', informative: true},
+      result: {description: 'It informs', helpText: 'help text', informative: true},
     });
 
     assert.ok(auditDOM.querySelector('.lh-score--informative'));

lighthouse-core/test/runner-test.js

@@ -187,6 +187,7 @@ describe('Runner', () => {
       category: 'ThrowThrow',
       name: 'throwy-audit',
       description: 'Always throws',
+      failureDescription: 'Always throws is failing, natch',
       helpText: 'Test for always throwing',
       requiredArtifacts: []
     };