feat: refine the markdown

package.json

@@ -74,7 +74,6 @@
         "http-server": "^0.12.1",
         "inversify": "^5.0.1",
         "lodash": "^4.17.15",
-        "markdown-table": "^2.0.0",
         "puppeteer-core": "^2.1.1",
         "reflect-metadata": "^0.1.13",
         "serve-static": "^1.14.1",

src/__snapshots__/check-result-markdown-builder.spec.ts.snap

@@ -0,0 +1,38 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`CheckResultMarkdownBuilder congratsContent 1`] = `
+"## Accessibility Automated Checks Results
+The Accessibility Insights Service ran a set of automated checks to help find some of the most common accessibility issues. The best way to evaluate web accessibility compliance is to complete a [WCAG 2.1 compliance assessment](http://aka.ms/AccessibilityInsights).
+###### DETAILS
+### ![Accessibility Insights](https://accessibilityinsights.io/img/a11yinsights-blue.svg) Accessibility Insights: All applicable checks passed
+* **1 check(s) passed**, and 1 were not applicable
+* Download the **Accessibility Insights** artifact to view the detailed results of these checks.
+---
+This scan used [axe-core 1.0.1](https://github.com/dequelabs/axe-core/releases/tag/v1.0.1) with the following browsers: browserSpec."
+`;
+
+exports[`CheckResultMarkdownBuilder errorContent 1`] = `
+"## Accessibility Automated Checks Results
+The Accessibility Insights Service ran a set of automated checks to help find some of the most common accessibility issues. The best way to evaluate web accessibility compliance is to complete a [WCAG 2.1 compliance assessment](http://aka.ms/AccessibilityInsights).
+###### DETAILS
+### ![Accessibility Insights](https://accessibilityinsights.io/img/a11yinsights-blue.svg) Accessibility Insights: Something went wrong
+You can review the log to troubleshoot the issue. Fix it and re-run the workflow to run the automated accessibility checks again.
+
+---
+"
+`;
+
+exports[`CheckResultMarkdownBuilder getFailureDetails 1`] = `
+"## Accessibility Automated Checks Results
+The Accessibility Insights Service ran a set of automated checks to help find some of the most common accessibility issues. The best way to evaluate web accessibility compliance is to complete a [WCAG 2.1 compliance assessment](http://aka.ms/AccessibilityInsights).
+###### DETAILS
+### ![Accessibility Insights](https://accessibilityinsights.io/img/a11yinsights-blue.svg) Accessibility Insights
+* **2 check(s) failed**, 1 passed, and 1 were not applicable
+* Download the **Accessibility Insights** artifact to view the detailed results of these checks.
+#### Failed instances
+* **2 × color-contrast**:  color-contrast is important
+* **3 × duplicate-id**:  duplicate-id is even more important
+
+---
+This scan used [axe-core 1.0.1](https://github.com/dequelabs/axe-core/releases/tag/v1.0.1) with the following browsers: browserSpec."
+`;

src/axe-markdown-convertor.spec.ts

@@ -4,16 +4,20 @@
 import 'reflect-metadata';
 
 import { AxeScanResults } from 'accessibility-insights-scan';
+import { IMock, It, Mock, Times } from 'typemoq';
 
 import { AxeMarkdownConvertor } from './axe-markdown-convertor';
