Add failureDescription to audit. display on fail (#2478)

lighthouse-core/audits/accessibility/accesskeys.js

@@ -21,6 +21,7 @@ class Accesskeys extends AxeAudit {
       category: 'Accessibility',
       name: 'accesskeys',
       description: '`[accesskey]` values are unique.',
+      failureDescription: '`[accesskey]` values are not unique.',
       helpText: 'Access keys let users quickly focus a part of the page. For proper ' +
           'navigation, each access key must be unique. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/accesskeys).',

lighthouse-core/audits/accessibility/aria-allowed-attr.js

@@ -21,6 +21,7 @@ class ARIAAllowedAttr extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-allowed-attr',
       description: '`[aria-*]` attributes match their roles.',
+      failureDescription: '`[aria-*]` attributes do not match their roles.',
       helpText: 'Each ARIA `role` supports a specific subset of `aria-*` attributes. ' +
           'Mismatching these invalidates the `aria-*` attributes. [Learn ' +
           'more](https://developers.google.com/web/tools/lighthouse/audits/aria-allowed-attributes).',

lighthouse-core/audits/accessibility/aria-required-attr.js

@@ -21,6 +21,7 @@ class ARIARequiredAttr extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-required-attr',
       description: '`[role]`s have all required `[aria-*]` attributes.',
+      failureDescription: '`[role]`s do not have all required `[aria-*]` attributes.',
       helpText: 'Some ARIA roles have required attributes that describe the state ' +
           'of the element to screen readers. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/required-aria-attributes).',
       requiredArtifacts: ['Accessibility']

lighthouse-core/audits/accessibility/aria-required-children.js

@@ -21,7 +21,9 @@ class AriaRequiredChildren extends AxeAudit {
     return {
       category: 'Accessibility',
       name: 'aria-required-children',
-      description: '`[role]`s that require child `[role]`s contain them.',
+      description: 'Elements with `[role]` that require specific children `[role]`s, are present.',
+      failureDescription: 'Elements with `[role]` that require specific children `[role]`s, ' +
+          'are missing.',
       helpText: 'Some ARIA parent roles must contain specific child roles to perform ' +
           'their intended accessibility functions. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/aria-required-children).',

lighthouse-core/audits/accessibility/aria-required-parent.js

@@ -22,6 +22,7 @@ class AriaRequiredParent extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-required-parent',
       description: '`[role]`s are contained by their required parent element.',
+      failureDescription: '`[role]`s are not contained by their required parent element.',
       helpText: 'Some ARIA child roles must be contained by specific parent roles to ' +
           'properly perform their intended accessibility functions. ' +
           '[Learn more](https://dequeuniversity.com/rules/worldspace/2.1/aria-required-parent).',

lighthouse-core/audits/accessibility/aria-roles.js

@@ -21,6 +21,7 @@ class AriaRoles extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-roles',
       description: '`[role]` values are valid.',
+      failureDescription: '`[role]` values are not valid.',
       helpText: 'ARIA roles must have valid values in order to perform their ' +
           'intended accessibility functions. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/aria-roles).',

lighthouse-core/audits/accessibility/aria-valid-attr-value.js

@@ -21,6 +21,7 @@ class ARIAValidAttr extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-valid-attr-value',
       description: '`[aria-*]` attributes have valid values.',
+      failureDescription: '`[aria-*]` attributes do not have valid values.',
       helpText: 'Assistive technologies, like screen readers, can\'t interpret ARIA ' +
           'attributes with invalid values. [Learn ' +
           'more](https://developers.google.com/web/tools/lighthouse/audits/valid-aria-values).',

lighthouse-core/audits/accessibility/aria-valid-attr.js

@@ -21,6 +21,7 @@ class ARIAValidAttr extends AxeAudit {
       category: 'Accessibility',
       name: 'aria-valid-attr',
       description: '`[aria-*]` attributes are valid and not misspelled.',
+      failureDescription: '`[aria-*]` attributes are not valid or misspelled.',
       helpText: 'Assistive technologies, like screen readers, can\'t interpret ARIA ' +
           'attributes with invalid names. [Learn ' +
           'more](https://developers.google.com/web/tools/lighthouse/audits/valid-aria-attributes).',

lighthouse-core/audits/accessibility/audio-caption.js

@@ -21,6 +21,8 @@ class AudioCaption extends AxeAudit {
       category: 'Accessibility',
       name: 'audio-caption',
       description: '`<audio>` elements contain a `<track>` element with `[kind="captions"]`.',
+      failureDescription: '`<audio>` elements are missing a `<track>` element with ' +
+          '`[kind="captions"]`.',
       helpText: 'Captions make audio elements usable for deaf or hearing-impaired users, ' +
           'providing critical information such as who is talking, what they\'re saying, ' +
           'and other non-speech information. ' +

lighthouse-core/audits/accessibility/button-name.js

@@ -21,6 +21,7 @@ class ButtonName extends AxeAudit {
       category: 'Accessibility',
       name: 'button-name',
       description: 'Buttons have an accessible name.',
+      failureDescription: 'Buttons do not have an accessible name.',
       helpText: 'When a button doesn\'t have an accessible name, screen readers announce it as ' +
           '"button", making it unusable for users who rely on screen readers. ' +
           '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/button-name).',

lighthouse-core/audits/accessibility/bypass.js

@@ -22,6 +22,7 @@ class Bypass extends AxeAudit {
       category: 'Accessibility',
       name: 'bypass',
       description: 'The page contains a heading, skip link, or landmark region.',
+      failureDescription: 'The page does not contain a heading, skip link, or landmark region.',
       helpText: 'Adding ways to bypass repetitive content lets keyboard users navigate the page ' +
           'more efficiently. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/bypass).',

lighthouse-core/audits/accessibility/color-contrast.js

@@ -22,6 +22,8 @@ class ColorContrast extends AxeAudit {
       category: 'Accessibility',
       name: 'color-contrast',
       description: 'Background and foreground colors have a sufficient contrast ratio.',
+      failureDescription: 'Background and foreground colors do not have a ' +
+          'sufficient contrast ratio.',
       helpText: 'Low-contrast text is difficult or impossible for many users to read. ' +
           '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/contrast-ratio).',
       requiredArtifacts: ['Accessibility']

lighthouse-core/audits/accessibility/definition-list.js

@@ -21,7 +21,9 @@ class DefinitionList extends AxeAudit {
       category: 'Accessibility',
       name: 'definition-list',
       description: '`<dl>`\'s contain only properly-ordered `<dt>` and `<dd>` groups, `<script>` ' +
-          'or <template> elements.',
+          'or `<template>` elements.',
+      failureDescription: '`<dl>`\'s do not contain only properly-ordered `<dt>` and `<dd>` ' +
+          'groups, `<script>` or `<template>` elements.',
       helpText: 'When definition lists are not properly marked up, screen readers may produce ' +
           'confusing or inaccurate output. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/definition-list).',

lighthouse-core/audits/accessibility/dlitem.js

@@ -21,6 +21,7 @@ class DLItem extends AxeAudit {
       category: 'Accessibility',
       name: 'dlitem',
       description: 'Definition list items are wrapped in `<dl>` elements.',
+      failureDescription: 'Definition list items are not wrapped in `<dl>` elements.',
       helpText: 'Definition list items (`<dt>` and `<dd>`) must be wrapped in a ' +
           'parent `<dl>` element to ensure that screen readers can properly announce them. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/dlitem).',

lighthouse-core/audits/accessibility/document-title.js

@@ -21,6 +21,7 @@ class DocumentTitle extends AxeAudit {
       category: 'Accessibility',
       name: 'document-title',
       description: 'Document has a `<title>` element.',
+      failureDescription: 'Document does not have a `<title>` element.',
       helpText: 'Screen reader users use page titles to get an overview of the contents of ' +
           'the page. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/document-title).',

lighthouse-core/audits/accessibility/duplicate-id.js

@@ -21,6 +21,7 @@ class DuplicateId extends AxeAudit {
       category: 'Accessibility',
       name: 'duplicate-id',
       description: '`[id]` attributes on the page are unique.',
+      failureDescription: '`[id]` attributes on the page are not unique.',
       helpText: 'The value of an id attribute must be unique to prevent ' +
           'other instances from being overlooked by assistive technologies. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/duplicate-id).',

lighthouse-core/audits/accessibility/frame-title.js

@@ -21,6 +21,7 @@ class FrameTitle extends AxeAudit {
       category: 'Accessibility',
       name: 'frame-title',
       description: '`<frame>` or `<iframe>` elements have a title.',
+      failureDescription: '`<frame>` or `<iframe>` elements do not have a title.',
       helpText: 'Screen reader users rely on frame titles to describe the contents of frames. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/frame-title).',
       requiredArtifacts: ['Accessibility']

lighthouse-core/audits/accessibility/html-has-lang.js

@@ -21,6 +21,7 @@ class HTMLHasLang extends AxeAudit {
       category: 'Accessibility',
       name: 'html-has-lang',
       description: '`<html>` element has a `[lang]` attribute.',
+      failureDescription: '`<html>` element does not have a `[lang]` attribute.',
       helpText: 'If a page doesn\'t specify a lang attribute, a screen reader assumes ' +
           'that the page is in the default language that the user chose when setting up the ' +
           'screen reader. If the page isn\'t actually in the default language, then the screen ' +

lighthouse-core/audits/accessibility/html-lang-valid.js

@@ -21,6 +21,8 @@ class HTMLLangValid extends AxeAudit {
       category: 'Accessibility',
       name: 'html-lang-valid',
       description: '`<html>` element has a valid value for its `[lang]` attribute.',
+      failureDescription: '`<html>` element does not have a valid value for ' +
+          'its `[lang]` attribute.',
       helpText: 'Specifying a valid [BCP 47 language](https://www.w3.org/International/questions/qa-choosing-language-tags#question) ' +
           'helps screen readers announce text properly. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/valid-lang).',

lighthouse-core/audits/accessibility/image-alt.js

@@ -21,6 +21,7 @@ class ImageAlt extends AxeAudit {
       category: 'Accessibility',
       name: 'image-alt',
       description: 'Image elements have `[alt]` attributes.',
+      failureDescription: 'Image elements do not have `[alt]` attributes.',
       helpText: 'Informative elements should aim for short, descriptive alternate text. ' +
           'Decorative elements can be ignored with an empty alt attribute.' +
           '[Learn more](https://developers.google.com/web/tools/lighthouse/audits/alt-attribute).',

lighthouse-core/audits/accessibility/input-image-alt.js

@@ -21,6 +21,7 @@ class InputImageAlt extends AxeAudit {
       category: 'Accessibility',
       name: 'input-image-alt',
       description: '`<input type="image">` elements have `[alt]` text.',
+      failureDescription: '`<input type="image">` elements do not have `[alt]` text.',
       helpText: 'When an image is being used as an `<input>` button, providing alternative text ' +
           'can help screen reader users understand the purpose of the button. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/input-image-alt).',

lighthouse-core/audits/accessibility/label.js

@@ -21,6 +21,7 @@ class Label extends AxeAudit {
       category: 'Accessibility',
       name: 'label',
       description: 'Form elements have associated labels.',
+      failureDescription: 'Form elements do not have associated labels.',
       helpText: 'Labels ensure that form controls are announced properly by assistive ' +
           'technologies, like screen readers. [Learn ' +
           'more](https://developers.google.com/web/tools/lighthouse/audits/form-labels).',

lighthouse-core/audits/accessibility/layout-table.js

@@ -23,6 +23,8 @@ class LayoutTable extends AxeAudit {
       name: 'layout-table',
       description: 'Presentational `<table>` elements avoid using `<th>`, `<caption>` or the ' +
           '`[summary]` attribute.',
+      failureDescription: 'Presentational `<table>` elements do not avoid using `<th>`, ' +
+          '`<caption>` or the `[summary]` attribute.',
       helpText: 'A table being used for layout purposes should not include data elements, ' +
           'such as the th or caption elements or the summary attribute, because this can ' +
           'create a confusing experience for screen reader users. ' +

lighthouse-core/audits/accessibility/link-name.js

@@ -21,6 +21,7 @@ class LinkName extends AxeAudit {
       category: 'Accessibility',
       name: 'link-name',
       description: 'Links have a discernible name.',
+      failureDescription: 'Links do not have a discernable name.',
       helpText: 'Link text (and alternate text for images, when used as links) that is ' +
           'discernible, unique, and focusable improves the navigation experience for ' +
           'screen reader users. ' +

lighthouse-core/audits/accessibility/list.js

@@ -22,6 +22,8 @@ class List extends AxeAudit {
       name: 'list',
       description: 'Lists contain only `<li>` elements and script supporting elements ' +
           '(`<script>` and `<template>`).',
+      failureDescription: 'Lists do not contain only `<li>` elements and script ' +
+          'supporting elements (`<script>` and `<template>`).',
       helpText: 'Screen readers have a specific way of announcing lists. Ensuring proper list ' +
           'structure aids screen reader output. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/list).',

lighthouse-core/audits/accessibility/listitem.js

@@ -21,6 +21,8 @@ class ListItem extends AxeAudit {
       category: 'Accessibility',
       name: 'listitem',
       description: 'List items (`<li>`) are contained within `<ul>` or `<ol>` parent elements.',
+      failureDescription: 'List items (`<li>`) are not contained within `<ul>` ' +
+          'or `<ol>` parent elements.',
       helpText: 'Screen readers require list items (`<li>`) to be contained within a ' +
           'parent `<ul>` or `<ol>` to be announced properly. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/listitem).',

lighthouse-core/audits/accessibility/meta-refresh.js

@@ -21,6 +21,7 @@ class MetaRefresh extends AxeAudit {
       category: 'Accessibility',
       name: 'meta-refresh',
       description: 'The document does not use `<meta http-equiv="refresh">`.',
+      failureDescription: 'The document uses `<meta http-equiv="refresh">`.',
       helpText: 'Users do not expect a page to refresh automatically, and doing so will move ' +
           'focus back to the top of the page. This may create a frustrating or ' +
           'confusing experience. ' +

lighthouse-core/audits/accessibility/meta-viewport.js

@@ -22,6 +22,8 @@ class MetaViewport extends AxeAudit {
       name: 'meta-viewport',
       description: '`[user-scalable="no"]` is not used in the `<meta name="viewport">` ' +
           'element and the `[maximum-scale]` attribute is not less than 5.',
+      failureDescription: '`[user-scalable="no"]` is used in the `<meta name="viewport">` ' +
+          'element or the `[maximum-scale]` attribute is less than 5.',
       helpText: 'Disabling zooming is problematic for users with low vision who rely on screen ' +
           'magnification to properly see the contents of a web page. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/meta-viewport).',

lighthouse-core/audits/accessibility/object-alt.js

@@ -21,6 +21,7 @@ class ObjectAlt extends AxeAudit {
       category: 'Accessibility',
       name: 'object-alt',
       description: '`<object>` elements have `[alt]` text.',
+      failureDescription: '`<object>` elements do not have `[alt]` text.',
       helpText: 'Screen readers cannot translate non-text content. Adding alt text to `<object>` ' +
           'elements helps screen readers convey meaning to users. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/object-alt).',

lighthouse-core/audits/accessibility/tabindex.js

@@ -21,6 +21,7 @@ class TabIndex extends AxeAudit {
       category: 'Accessibility',
       name: 'tabindex',
       description: 'No element has a `[tabindex]` value greater than 0.',
+      failureDescription: 'Some elements have a `[tabindex]` value greater than 0.',
       helpText: 'A value greater than 0 implies an explicit navigation ordering. ' +
           'Although technically valid, this often creates frustrating experiences ' +
           'for users who rely on assistive technologies. [Learn more](https://developers.google.com/web/tools/lighthouse/audits/tabindex).',

lighthouse-core/audits/accessibility/td-headers-attr.js

@@ -23,6 +23,8 @@ class TDHeadersAttr extends AxeAudit {
       name: 'td-headers-attr',
       description: 'Cells in a `<table>` element that use the `[headers]` attribute only refer ' +
           'to other cells of that same table.',
+      failureDescription: 'Cells in a `<table>` element that use the `[headers]` ' +
+          'attribute refers to other cells of that same table.',
       helpText: 'Screen readers have features to make navigating tables easier. Ensuring `<td>` ' +
           'cells using the `[headers]` attribute only refer to other cells in the same table may ' +
           'improve the experience for screen reader users. ' +

lighthouse-core/audits/accessibility/th-has-data-cells.js

@@ -22,6 +22,8 @@ class THHasDataCells extends AxeAudit {
       name: 'th-has-data-cells',
       description: '`<th>` elements and elements with `[role="columnheader"/"rowheader"]` have ' +
           'data cells they describe.',
+      failureDescription: '`<th>` elements and elements with ' +
+          '`[role="columnheader"/"rowheader"]` do not have data cells they describe.',
       helpText: 'Screen readers have features to make navigating tables easier. Ensuring table ' +
           'headers always refer to some set of cells may improve the experience for screen ' +
           'reader users. ' +

lighthouse-core/audits/accessibility/valid-lang.js

@@ -21,6 +21,7 @@ class ValidLang extends AxeAudit {
       category: 'Accessibility',
       name: 'valid-lang',
       description: '`[lang]` attributes have a valid value.',
+      failureDescription: '`[lang]` attributes do not have a valid value.',
       helpText: 'Specifying a valid [BCP 47 language](https://www.w3.org/International/questions/qa-choosing-language-tags#question) ' +
           'on elements helps ensure that text is pronounced correctly by a screen reader. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/valid-lang).',

lighthouse-core/audits/accessibility/video-caption.js

@@ -21,6 +21,8 @@ class VideoCaption extends AxeAudit {
       category: 'Accessibility',
       name: 'video-caption',
       description: '`<video>` elements contain a `<track>` element with `[kind="captions"]`.',
+      failureDescription: '`<video>` elements do not contain a `<track>` element ' +
+          'with `[kind="captions"]`.',
       helpText: 'When a video provides a caption it is easier for deaf and hearing impaired ' +
           'users to access its information. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/video-caption).',

lighthouse-core/audits/accessibility/video-description.js

@@ -21,6 +21,8 @@ class VideoDescription extends AxeAudit {
       category: 'Accessibility',
       name: 'video-description',
       description: '`<video>` elements contain a `<track>` element with `[kind="description"]`.',
+      failureDescription: '`<video>` elements do not contain a `<track>` element with ' +
+          '`[kind="description"]`.',
       helpText: 'Audio descriptions provide relevant information for videos that dialogue ' +
           'cannot, such as facial expressions and scenes. ' +
           '[Learn more](https://dequeuniversity.com/rules/axe/1.1/video-description).',

lighthouse-core/audits/audit.js

@@ -115,7 +115,12 @@ class Audit {
     if (displayValue === score) {
       displayValue = '';
     }
-
+    let auditDescription = audit.meta.description;
+    if (audit.meta.failureDescription) {
+      if (!score || (typeof score === 'number' && score < 100)) {
+        auditDescription = audit.meta.failureDescription;
+      }
+    }
     return {
       score,
       displayValue: `${displayValue}`,
@@ -129,7 +134,7 @@ class Audit {
       manual: audit.meta.manual,
       name: audit.meta.name,
       category: audit.meta.category,
-      description: audit.meta.description,
+      description: auditDescription,
       helpText: audit.meta.helpText,
       details: result.details,
     };