feat: added functionality for jest custom ruleset (#630)

* feat: added functionality for jest custom ruleset

* fix: changed coverage

* fix: review added

* fix: reading custom rules file async

---------

Co-authored-by: Navateja Alagam <navateja215@gmail.com>

cSpell.json

@@ -14,7 +14,8 @@
         "wcag",
         "wdio",
         "webdriverio",
-        "webm"
+        "webm",
+        "Vidyard"
     ],
     "flagWords": ["master-slave", "slave", "blacklist", "whitelist"],
     "allowCompoundWords": true

packages/common/__tests__/helpers.test.ts

@@ -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 { useFilesToBeExempted, log } from '../src/helpers';
+import { useFilesToBeExempted, log, useCustomRules } from '../src/helpers';
 
 describe('Your Module', () => {
     afterEach(() => {
@@ -66,4 +66,23 @@ describe('Your Module', () => {
 
         delete process.env.SA11Y_AUTO_FILTER_LIST_PACKAGE_NAME;
     });
+
+    it('should return empty array if SA11Y_CUSTOM_RULES env variable is not set', async () => {
+        process.env.SA11Y_CUSTOM_RULES = '';
+        const result = await useCustomRules();
+        expect(result).toEqual([]);
+    });
+
+    it('should return empty array if reading file encounters an error', async () => {
+        process.env.SA11Y_CUSTOM_RULES = 'packages/common/testMocks/WrongFile.json';
+        const result = await useCustomRules();
+        expect(result).toEqual([]);
+    });
+
+    it('should return rules array if file is read successfully', async () => {
+        process.env.SA11Y_CUSTOM_RULES = 'packages/common/testMocks/sa11y-custom-rules.json';
+        const mockRules = ['rule1', 'rule2'];
+        const result = await useCustomRules();
+        expect(result).toEqual(mockRules);
+    });
 });

packages/common/src/helpers.ts

@@ -10,6 +10,7 @@
  * Logging is enabled only when environment variable `SA11Y_DEBUG` is set.
  */
 
+import * as fs from 'fs/promises';
 export function log(...args: unknown[]): void {
     // Probably not worth it to mock and test console logging for this helper util
     /* istanbul ignore next */
@@ -32,3 +33,19 @@ export function useFilesToBeExempted(): string[] {
     }
     return [];
 }
+
+export async function useCustomRules(): Promise<string[]> {
+    const filePath = process.env.SA11Y_CUSTOM_RULES ?? '';
+    if (filePath !== '') {
+        try {
+            // Read the file asynchronously
+            const data = await fs.readFile(filePath, 'utf-8');
+            const { rules } = JSON.parse(data) as { rules: string[] };
+            // Access the rules array
+            return rules;
+        } catch (err) {
+            console.error('Error reading the custom ruleset file:', err);
+        }
+    }
+    return [];
+}

packages/common/src/index.ts

@@ -8,4 +8,4 @@
 export { A11yConfig, AxeResults, axeRuntimeExceptionMsgPrefix, axeVersion, getAxeRules, getViolations } from './axe';
 export { WdioAssertFunction, WdioOptions } from './wdio';
 export { errMsgHeader, ExceptionList } from './format';
-export { log, useFilesToBeExempted } from './helpers';
+export { log, useFilesToBeExempted, useCustomRules } from './helpers';

packages/common/testMocks/sa11y-custom-rules.json

@@ -0,0 +1,3 @@
+{
+    "rules": ["rule1", "rule2"]
+}

packages/jest/__tests__/automatic.test.ts

@@ -14,6 +14,7 @@ import {
     domWithNoA11yIssues,
     domWithNoA11yIssuesChildCount,
     domWithDescendancyA11yIssues,
+    customRulesFilePath,
 } from '@sa11y/test-utils';
 import * as Sa11yCommon from '@sa11y/common';
 import { expect, jest } from '@jest/globals';
@@ -203,4 +204,11 @@ describe('automatic checks call', () => {
         document.body.innerHTML = domWithA11yIssues;
         await expect(automaticCheck({ filesFilter: nonExistentFilePaths })).rejects.toThrow();
     });
+
+    it('should take only custom rules if specified', async () => {
+        document.body.innerHTML = domWithA11yIssues;
+        process.env.SA11Y_CUSTOM_RULES = customRulesFilePath;
+        await expect(automaticCheck({ cleanupAfterEach: true })).rejects.toThrow('1 Accessibility');
+        delete process.env.SA11Y_CUSTOM_RULES;
+    });
 });

packages/jest/__tests__/setup.test.ts

@@ -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 { adaptA11yConfig, registerSa11yMatcher } from '../src/setup';
+import { adaptA11yConfig, adaptA11yConfigCustomRules, registerSa11yMatcher } from '../src/setup';
 import { base, extended } from '@sa11y/preset-rules';
 import { expect, jest } from '@jest/globals';
 