+import { CheckResultMarkdownBuilder } from './check-result-markdown-builder';
 
 // tslint:disable: no-unsafe-any no-null-keyword no-object-literal-type-assertion
 describe(AxeMarkdownConvertor, () => {
     let axeMarkdownConvertor: AxeMarkdownConvertor;
+    let markdownBuilderMock: IMock<CheckResultMarkdownBuilder>;
     let axeScanResults: AxeScanResults;
 
     beforeEach(() => {
-        axeMarkdownConvertor = new AxeMarkdownConvertor();
+        markdownBuilderMock = Mock.ofType(CheckResultMarkdownBuilder);
+        axeMarkdownConvertor = new AxeMarkdownConvertor(markdownBuilderMock.object);
         axeScanResults = {
             results: {
                 violations: [],
@@ -27,9 +31,11 @@ describe(AxeMarkdownConvertor, () => {
 
     describe('convert', () => {
         it('returns congrats message when no failure found', async () => {
-            const res = axeMarkdownConvertor.convert(axeScanResults);
+            markdownBuilderMock.setup(mm => mm.congratsContent(axeScanResults)).verifiable(Times.once());
 
-            expect(res).toMatchSnapshot();
+            axeMarkdownConvertor.convert(axeScanResults);
+
+            markdownBuilderMock.verifyAll();
         });
 
         it('returns failure details', async () => {
@@ -47,10 +53,19 @@ describe(AxeMarkdownConvertor, () => {
                 passes: [{ html: 'passed' }],
                 inapplicable: [{ html: 'inapplicable' }],
             } as any;
+            markdownBuilderMock.setup(mm => mm.failureDetails(axeScanResults)).verifiable(Times.once());
 
-            const res = axeMarkdownConvertor.convert(axeScanResults);
+            axeMarkdownConvertor.convert(axeScanResults);
 
-            expect(res).toMatchSnapshot();
+            markdownBuilderMock.verifyAll();
         });
     });
+
+    it('getErrorMarkdown', () => {
+        markdownBuilderMock.setup(mm => mm.errorContent()).verifiable(Times.once());
+
+        axeMarkdownConvertor.getErrorMarkdown();
+
+        markdownBuilderMock.verifyAll();
+    });
 });

src/axe-markdown-convertor.ts

@@ -1,48 +1,24 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 import { AxeScanResults } from 'accessibility-insights-scan';
-import { stripIndent } from 'common-tags';
-import { injectable } from 'inversify';
+import { inject, injectable } from 'inversify';
 import { isEmpty } from 'lodash';
-import * as table from 'markdown-table';
 
-import { toolName } from './content/strings';
+import { CheckResultMarkdownBuilder } from './check-result-markdown-builder';
 
 @injectable()
 export class AxeMarkdownConvertor {
+    constructor(@inject(CheckResultMarkdownBuilder) private readonly checkResultMarkdownBuilder: CheckResultMarkdownBuilder) {}
+
     public convert(axeScanResults: AxeScanResults): string {
         if (isEmpty(axeScanResults.results.violations)) {
-            return this.getCongratsText();
+            return this.checkResultMarkdownBuilder.congratsContent(axeScanResults);
+        } else {
+            return this.checkResultMarkdownBuilder.failureDetails(axeScanResults);
         }
-
-        return this.getFailureDetails(axeScanResults);
-    }
-
-    private getFailureDetails(axeScanResults: AxeScanResults): string {
-        return stripIndent`
-        FAILED RULES:
-
-${this.getFailedRuleTable(axeScanResults)}
-        `;
     }
 
-    private getCongratsText(): string {
-        return stripIndent`
-            Congratulations!
-            No failed automated checks were found.
-        `;
-    }
-
-    private getFailedRuleTable(axeScanResults: AxeScanResults): string {
-        const tableContent: string[][] = [['Rule', 'Count']];
-
-        const violations = axeScanResults.results.violations;
-
-        violations.forEach(violation => {
-            const row: string[] = [violation.id, violation.nodes.length.toString()];
-            tableContent.push(row);
-        });
-
-        return table(tableContent);
+    public getErrorMarkdown(): string {
+        return this.checkResultMarkdownBuilder.errorContent();
     }
 }

src/check-result-markdown-builder.spec.ts

@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+// tslint:disable:no-import-side-effect no-any
+import 'reflect-metadata';
+
+import { AxeScanResults } from 'accessibility-insights-scan';
+
+import { CheckResultMarkdownBuilder } from './check-result-markdown-builder';
+
+// tslint:disable: no-unsafe-any no-null-keyword no-object-literal-type-assertion
+describe(CheckResultMarkdownBuilder, () => {
+    let checkResultMarkdownBuilder: CheckResultMarkdownBuilder;
+    let axeScanResults: AxeScanResults;
+
+    beforeEach(() => {
+        checkResultMarkdownBuilder = new CheckResultMarkdownBuilder();
+    });
+
+    it('getFailureDetails', () => {
+        axeScanResults = {
+            results: {
+                testEngine: {
+                    version: '1.0.1',
+                },
+                violations: [
+                    {
+                        id: 'color-contrast',
+                        nodes: [{ html: 'html1' }, { html: 'html2' }],
+                        description: 'color-contrast is important',
+                    },
+                    {
+                        id: 'duplicate-id',
+                        nodes: [{ html: 'html3' }, { html: 'html4' }, { html: 'html5' }],
+                        description: 'duplicate-id is even more important',
+                    },
+                ],
+                passes: [{ html: 'passed' }],
+                inapplicable: [{ html: 'inapplicable' }],
+            },
+            browserSpec: 'browserSpec',
+        } as any;
+
+        expect(checkResultMarkdownBuilder.failureDetails(axeScanResults)).toMatchSnapshot();
+    });
+
+    it('errorContent', () => {
+        expect(checkResultMarkdownBuilder.errorContent()).toMatchSnapshot();
+    });
+
+    it('congratsContent', () => {
+        axeScanResults = {
+            browserSpec: 'browserSpec',
+            results: {
+                testEngine: {
+                    version: '1.0.1',
+                },
+                violations: [],
+                passes: [{ html: 'passed' }],
+                inapplicable: [{ html: 'inapplicable' }],
+            },
+        } as any;
+
+        const res = checkResultMarkdownBuilder.congratsContent(axeScanResults);
+
+        expect(res).toMatchSnapshot();
+    });
+});

src/check-result-markdown-builder.ts

@@ -0,0 +1,110 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+import { AxeScanResults } from 'accessibility-insights-scan';
+import * as axe from 'axe-core';
+import { injectable } from 'inversify';
+
+import { brand } from './content/strings';
+import { bold, footerSeparator, heading, link, listItem, productTitle, sectionSeparator } from './utils/markdown-formatter';
+
+@injectable()
+export class CheckResultMarkdownBuilder {
+    public failureDetails = (axeScanResults: AxeScanResults) => {
+        const failedRulesList = axeScanResults.results.violations.map((rule: axe.Result) => {
+            return [this.failedRuleListItem(rule.nodes.length, rule.id, rule.description),  sectionSeparator()].join('');
+        });
+        const sections = [
+            this.failureSummary(
+                axeScanResults.results.violations.length,
+                axeScanResults.results.passes.length,
+                axeScanResults.results.inapplicable.length,
+            ),
+            sectionSeparator(),
+
+            `${heading('Failed instances', 4)}`,
+            sectionSeparator(),
+        ];
+
+        return this.scanResultDetails(sections.concat(failedRulesList).join(''), this.scanResultFooter(axeScanResults));
+    };
+
+    public errorContent = (): string => {
+        const lines = [
+            heading(`${productTitle()}: Something went wrong`, 3),
+            sectionSeparator(),
+
+            `You can review the log to troubleshoot the issue. Fix it and re-run the workflow to run the automated accessibility checks again.`,
+            sectionSeparator(),
+        ];
+
+        return this.scanResultDetails(lines.join(''));
+    };
+
+    public congratsContent = (axeScanResults: AxeScanResults) => {
+        const passed = axeScanResults.results.passes.length;
+        const inapplicable = axeScanResults.results.inapplicable.length;
+        const lines = [
+            heading(`${productTitle()}: All applicable checks passed`, 3),
+            sectionSeparator(),
+
+            listItem(`${bold(`${passed} check(s) passed`)}, and ${inapplicable} were not applicable`),
+            sectionSeparator(),
+
+            listItem(`Download the ${bold(brand)} artifact to view the detailed results of these checks.`),
+        ];
+
+        return this.scanResultDetails(lines.join(''), this.scanResultFooter(axeScanResults));
+    };
+
+    private readonly scanResultDetails = (scanResult: string, footer?: string): string => {
+        const lines = [
+            heading('Accessibility Automated Checks Results', 2),
+            sectionSeparator(),
+
+            `The Accessibility Insights Service ran a set of automated checks to help find some of the most common accessibility issues. The best way to evaluate web accessibility compliance is to complete a ${link(
+                // tslint:disable-next-line: no-http-string
+                'http://aka.ms/AccessibilityInsights',
+                'WCAG 2.1 compliance assessment',
+            )}.`,
+            sectionSeparator(),
+
+            heading('DETAILS', 6),
+            sectionSeparator(),
+
+            scanResult,
+            sectionSeparator(),
+
+            footerSeparator(),
+            sectionSeparator(),
+
+            footer,
+        ];
+
+        return lines.join('');
+    };
+
+    private readonly scanResultFooter = (axeScanResults: AxeScanResults): string => {
+        const axeVersion = axeScanResults.results.testEngine.version;
+        const axeCoreUrl = `https://github.com/dequelabs/axe-core/releases/tag/v${axeVersion}`;
+        const axeLink = link(axeCoreUrl, `axe-core ${axeVersion}`);
+
+        return `This scan used ${axeLink} with the following browsers: ${axeScanResults.browserSpec}.`;
+    };
+
+    private readonly failureSummary = (failed: number, passed: number, inapplicable: number) => {
+        const lines = [
+            heading(`${productTitle()}`, 3),
+            sectionSeparator(),
+
+            listItem(`${bold(`${failed} check(s) failed`)}, ${passed} passed, and ${inapplicable} were not applicable`),
+            sectionSeparator(),
+            listItem(`Download the ${bold(brand)} artifact to view the detailed results of these checks.`),
+        ];
+
+        return lines.join('');
+    };
+
+    private readonly failedRuleListItem = (failureCount: number, ruleId: string, description: string) => {
+        return listItem(`${bold(`${failureCount} × ${ruleId}`)}:  ${description}`);
+    };
+}

src/check-run/check-run-creator.spec.ts

@@ -97,7 +97,10 @@ describe(CheckRunCreator, () => {
         };
 
         setupMocksForCreateCheck();
-
+        convertorMock
+            .setup(cm => cm.getErrorMarkdown())
+            .returns(() => message)
+            .verifiable(Times.once());
         updateCheckMock.setup(um => um(expectedParam)).verifiable(Times.once());
 
         await checkRunCreator.createRun();

src/check-run/check-run-creator.ts

@@ -62,8 +62,7 @@ export class CheckRunCreator {
                 title: A11Y_REPORT_TITLE,
                 summary: `Unable to scan`,
                 annotations: [],
-                text: stripIndent`
-                ${message}`,
+                text: this.axeMarkdownConvertor.getErrorMarkdown(),
             },
         });
     }

src/content/strings.ts

@@ -4,3 +4,4 @@ export const brand = 'Accessibility Insights';
 export const title = `${brand} Action`;
 export const productName = title;
 export const toolName = title;
+export const brandLogoImg = 'https://accessibilityinsights.io/img/a11yinsights-blue.svg';