docs: add docs, test for audio, video elements (#41)

README.md

@@ -14,6 +14,7 @@ Automated Accessibility Testing Libraries and Tools ([@sa11y packages](https://w
 
 
 - [Docs](#docs)
+  - [References](#references)
 - [Packages](#packages)
   - [Jest integration](#jest-integration)
   - [WDIO integration](#wdio-integration)
@@ -39,6 +40,12 @@ Automated Accessibility Testing Libraries and Tools ([@sa11y packages](https://w
 -   [Changelog](./CHANGELOG.md)
 -   [LICENSE](./LICENSE.txt)
 
+### References
+
+-   [Automated Accessibility Testing with sa11y | Salesforce Developers Blog](https://developer.salesforce.com/blogs/2020/10/automated-accessibility-testing-with-sa11y.html)
+-   [Accessibility Overview - Lightning Design System](https://www.lightningdesignsystem.com/accessibility/overview/)
+-   [Get Started with Web Accessibility | Salesforce Trailhead](https://trailhead.salesforce.com/en/content/learn/trails/get-started-with-web-accessibility)
+
 ## Packages
 
 This repo contains the following packages for automated accessibility testing:

package.json

@@ -1,6 +1,6 @@
 {
     "name": "sa11y-monorepo",
-    "version": "0.3.2-beta",
+    "version": "0.3.3-beta",
     "private": true,
     "description": "Salesforce Accessibility Automated Testing Libraries and Tools (@sa11y packages)",
     "license": "BSD-3-Clause",
@@ -21,30 +21,31 @@
         "build:clean": "tsc --build --clean && rimraf packages/**/dist && yarn build:ci",
         "build:watch": "tsc --build --watch",
         "commit": "! git diff --cached --exit-code && lint-staged && git-cz",
-        "install:clean": "lerna clean --yes && yarn install",
+        "install:clean": "lerna clean --yes && rimraf yarn.lock && yarn install",
+        "install:update": "yarn audit; yarn upgrade-interactive --latest && yarn install:clean && yarn test:clean",
         "lint": "eslint . --ext ts,js,md",
-        "lint:all": "tsc --noEmit && yarn lint && yarn lint:lockfile && yarn lint:deps && yarn lint:depgraph && yarn lint:version",
+        "lint:all": "tsc --noEmit && yarn lint && yarn lint:lockfile && yarn lint:deps && yarn lint:depgraph",
         "lint:deps": "lerna exec depcheck",
         "lint:depgraph": "yarn pkg:depgraph && git diff --quiet docs/sa11y_dependency_graph.svg || echo 'Dependency graph needs to be updated!'",
         "lint:fix": "yarn lint --fix",
         "lint:lockfile": "lockfile-lint --path yarn.lock --allowed-hosts registry.yarnpkg.com --validate-https",
         "lint:staged": "lint-staged",
-        "lint:version": "yarn lerna exec --since master vertioner",
+        "lint:version": "yarn lerna exec --stream --no-bail --since master vertioner",
         "lint:watch": "esw --watch --changed --color --ext .js,.ts",
+        "pkg:diff": "yarn lerna exec --stream --no-bail 'git diff --relative --stat origin/master'",
         "pkg:list": "lerna list --long --all --toposort",
         "pkg:deps": "yarn pkg:list --graph",
         "pkg:depgraph": "yarn package-dependency-graph --graphviz --svg docs/sa11y_dependency_graph.svg",
         "release:changelog": "conventional-changelog --infile CHANGELOG.md --same-file --preset angular --output-unreleased",
-        "release:version": "yarn lerna version --no-push --no-git-tag-version && yarn build:clean",
+        "release:version": "yarn pkg:diff; yarn lerna version --no-push --no-git-tag-version && yarn build:clean",
         "release:version:auto": "yarn release:version --conventional-commits --no-changelog && yarn build:clean",
         "release:publish": "yarn test:clean && yarn lerna publish from-package",
         "test": "jest --coverage",
         "test:ci": "yarn lint:all && yarn test --ci && yarn test:wdio",
         "test:clean": "yarn build:clean && yarn test:ci",
         "test:debug": "node --inspect node_modules/.bin/jest --runInBand --watch",
         "test:watch": "yarn test --watch",
-        "test:wdio": "yarn workspace @sa11y/wdio test && yarn workspace @sa11y/browser-lib test ",
-        "update": "yarn audit; yarn upgrade-interactive --latest && yarn test:clean"
+        "test:wdio": "yarn workspace @sa11y/wdio test && yarn workspace @sa11y/browser-lib test "
     },
     "config": {
         "commitizen": {
@@ -60,44 +61,44 @@
         }
     },
     "devDependencies": {
-        "@babel/core": "^7.11.6",
-        "@babel/preset-env": "^7.11.5",
-        "@babel/preset-typescript": "^7.10.4",
+        "@babel/core": "^7.12.1",
+        "@babel/preset-env": "^7.12.1",
+        "@babel/preset-typescript": "^7.12.1",
         "@commitlint/cli": "11.0.0",
         "@commitlint/config-conventional": "11.0.0",
         "@types/jest": "^26.0.14",
-        "@types/node": "^14.11.2",
-        "@typescript-eslint/eslint-plugin": "^4.2.0",
-        "@typescript-eslint/parser": "^4.2.0",
-        "@wdio/cli": "^6.5.2",
-        "@wdio/local-runner": "^6.5.2",
-        "@wdio/mocha-framework": "^6.5.0",
-        "@wdio/spec-reporter": "^6.4.7",
-        "@wdio/sync": "^6.5.0",
-        "babel-jest": "^26.3.0",
-        "chromedriver": "^85.0.1",
-        "codecov": "^3.7.2",
+        "@types/node": "^14.11.10",
+        "@typescript-eslint/eslint-plugin": "^4.4.1",
+        "@typescript-eslint/parser": "^4.4.1",
+        "@wdio/cli": "^6.6.6",
+        "@wdio/local-runner": "^6.6.6",
+        "@wdio/mocha-framework": "^6.6.6",
+        "@wdio/spec-reporter": "^6.6.6",
+        "@wdio/sync": "^6.6.4",
+        "babel-jest": "^26.5.2",
+        "chromedriver": "^86.0.0",
+        "codecov": "^3.8.0",
         "commitizen": "^4.2.1",
         "conventional-changelog-cli": "^2.1.0",
         "cspell": "^4.1.0",
         "depcheck": "^1.2.0",
         "doctoc": "^1.4.0",
-        "eslint": "^7.9.0",
-        "eslint-config-prettier": "^6.11.0",
+        "eslint": "^7.11.0",
+        "eslint-config-prettier": "^6.13.0",
         "eslint-import-resolver-typescript": "^2.3.0",
         "eslint-plugin-eslint-comments": "^3.1.2",
-        "eslint-plugin-import": "^2.22.0",
-        "eslint-plugin-jest": "^24.0.2",
+        "eslint-plugin-import": "^2.22.1",
+        "eslint-plugin-jest": "^24.1.0",
         "eslint-plugin-license-header": "^0.2.0",
         "eslint-plugin-markdown": "^2.0.0-rc.0",
         "eslint-plugin-notice": "^0.9.10",
         "eslint-plugin-prettier": "^3.1.4",
         "eslint-plugin-tsdoc": "^0.2.6",
         "eslint-watch": "^7.0.0",
         "husky": "^4.3.0",
-        "jest": "^26.4.2",
+        "jest": "^26.5.3",
         "lerna": "^3.21.0",
-        "lint-staged": "^10.4.0",
+        "lint-staged": "^10.4.1",
         "lockfile-lint": "^4.3.7",
         "markdown-link-check": "^3.8.3",
         "package-dependency-graph": "^1.9.1",
@@ -107,7 +108,7 @@
         "typescript": "^4.0.3",
         "vertioner": "^1.0.6",
         "wdio-chromedriver-service": "^6.0.4",
-        "webdriverio": "^6.5.2"
+        "webdriverio": "^6.6.6"
     },
     "engines": {
         "node": "^10 || ^12"

packages/assert/package.json

@@ -26,7 +26,7 @@
         "axe-core": "4.0.2"
     },
     "devDependencies": {
-        "@sa11y/test-utils": "0.2.1-beta.0"
+        "@sa11y/test-utils": "0.2.2-beta.0"
     },
     "publishConfig": {
         "access": "public"

packages/browser-lib/package.json

@@ -42,10 +42,13 @@
         "@rollup/plugin-commonjs": "^15.1.0",
         "@rollup/plugin-node-resolve": "^9.0.0",
         "@sa11y/common": "0.2.1-beta.0",
-        "rollup": "^2.28.2",
+        "rollup": "^2.32.0",
         "rollup-plugin-progress": "^1.1.2",
         "rollup-plugin-sizes": "^1.0.3",
         "rollup-plugin-terser": "^7.0.2",
-        "rollup-plugin-typescript2": "^0.27.2"
+        "rollup-plugin-typescript2": "^0.27.3"
+    },
+    "publishConfig": {
+        "access": "public"
     }
 }

packages/format/package.json

@@ -26,7 +26,7 @@
         "axe-core": "4.0.2"
     },
     "devDependencies": {
-        "@sa11y/test-utils": "0.2.1-beta.0"
+        "@sa11y/test-utils": "0.2.2-beta.0"
     },
     "publishConfig": {
         "access": "public"

packages/jest/README.md

@@ -11,7 +11,7 @@ Accessibility matcher for [Jest](https://jestjs.io)
 - [Setup](#setup)
   - [Project level](#project-level)
   - [Test module level](#test-module-level)
-- [⚠ Caution](#%E2%9A%A0-caution)
+- [Caution](#caution)
 - [Usage](#usage)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -70,12 +70,13 @@ beforeAll(() => {
 
 -   This makes the `toBeAccessible` API available for the tests only in that specific test module where `registerSa11yMatcher()` is invoked.
 
-## ⚠ Caution
+## Caution
 
 -   **async**: `toBeAccessible` **must** be invoked with `async/wait` or `Promise` or the equivalent supported asynchronous method in your environment
     -   Not invoking it async would result in incorrect results e.g. no issues reported even when the page is not accessible
 -   **color-contrast**: Color-contrast check is disabled for Jest tests as it [does not work in JSDOM](https://github.com/dequelabs/axe-core/issues/595)
-    -   If you need to check for color-contrast please use a real browser to test e.g. using [`@sa11y/wdio`](https://github.com/salesforce/sa11y/tree/master/packages/wdio#readme)
+-   **audio, video**: Accessibility of `audio`, `video` elements cannot be checked with Jest as they are [stubbed out in JSDOM](https://github.com/jsdom/jsdom/issues/2155)
+-   **real browser**: If you need to check for color-contrast, audio/video elements or any other checks which need the element to be rendered visually please use a real browser to test e.g. using [`@sa11y/wdio`](https://github.com/salesforce/sa11y/tree/master/packages/wdio#readme)
 
 ## Usage
 

packages/jest/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sa11y/jest",
-    "version": "0.1.4-beta.0",
+    "version": "0.1.4-beta.1",
     "description": "Accessibility testing matcher for Jest",
     "license": "BSD-3-Clause",
     "homepage": "https://github.com/salesforce/sa11y/tree/master/packages/jest#readme",
@@ -32,7 +32,7 @@
     },
     "devDependencies": {
         "@sa11y/common": "0.2.1-beta.0",
-        "@sa11y/test-utils": "0.2.1-beta.0"
+        "@sa11y/test-utils": "0.2.2-beta.0"
     },
     "publishConfig": {
         "access": "public"

packages/test-integration/__tests__/jest.test.js

@@ -5,7 +5,7 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-import { beforeEachSetup, domWithA11yIssues, domWithNoA11yIssues } from '@sa11y/test-utils';
+import { beforeEachSetup, domWithA11yIssues, domWithNoA11yIssues, domWithVisualA11yIssues } from '@sa11y/test-utils';
 
 beforeEach(beforeEachSetup);
 
@@ -23,4 +23,11 @@ describe('integration test @sa11y/jest', () => {
             .toBeAccessible()
             .catch((e) => expect(e).toMatchSnapshot());
     });
+
+    it('will not throw error for audio video color-contrast', async () => {
+        document.body.innerHTML = domWithVisualA11yIssues;
+        // Even though the dom has a11y issues w.r.t color contrast and audio/video
+        //  elements etc, Jest/JSDOM will not able to detect them
+        await expect(document).toBeAccessible();
+    });
 });

packages/test-integration/__tests__/wdio.test.ts

@@ -7,7 +7,7 @@
 
 import { BrowserObject, remote } from 'webdriverio';
 import { assertAccessibleSync } from '@sa11y/wdio';
-import { htmlFileWithA11yIssues, htmlFileWithNoA11yIssues } from '@sa11y/test-utils';
+import { htmlFileWithA11yIssues, htmlFileWithNoA11yIssues, htmlFileWithVisualA11yIssues } from '@sa11y/test-utils';
 
 // TODO (chore): Raise issue with WebdriverIO - 'sync' missing 'default' in ts def
 // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-var-requires
@@ -43,8 +43,11 @@ afterAll(async () => {
 });
 
 describe('integration test @sa11y/wdio in sync mode', () => {
-    it('should throw error for html with a11y issues', () => {
+    it('should have browser object be setup', () => {
         expect(browser).toBeTruthy();
+    });
+
+    it('should throw error for html with a11y issues', () => {
         // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
         return sync(() => {
             void browser.url(htmlFileWithA11yIssues);
@@ -53,11 +56,18 @@ describe('integration test @sa11y/wdio in sync mode', () => {
     });
 
     it('should not throw error for html with no a11y issues', () => {
-        expect(browser).toBeTruthy();
         // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
         return sync(() => {
             void browser.url(htmlFileWithNoA11yIssues);
             expect(() => assertAccessibleSync(browser)).not.toThrow();
         });
     });
+
+    it('should throw error for html with visual a11y issues', () => {
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
+        return sync(() => {
+            void browser.url(htmlFileWithVisualA11yIssues);
+            expect(() => assertAccessibleSync(browser)).toThrowErrorMatchingSnapshot();
+        });
+    });
 });

packages/test-integration/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sa11y/test-integration",
-    "version": "0.1.3-beta.0",
+    "version": "0.1.4-beta.0",
     "private": true,
     "description": "Private package for integration testing @sa11y packages",
     "license": "BSD-3-Clause",
@@ -11,8 +11,8 @@
         "directory": "packages/test-integration"
     },
     "devDependencies": {
-        "@sa11y/jest": "0.1.4-beta.0",
-        "@sa11y/test-utils": "0.2.1-beta.0",
-        "@sa11y/wdio": "0.1.1-alpha.0"
+        "@sa11y/jest": "0.1.4-beta.1",
+        "@sa11y/test-utils": "0.2.2-beta.0",
+        "@sa11y/wdio": "0.1.1-alpha.1"
     }
 }

packages/test-utils/__data__/a11yIssuesVisual.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <title>Test Page</title>
+    </head>
+    <body>
+        <div role="main" id="host">
+            <h1>This is a test</h1>
+            <p>This is a test page with violations that can be detected only with a real browser</p>
+            <audio src="https://file-examples-com.github.io/uploads/2017/11/file_example_MP3_700KB.mp3" autoplay>Audio test</audio>
+            <video src="https://file-examples-com.github.io/uploads/2020/03/file_example_WEBM_480_900KB.webm" autoplay>Video test</video>
+        </div>
+        <div role="contentinfo" id="upside-down"></div>
+        <!-- cSpell:disable-line -->
+        <script>
+            const shadow = document.getElementById('upside-down').attachShadow({ mode: 'open' });
+            shadow.innerHTML = `<h2 id="shadow">SHADOW DOM</h2><ul><li>Shadow Item 1</li></ul>;
+                                <button style="background-color:red; color:white;font-size:14px;">Go!</button>`;
+        </script>
+    </body>
+</html>

packages/test-utils/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@sa11y/test-utils",
-    "version": "0.2.1-beta.0",
+    "version": "0.2.2-beta.0",
     "private": true,
     "description": "Private package providing test utilities for @sa11y packages",
     "license": "BSD-3-Clause",

packages/test-utils/src/index.ts

@@ -10,8 +10,10 @@ export {
     domWithA11yIssues,
     domWithA11yIssuesBodyID,
     domWithNoA11yIssues,
+    domWithVisualA11yIssues,
     htmlFileWithA11yIssues,
     htmlFileWithNoA11yIssues,
+    htmlFileWithVisualA11yIssues,
     shadowDomID,
     videoURL,
 } from './test-data';

packages/test-utils/src/test-data.ts

@@ -20,6 +20,11 @@ const fileWithNoA11yIssues = path.resolve(__dirname, '../__data__/noA11yIssues.h
 export const htmlFileWithNoA11yIssues = 'file:///' + fileWithNoA11yIssues;
 export const domWithNoA11yIssues = fs.readFileSync(fileWithNoA11yIssues).toString();
 
+// DOM with video, color contrast a11y issues that can be detected only in a real browser
+const fileWithVisualA11yIssues = path.resolve(__dirname, '../__data__/a11yIssuesVisual.html');
+export const htmlFileWithVisualA11yIssues = 'file:///' + fileWithVisualA11yIssues;
+export const domWithVisualA11yIssues = fs.readFileSync(fileWithVisualA11yIssues).toString();
+
 // Sample media files
 // TODO (refactor): Is there a way to reuse these values inside the noA11yIssues.html
 export const audioURL = 'https://file-examples-com.github.io/uploads/2017/11/file_example_MP3_700KB.mp3';

packages/wdio/README.md

@@ -6,13 +6,13 @@ Provides `assertAccessible()`, `assertAccessibleSync()` APIs that can be used wi
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
 
-- [⚠ Caution](#%E2%9A%A0-caution)
+- [Caution](#caution)
 - [Usage](#usage)
 - [Reference](#reference)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
-## ⚠ Caution
+## Caution
 
 -   **headless**: Checks such as color contrast do not work in headless mode. In general executing tests in headless mode [might yield different accessibility results](https://github.com/dequelabs/axe-core/issues/2088). Hence, it is recommended to run accessibility checks in windowed mode when possible for accurate results.