Skip to content

Commit

Permalink
core(category): add manualDescription (GoogleChrome#5100)
Browse files Browse the repository at this point in the history
  • Loading branch information
@patrickhulce @kdzwinel
patrickhulce authored and kdzwinel committed Aug 16, 2018
1 parent 79f6c2c commit 662ca55
Show file tree
Hide file tree
Showing 6 changed files with 61 additions and 94 deletions.
19 changes: 10 additions & 9 deletions lighthouse-core/config/config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,23 +51,24 @@ function validateCategories(categories, audits, groups) {
return;
}

const auditIds = audits.map(audit => audit.implementation.meta.name);
Object.keys(categories).forEach(categoryId => {
categories[categoryId].audits.forEach((audit, index) => {
if (!audit.id) {
categories[categoryId].audits.forEach((auditRef, index) => {
if (!auditRef.id) {
throw new Error(`missing an audit id at ${categoryId}[${index}]`);
}

if (!auditIds.includes(audit.id)) {
throw new Error(`could not find ${audit.id} audit for category ${categoryId}`);
const audit = audits.find(a => a.implementation.meta.name === auditRef.id);
if (!audit) {
throw new Error(`could not find ${auditRef.id} audit for category ${categoryId}`);
}

if (categoryId === 'accessibility' && !audit.group) {
throw new Error(`${audit.id} accessibility audit does not have a group`);
const auditImpl = audit.implementation;
if (categoryId === 'accessibility' && !auditRef.group && !auditImpl.meta.manual) {
throw new Error(`${auditRef.id} accessibility audit does not have a group`);
}

if (audit.group && !groups[audit.group]) {
throw new Error(`${audit.id} references unknown group ${audit.group}`);
if (auditRef.group && !groups[auditRef.group]) {
throw new Error(`${auditRef.id} references unknown group ${auditRef.group}`);
}
});
});
Expand Down
52 changes: 23 additions & 29 deletions lighthouse-core/config/default-config.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -232,16 +232,6 @@ module.exports = {
title: 'Meta Tags Used Properly',
description: 'These are opportunities to improve the user experience of your site.',
},
'manual-a11y-checks': {
title: 'Additional items to manually check',
description: 'These items address areas which an automated testing tool cannot cover. Learn more in our guide on [conducting an accessibility review](https://developers.google.com/web/fundamentals/accessibility/how-to-review).',
},
'manual-pwa-checks': {
title: 'Additional items to manually check',
description: 'These checks are required by the baseline ' +
'[PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist) but are ' +
'not automatically checked by Lighthouse. They do not affect your score but it\'s important that you verify them manually.',
},
'seo-mobile': {
title: 'Mobile Friendly',
description: 'Make sure your pages are mobile friendly so users don’t have to pinch or zoom ' +
Expand All @@ -255,10 +245,6 @@ module.exports = {
title: 'Crawling and Indexing',
description: 'To appear in search results, crawlers need access to your app.',
},
'manual-seo-checks': {
title: 'Additional items to manually check',
description: 'Run these additional validators on your site to check additional SEO best practices.',
},
},
categories: {
'performance': {
Expand Down Expand Up @@ -302,6 +288,9 @@ module.exports = {
'pwa': {
name: 'Progressive Web App',
description: 'These checks validate the aspects of a Progressive Web App, as specified by the baseline [PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist).',
manualDescription: 'These checks are required by the baseline ' +
'[PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist) but are ' +
'not automatically checked by Lighthouse. They do not affect your score but it\'s important that you verify them manually.',
audits: [
{id: 'service-worker', weight: 1},
{id: 'works-offline', weight: 1},
Expand All @@ -314,14 +303,16 @@ module.exports = {
{id: 'themed-omnibox', weight: 1},
{id: 'viewport', weight: 1},
{id: 'content-width', weight: 1},
{id: 'pwa-cross-browser', weight: 0, group: 'manual-pwa-checks'},
{id: 'pwa-page-transitions', weight: 0, group: 'manual-pwa-checks'},
{id: 'pwa-each-page-has-url', weight: 0, group: 'manual-pwa-checks'},
// Manual audits
{id: 'pwa-cross-browser', weight: 0},
{id: 'pwa-page-transitions', weight: 0},
{id: 'pwa-each-page-has-url', weight: 0},
],
},
'accessibility': {
name: 'Accessibility',
description: 'These checks highlight opportunities to [improve the accessibility of your web app](https://developers.google.com/web/fundamentals/accessibility). Only a subset of accessibility issues can be automatically detected so manual testing is also encouraged.',
manualDescription: 'These items address areas which an automated testing tool cannot cover. Learn more in our guide on [conducting an accessibility review](https://developers.google.com/web/fundamentals/accessibility/how-to-review).',
audits: [
{id: 'accesskeys', weight: 1, group: 'a11y-correct-attributes'},
{id: 'aria-allowed-attr', weight: 3, group: 'a11y-aria'},
Expand Down Expand Up @@ -358,16 +349,17 @@ module.exports = {
{id: 'valid-lang', weight: 1, group: 'a11y-language'},
{id: 'video-caption', weight: 4, group: 'a11y-describe-contents'},
{id: 'video-description', weight: 3, group: 'a11y-describe-contents'},
{id: 'logical-tab-order', weight: 0, group: 'manual-a11y-checks'},
{id: 'focusable-controls', weight: 0, group: 'manual-a11y-checks'},
{id: 'managed-focus', weight: 0, group: 'manual-a11y-checks'},
{id: 'focus-traps', weight: 0, group: 'manual-a11y-checks'},
{id: 'custom-controls-labels', weight: 0, group: 'manual-a11y-checks'},
{id: 'custom-controls-roles', weight: 0, group: 'manual-a11y-checks'},
{id: 'visual-order-follows-dom', weight: 0, group: 'manual-a11y-checks'},
{id: 'offscreen-content-hidden', weight: 0, group: 'manual-a11y-checks'},
{id: 'heading-levels', weight: 0, group: 'manual-a11y-checks'},
{id: 'use-landmarks', weight: 0, group: 'manual-a11y-checks'},
// Manual audits
{id: 'logical-tab-order', weight: 0},
{id: 'focusable-controls', weight: 0},
{id: 'managed-focus', weight: 0},
{id: 'focus-traps', weight: 0},
{id: 'custom-controls-labels', weight: 0},
{id: 'custom-controls-roles', weight: 0},
{id: 'visual-order-follows-dom', weight: 0},
{id: 'offscreen-content-hidden', weight: 0},
{id: 'heading-levels', weight: 0},
{id: 'use-landmarks', weight: 0},
],
},
'best-practices': {
Expand Down Expand Up @@ -397,6 +389,7 @@ module.exports = {
description: 'These checks ensure that your page is optimized for search engine results ranking. ' +
'There are additional factors Lighthouse does not check that may affect your search ranking. ' +
'[Learn more](https://support.google.com/webmasters/answer/35769).',
manualDescription: 'Run these additional validators on your site to check additional SEO best practices.',
audits: [
{id: 'viewport', weight: 1, group: 'seo-mobile'},
{id: 'document-title', weight: 1, group: 'seo-content'},
Expand All @@ -409,8 +402,9 @@ module.exports = {
{id: 'canonical', weight: 1, group: 'seo-content'},
{id: 'font-size', weight: 1, group: 'seo-mobile'},
{id: 'plugins', weight: 1, group: 'seo-content'},
{id: 'mobile-friendly', weight: 0, group: 'manual-seo-checks'},
{id: 'structured-data', weight: 0, group: 'manual-seo-checks'},
// Manual audits
{id: 'mobile-friendly', weight: 0},
{id: 'structured-data', weight: 0},
],
},
},
Expand Down
21 changes: 7 additions & 14 deletions lighthouse-core/report/html/renderer/category-renderer.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -196,21 +196,14 @@ class CategoryRenderer {

/**
* @param {!Array<!ReportRenderer.AuditJSON>} manualAudits
* @param {!Object<string, !ReportRenderer.GroupJSON>} groupDefinitions
* @param {string} manualDescription
* @param {!Element} element Parent container to add the manual audits to.
*/
_renderManualAudits(manualAudits, groupDefinitions, element) {
// While we could support rendering multiple groups of manual audits, it doesn't
// seem desirable for UX or renderer complexity. So we'll throw.
const groupsIds = new Set(manualAudits.map(a => a.group));
/* eslint-disable no-console */
console.assert(groupsIds.size <= 1, 'More than 1 manual audit group found.');
console.assert(!groupsIds.has(undefined), 'Some manual audits don\'t belong to a group');
/* eslint-enable no-console */
if (!groupsIds.size) return;

const groupId = /** @type {string} */ (Array.from(groupsIds)[0]);
const auditGroupElem = this.renderAuditGroup(groupDefinitions[groupId], {expandable: true});
_renderManualAudits(manualAudits, manualDescription, element) {
if (!manualAudits.length) return;

const group = {title: 'Additional items to manually check', description: manualDescription};
const auditGroupElem = this.renderAuditGroup(group, {expandable: true});
auditGroupElem.classList.add('lh-audit-group--manual');

manualAudits.forEach(audit => {
Expand Down Expand Up @@ -354,7 +347,7 @@ class CategoryRenderer {
}

// Render manual audits after passing.
this._renderManualAudits(manualAudits, groupDefinitions, element);
this._renderManualAudits(manualAudits, category.manualDescription, element);

return element;
}
Expand Down
1 change: 1 addition & 0 deletions lighthouse-core/report/html/renderer/report-renderer.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -239,6 +239,7 @@ ReportRenderer.AuditJSON; // eslint-disable-line no-unused-expressions
* id: string,
* score: number,
* description: string,
* manualDescription: string,
* audits: !Array<!ReportRenderer.AuditJSON>
* }}
*/
Expand Down
60 changes: 18 additions & 42 deletions lighthouse-core/test/results/sample_v2.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4728,6 +4728,7 @@
{
"name": "Progressive Web App",
"description": "These checks validate the aspects of a Progressive Web App, as specified by the baseline [PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist).",
"manualDescription": "These checks are required by the baseline [PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist) but are not automatically checked by Lighthouse. They do not affect your score but it's important that you verify them manually.",
"audits": [
{
"id": "service-worker",
Expand Down Expand Up @@ -4775,18 +4776,15 @@
},
{
"id": "pwa-cross-browser",
"weight": 0,
"group": "manual-pwa-checks"
"weight": 0
},
{
"id": "pwa-page-transitions",
"weight": 0,
"group": "manual-pwa-checks"
"weight": 0
},
{
"id": "pwa-each-page-has-url",
"weight": 0,
"group": "manual-pwa-checks"
"weight": 0
}
],
"id": "pwa",
Expand All @@ -4795,6 +4793,7 @@
{
"name": "Accessibility",
"description": "These checks highlight opportunities to [improve the accessibility of your web app](https://developers.google.com/web/fundamentals/accessibility). Only a subset of accessibility issues can be automatically detected so manual testing is also encouraged.",
"manualDescription": "These items address areas which an automated testing tool cannot cover. Learn more in our guide on [conducting an accessibility review](https://developers.google.com/web/fundamentals/accessibility/how-to-review).",
"audits": [
{
"id": "accesskeys",
Expand Down Expand Up @@ -4973,53 +4972,43 @@
},
{
"id": "logical-tab-order",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
},
{
"id": "focusable-controls",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
},
{
"id": "managed-focus",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
},
{
"id": "focus-traps",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
},
{
"id": "custom-controls-labels",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
},
{
"id": "custom-controls-roles",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
},
{
"id": "visual-order-follows-dom",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
},
{
"id": "offscreen-content-hidden",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
},
{
"id": "heading-levels",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
},
{
"id": "use-landmarks",
"weight": 0,
"group": "manual-a11y-checks"
"weight": 0
}
],
"id": "accessibility",
Expand Down Expand Up @@ -5100,6 +5089,7 @@
{
"name": "SEO",
"description": "These checks ensure that your page is optimized for search engine results ranking. There are additional factors Lighthouse does not check that may affect your search ranking. [Learn more](https://support.google.com/webmasters/answer/35769).",
"manualDescription": "Run these additional validators on your site to check additional SEO best practices.",
"audits": [
{
"id": "viewport",
Expand Down Expand Up @@ -5158,13 +5148,11 @@
},
{
"id": "mobile-friendly",
"weight": 0,
"group": "manual-seo-checks"
"weight": 0
},
{
"id": "structured-data",
"weight": 0,
"group": "manual-seo-checks"
"weight": 0
}
],
"id": "seo",
Expand Down Expand Up @@ -5216,14 +5204,6 @@
"title": "Meta Tags Used Properly",
"description": "These are opportunities to improve the user experience of your site."
},
"manual-a11y-checks": {
"title": "Additional items to manually check",
"description": "These items address areas which an automated testing tool cannot cover. Learn more in our guide on [conducting an accessibility review](https://developers.google.com/web/fundamentals/accessibility/how-to-review)."
},
"manual-pwa-checks": {
"title": "Additional items to manually check",
"description": "These checks are required by the baseline [PWA Checklist](https://developers.google.com/web/progressive-web-apps/checklist) but are not automatically checked by Lighthouse. They do not affect your score but it's important that you verify them manually."
},
"seo-mobile": {
"title": "Mobile Friendly",
"description": "Make sure your pages are mobile friendly so users don’t have to pinch or zoom in order to read the content pages. [Learn more](https://developers.google.com/search/mobile-sites/)."
Expand All @@ -5235,10 +5215,6 @@
"seo-crawl": {
"title": "Crawling and Indexing",
"description": "To appear in search results, crawlers need access to your app."
},
"manual-seo-checks": {
"title": "Additional items to manually check",
"description": "Run these additional validators on your site to check additional SEO best practices."
}
}
}
2 changes: 2 additions & 0 deletions typings/lhr.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ declare global {
name: string;
/** A more detailed description of the category and its importance. */
description: string;
/** A description for the manual audits in the category. */
manualDescription?: string;
/** The overall score of the category, the weighted average of all its audits. */
score: number;
/** An array of references to all the audit members of this category. */
Expand Down

0 comments on commit 662ca55

Please sign in to comment.