@@ -21,6 +21,15 @@ describe('jest setup', () => {
         // original ruleset is not modified
         expect(config.runOnly.values).toContain('color-contrast');
     });
+    it('should customize preset-rule as expected for custom rules', () => {
+        expect(base.runOnly.values).toContain('color-contrast');
+        const rules = adaptA11yConfigCustomRules(base, ['rule1', 'rule2']).runOnly.values;
+        expect(rules).toContain('rule1');
+        expect(rules).toContain('rule2');
+
+        // original ruleset is not modified
+        expect(base.runOnly.values).toContain('color-contrast');
+    });
 
     /* Skipped: Difficult to mock the global "expect" when we are `import {expect} from '@jest/globals'` */
     it.skip('should throw error when global expect is undefined', () => {

packages/jest/src/automatic.ts

@@ -5,12 +5,12 @@
  * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/BSD-3-Clause
  */
 
-import { AxeResults, log } from '@sa11y/common';
+import { AxeResults, log, useCustomRules } from '@sa11y/common';
 import { getViolationsJSDOM } from '@sa11y/assert';
 import { A11yError } from '@sa11y/format';
 import { isTestUsingFakeTimer } from './matcher';
 import { expect } from '@jest/globals';
-import { adaptA11yConfig } from './setup';
+import { adaptA11yConfig, adaptA11yConfigCustomRules } from './setup';
 import { defaultRuleset } from '@sa11y/preset-rules';
 
 /**
@@ -82,6 +82,7 @@ export async function automaticCheck(opts: AutoCheckOpts = defaultAutoCheckOpts)
     // Create a DOM walker filtering only elements (skipping text, comment nodes etc)
     const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_ELEMENT);
     let currNode = walker.firstChild();
+    const customRules = await useCustomRules();
     try {
         while (currNode !== null) {
             // TODO (spike): Use a logger lib with log levels selectable at runtime
@@ -91,7 +92,12 @@ export async function automaticCheck(opts: AutoCheckOpts = defaultAutoCheckOpts)
             //      : ${testPath}`
             // );
             // W-10004832 - Exclude descendancy based rules from automatic checks
-            violations.push(...(await getViolationsJSDOM(currNode, adaptA11yConfig(defaultRuleset))));
+            if (customRules.length === 0)
+                violations.push(...(await getViolationsJSDOM(currNode, adaptA11yConfig(defaultRuleset))));
+            else
+                violations.push(
+                    ...(await getViolationsJSDOM(currNode, adaptA11yConfigCustomRules(defaultRuleset, customRules)))
+                );
             currNode = walker.nextSibling();
         }
     } finally {

packages/jest/src/setup.ts

@@ -126,7 +126,6 @@ export function setup(opts: Sa11yOpts = defaultSa11yOpts): void {
     ]);
     registerSa11yAutomaticChecks(autoCheckOpts);
 }
-
 /**
  * Register accessibility helpers toBeAccessible as jest matchers
  */
@@ -141,10 +140,14 @@ export function registerSa11yMatcher(): void {
         );
     }
 }
-
 /**
  * Customize sa11y preset rules specific to JSDOM
  */
+export function adaptA11yConfigCustomRules(config: A11yConfig, customRules: string[]): A11yConfig {
+    const adaptedConfig = JSON.parse(JSON.stringify(config)) as A11yConfig;
+    adaptedConfig.runOnly.values = customRules;
+    return adaptedConfig;
+}
 export function adaptA11yConfig(config: A11yConfig, filterRules = disabledRules): A11yConfig {
     // TODO (refactor): Move into preset-rules pkg as a generic rules filter util
     const adaptedConfig = JSON.parse(JSON.stringify(config)) as A11yConfig;

packages/test-utils/__data__/sa11y-custom-rules.json

@@ -0,0 +1,3 @@
+{
+    "rules": ["link-name"]
+}

packages/test-utils/src/index.ts

@@ -21,5 +21,6 @@ export {
     a11yIssuesCountFiltered,
     shadowDomID,
     videoURL,
+    customRulesFilePath,
 } from './test-data';
 export { beforeEachSetup, cartesianProduct } from './utils';

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

@@ -13,6 +13,7 @@ const dataDir = path.resolve(__dirname, '../__data__/');
 // DOM with a11y issues
 export const domWithA11yIssuesBodyID = 'dom-with-issues';
 const fileWithA11yIssues = path.resolve(dataDir, 'a11yIssues.html');
+export const customRulesFilePath = path.resolve(dataDir, 'sa11y-custom-rules.json');
 const fileWithDescendancyA11yIssues = path.resolve(dataDir, 'descendancyA11yIssues.html');
 export const htmlFileWithA11yIssues = 'file:///' + fileWithA11yIssues;
 export const domWithA11yIssues = fs.readFileSync(fileWithA11yIssues).toString();