@axe-core/cli 4.7.4-cbd2a5f.0 → 4.8.0

package/src/bin/index.ts

@@ -0,0 +1,216 @@
+import type { OptionValues } from 'commander';
+import colors from 'colors';
+import {
+  parseBrowser,
+  parseUrl,
+  reporter,
+  getAxeVersion,
+  getAxeSource,
+  saveOutcome,
+  bold,
+  error,
+  italics,
+  link
+} from '../lib/utils';
+import axeTestUrls from '../lib/axe-test-urls';
+import event from '../lib/events';
+import { startDriver } from '../lib/webdriver';
+import { error as selenium_error } from 'selenium-webdriver';
+
+const cli = async (
+  args: OptionValues,
+  url: { args: string[] }
+): Promise<void> => {
+  const {
+    save,
+    stdout,
+    dir,
+    exit,
+    timer,
+    reporter: noReporter,
+    chromeOptions,
+    verbose,
+    timeout,
+    include,
+    exclude,
+    tags,
+    rules,
+    disable,
+    loadDelay,
+    chromedriverPath,
+    chromePath
+  } = args;
+
+  const showErrors = args.showErrors === true;
+
+  const silentMode = !!stdout;
+  args.axeSource = getAxeSource(args.axeSource);
+
+  if (!args.axeSource) {
+    console.error(error('Unable to find the axe-core source file'));
+    process.exit(2);
+  }
+
+  args.browser = parseBrowser(args.browser);
+  /* istanbul ignore if */
+  if (chromeOptions) {
+    /* istanbul ignore if */
+    if (args.browser !== 'chrome-headless') {
+      console.error(
+        error(
+          'You may only provide --chrome-options when using headless chrome'
+        )
+      );
+      process.exit(2);
+    }
+  }
+
+  const driverConfigs = {
+    browser: args.browser,
+    timeout,
+    chromeOptions,
+    chromedriverPath,
+    chromePath
+  };
+
+  args.driver = startDriver(driverConfigs);
+
+  const cliReporter = reporter(noReporter, silentMode);
+  const axeVersion = getAxeVersion(args.axeSource);
+  if (!silentMode) {
+    console.log(
+      colors.bold('Running axe-core ' + axeVersion + ' in ' + args.browser)
+    );
+  }
+
+  const urls = url.args.map(parseUrl);
+
+  /* istanbul ignore if */
+  if (urls.length === 0) {
+    console.error(error('No url was specified. Check `axe --help` for help\n'));
+  }
+
+  const events = event({
+    silentMode,
+    timer,
+    cliReporter,
+    verbose,
+    exit
+  });
+
+  const testPageConfigParams = {
+    driver: args.driver,
+    timer,
+    loadDelay,
+    axeSource: args.axeSource,
+    include,
+    exclude,
+    tags,
+    rules,
+    disable
+  };
+  let outcome;
+  try {
+    try {
+      outcome = await axeTestUrls(urls, testPageConfigParams, events);
+    } catch (e) {
+      if (e instanceof selenium_error.ScriptTimeoutError) {
+        console.error(error('Error: %s'), e.message);
+        console.log(`The timeout is currently configured to be ${timeout} seconds (you can change it with --timeout).`)
+        process.exit(2);
+      }
+      // Provide a more user-friendly error message when there's a ChromeDriver/Chrome version mismatch.
+      else if (
+        e instanceof selenium_error.SessionNotCreatedError &&
+        e.message.includes(
+          'This version of ChromeDriver only supports'
+          // This string has to match the error message printed by chromedriver, see
+          // https://chromium.googlesource.com/chromium/src/+/refs/tags/110.0.5481.194/chrome/test/chromedriver/chrome_launcher.cc#300.
+        )
+      ) {
+        console.error(error('Error: %s'), e.message);
+        console.log(`\nPlease install a matching version of ChromeDriver and run axe with the --chromedriver-path option:
+
+    $ npm install -g chromedriver@<version>
+    $ axe --chromedriver-path $(npm root -g)/chromedriver/bin/chromedriver <url...>
+
+(where <version> is the first number of the "current browser version" reported above.)`);
+        process.exit(2);
+      } else {
+        throw e;
+      }
+    }
+    if (silentMode) {
+      process.stdout.write(JSON.stringify(outcome, null, 2));
+      return;
+    }
+
+    if (timer) {
+      console.timeEnd('Total test time');
+    }
+
+    /* istanbul ignore if */
+    if (Array.isArray(outcome)) {
+      console.log(bold('Testing complete of %d pages\n'), outcome.length);
+    }
+
+    if (save || dir) {
+      try {
+        const fileName = saveOutcome(outcome, save, dir);
+        console.log('Saved file at', fileName, '\n');
+      } catch (e) {
+        /* istanbul ignore next */
+        console.error(error('Unable to save file!\n') + e);
+        process.exit(1);
+      }
+    }
+
+    if (exit) {
+      let exitErr = false;
+      /* istanbul ignore if */
+      if (Array.isArray(outcome)) {
+        for (const res of outcome) {
+          if (res.violations.length > 0) {
+            exitErr = true;
+            break;
+          }
+        }
+      } else {
+        exitErr = outcome.violations.length > 0;
+      }
+      if (exitErr) {
+        process.exit(1);
+      }
+    }
+
+    /* istanbul ignore if */
+    if (silentMode) {
+      return;
+    }
+
+    console.log(
+      italics(
+        'Please note that only 20% to 50% of all accessibility ' +
+          'issues can automatically be detected. \nManual testing is ' +
+          'always required. For more information see:\n%s\n'
+      ),
+      link('https://dequeuniversity.com/curriculum/courses/testingmethods')
+    );
+  } catch (e) {
+    /* istanbul ignore else */
+    if (!showErrors) {
+      console.error(error('An error occurred while testing this page.'));
+    } else {
+      console.error(error('Error: %s'), e);
+    }
+
+    console.error(
+      'Please report the problem to: ' +
+        link('https://github.com/dequelabs/axe-core-npm/issues/') +
+        '\n'
+    );
+    process.exit(1);
+  }
+};
+
+export default cli;

package/src/lib/axe-test-urls.test.ts

@@ -0,0 +1,73 @@
+import 'mocha';
+import { assert } from 'chai';
+import testPages from './axe-test-urls';
+import { ConfigParams } from '../types';
+
+describe('testPages', function () {
+  this.timeout(10000);
+  let config: ConfigParams;
+  let mockDriver: any;
+
+  beforeEach(() => {
+    const func = async (arg: any) => '{}';
+    mockDriver = {
+      get: func,
+      executeAsyncScript: func,
+      executeScript: func,
+      wait: func,
+      switchTo: () => ({ defaultContent: () => {} }),
+      findElements: async () => [],
+      quit: func,
+      manage: () => ({
+        setTimeouts: func
+      })
+    };
+    config = { driver: mockDriver };
+  });
+
+  it('return a promise', () => {
+    assert.instanceOf(testPages([], config), Promise);
+  });
+
+  it('calls driver.get() for each URL', async () => {
+    const urlsCalled: string[] = [];
+    const urls = ['http://foo', 'http://bar', 'http://baz'];
+
+    mockDriver.get = async (url: string) => {
+      urlsCalled.push(url);
+      return url;
+    };
+
+    await testPages(urls, config);
+
+    assert.deepEqual(urlsCalled, urls);
+  });
+
+  it('injects axe into the page', async () => {
+    const scripts: string[] = [];
+    config.axeSource = 'axe="hi, I am axe"';
+    mockDriver.executeScript = async (script: string) => {
+      scripts.push(script);
+      return script;
+    };
+
+    await testPages(['http://foo'], config);
+    assert.include(scripts[0].toString(), config.axeSource);
+  });
+
+  it('runs axe once the page is loaded', async () => {
+    const asyncScripts: string[] = [];
+    mockDriver.executeAsyncScript = async (script: string) => {
+      asyncScripts.push(script);
+      return '{}';
+    };
+
+    await testPages(['http://foo'], config);
+
+    assert.isDefined(
+      asyncScripts
+        .map(script => script.toString())
+        .find(script => script.match(/(axe\.run)|(axe\.a11yCheck)/))
+    );
+  });
+});

package/src/lib/axe-test-urls.ts

@@ -0,0 +1,98 @@
+import WebDriver from 'selenium-webdriver';
+import AxeBuilder from '@axe-core/webdriverjs';
+import { AxeResults } from 'axe-core';
+import { EventResponse, ConfigParams } from '../types';
+
+const testPages = async (
+  urls: string | string[],
+  config: ConfigParams,
+  events?: EventResponse
+): Promise<AxeResults[] | AxeResults> => {
+  const driver: WebDriver.WebDriver = await config.driver;
+
+  if (urls.length === 0) {
+    await driver.quit();
+    return Promise.resolve([]);
+  }
+
+  return new Promise((resolve, reject) => {
+    const currentUrl = urls[0].replace(/[,;]$/, '');
+
+    if (events?.onTestStart) {
+      events?.onTestStart(currentUrl);
+    }
+
+    if (config.timer) {
+      events?.startTimer('axe page load time');
+    }
+
+    driver
+      .get(currentUrl)
+      .then(() => {
+        if (config.timer) {
+          events?.endTimer('axe page load time');
+        }
+
+        if (config.loadDelay) {
+          events?.waitingMessage(config.loadDelay);
+        }
+
+        return new Promise(resolve => {
+          setTimeout(resolve, config.loadDelay);
+        });
+      })
+      .then(() => {
+        const axe = new AxeBuilder(driver, config.axeSource);
+
+        if (Array.isArray(config.include)) {
+          config.include.forEach((include: string) => axe.include(include));
+        }
+
+        if (Array.isArray(config.exclude)) {
+          config.exclude.forEach((exclude: string) => axe.exclude(exclude));
+        }
+
+        if (config.tags) {
+          axe.withTags(config.tags);
+        } else if (config.rules) {
+          axe.withRules(config.rules);
+        }
+
+        /* istanbul ignore if */
+        if (config.disable) {
+          axe.disableRules(config.disable);
+        }
+
+        if (config.timer) {
+          events?.startTimer('axe-core execution time');
+        }
+
+        axe.analyze((err: Error | null, results: AxeResults) => {
+          if (config.timer) {
+            events?.endTimer('axe-core execution time');
+          }
+
+          /* istanbul ignore if */
+          if (err) {
+            return reject(err);
+          }
+
+          // Notify about the update
+          if (events?.onTestComplete) {
+            events?.onTestComplete(results);
+          }
+
+          // Move to the next item
+          testPages(urls.slice(1), config, events).then((out: AxeResults) => {
+            resolve([results].concat(out));
+          });
+        });
+      })
+      .catch(async e => {
+        await driver.quit();
+        reject(e);
+      });
+  });
+};
+
+export default testPages;

package/src/lib/events.test.ts

@@ -0,0 +1,26 @@
+import 'mocha';
+import { assert } from 'chai';
+import events from './events';
+
+describe('events()', () => {
+  const event = events({
+    silentMode: false,
+    timer: false,
+    cliReporter: () => {},
+    verbose: false,
+    exit: false
+  });
+  const functions = [
+    'startTimer',
+    'endTimer',
+    'waitingMessage',
+    'onTestStart',
+    'onTestComplete'
+  ];
+  for (const eventFunction of functions) {
+    it(`${eventFunction} is a typeof function`, () => {
+      // @ts-ignore
+      assert.isFunction(event[eventFunction]);
+    });
+  }
+});

package/src/lib/events.ts

@@ -0,0 +1,68 @@
+import type { AxeResults } from 'axe-core';
+import type { EventParams } from '../types';
+import { selectorToString, error, link, bold, green } from './utils';
+
+export default ({ silentMode, timer, cliReporter, verbose }: EventParams) => {
+  return {
+    startTimer: (message: string) => {
+      console.time(message);
+    },
+    endTimer: (message: string) => {
+      console.timeEnd(message);
+    },
+    waitingMessage: (loadDelayTime: number) => {
+      console.log(
+        'Waiting for ' + loadDelayTime + ' milliseconds after page loads...'
+      );
+    },
+    onTestStart: (url: string) => {
+      if (silentMode) {
+        return;
+      }
+      console.log(
+        bold('\nTesting ' + link(url)) +
+          ' ... please wait, this may take a minute.'
+      );
+      if (timer) {
+        console.time('Total test time');
+      }
+    },
+    onTestComplete: (results: AxeResults) => {
+      const { violations, testEngine, testEnvironment, testRunner } = results;
+
+      /* istanbul ignore if */
+      if (violations.length === 0) {
+        cliReporter(green(' 0 violations found!'));
+        return;
+      }
+
+      const issueCount = violations.reduce((count, violation) => {
+        cliReporter(
+          '\n' +
+            error('  Violation of %j with %d occurrences!\n') +
+            '    %s. Correct invalid elements at:\n' +
+            violation.nodes
+              .map(node => '     - ' + selectorToString(node.target) + '\n')
+              .join('') +
+            '    For details, see: %s',
+          violation.id,
+          violation.nodes.length,
+          violation.description,
+          link(violation.helpUrl.split('?')[0])
+        );
+        return count + violation.nodes.length;
+      }, 0);
+
+      cliReporter(error('\n%d Accessibility issues detected.'), issueCount);
+
+      if (verbose) {
+        const metadata = {
+          'Test Runner': testRunner,
+          'Test Engine': testEngine,
+          'Test Environment': testEnvironment
+        };
+        cliReporter(`\n${JSON.stringify(metadata, null, 2)}`);
+      }
+    }
+  };
+};

package/{dist/src/lib/index.d.ts → src/lib/index.ts}

@@ -1,4 +1,5 @@
 import testPages from './axe-test-urls';
 import { saveOutcome } from './utils';
 import * as utils from './utils';
+
 export { saveOutcome, testPages, utils };

package/src/lib/utils.test.ts

@@ -0,0 +1,160 @@
+import 'mocha';
+import { assert } from 'chai';
+import tempy from 'tempy';
+import { join } from 'path';
+import { mkdirSync, writeFileSync, rmSync } from 'fs';
+import { dependencies } from '../../package.json';
+import * as utils from './utils';
+
+describe('utils', () => {
+  describe('parseUrl', () => {
+    it('given a url without protocol', () => {
+      const url = 'foobar.com';
+      assert.deepEqual(utils.parseUrl(url), `http://${url}`);
+    });
+    it('given a url with a protocol', () => {
+      const url = 'http://foobar.com';
+      assert.deepEqual(utils.parseUrl(url), url);
+    });
+  });
+
+  describe('parseBrowser', () => {
+    it('given an unknown browser returns error', () => {
+      assert.throws(() => utils.parseBrowser('foobar'));
+    });
+
+    it('given no browser returns chrome-headless', () => {
+      assert.deepEqual(utils.parseBrowser(), 'chrome-headless');
+    });
+
+    describe('returns firefox', () => {
+      const firefoxBrowsers = ['ff', 'firefox', 'gecko', 'marionette'];
+      for (const firefoxBrowser of firefoxBrowsers) {
+        it(`given ${firefoxBrowser} returns firefox`, () => {
+          assert.deepEqual(utils.parseBrowser(firefoxBrowser), 'firefox');
+        });
+      }
+    });
+
+    describe('returns chrome', () => {
+      it('given chrome returns chrome', () => {
+        assert.deepEqual(utils.parseBrowser('chrome'), 'chrome');
+      });
+    });
+
+    describe('returns ie', () => {
+      const ieBrowsers = [
+        'ie',
+        'explorer',
+        'internetexplorer',
+        'internet_explorer',
+        'internet-explorer'
+      ];
+
+      for (const ieBrowser of ieBrowsers) {
+        it(`given ${ieBrowser} returns ie`, () => {
+          assert.deepEqual(utils.parseBrowser(ieBrowser), 'ie');
+        });
+      }
+    });
+
+    describe('returns safari', () => {
+      it('given safari return safari', () => {
+        assert.deepEqual(utils.parseBrowser('safari'), 'safari');
+      });
+    });
+
+    describe('returns edge', () => {
+      const edgeBrowsers = ['edge', 'microsoftedge'];
+      for (const edgeBrowser of edgeBrowsers) {
+        it(`given ${edgeBrowser} returns MicrosoftEdge`, () => {
+          assert.deepEqual(utils.parseBrowser(edgeBrowser), 'MicrosoftEdge');
+        });
+      }
+    });
+  });
+
+  describe('getAxeSource', () => {
+    describe('mock file', () => {
+      function setupTree() {
+        const tempDir = tempy.directory();
+        const parentDirname = join(tempDir, 'node_modules', 'axe-core');
+        mkdirSync(parentDirname, { recursive: true });
+        writeFileSync(join(parentDirname, 'axe.js'), 'parent');
+
+        const cliDirname = join(tempDir, 'packages', 'cli');
+        const nodeModDirname = join(
+          cliDirname,
+          'node_modules',
+          'axe-core'
+        );
+        mkdirSync(nodeModDirname, { recursive: true });
+        writeFileSync(join(nodeModDirname, 'axe.js'), 'node modules');
+
+        const cwdDirname = join(tempDir, 'packages', 'cli', 'lib');
+        mkdirSync(cwdDirname);
+        writeFileSync(join(cwdDirname, 'axe.js'), 'cwd');
+        return {
+          cliDirname,
+          parentDirname,
+          nodeModDirname,
+          cwdDirname
+        };
+      }
+
+      it('uses axe.js from the working directory if it exists', () => {
+        const { cwdDirname } = setupTree();
+        const axeSource = utils.getAxeSource(undefined, cwdDirname);
+        assert.include(axeSource, 'cwd');
+      });
+      it("falls back to axe-core from the working directory's node_modules if axe.js doesn't exist in the working directory", () => {
+        const { cliDirname, cwdDirname } = setupTree();
+        rmSync(join(cwdDirname, 'axe.js'));
+        const axeSource = utils.getAxeSource(undefined, cliDirname);
+        assert.include(axeSource, 'node modules');
+      });
+      it("falls back to axe-core from our own package's node_modules if no working-directory based implementation exists", () => {
+        const { cwdDirname, nodeModDirname } = setupTree();
+        rmSync(join(cwdDirname, 'axe.js'));
+        rmSync(join(nodeModDirname, 'axe.js'));
+        const axeSource = utils.getAxeSource(undefined, cwdDirname);
+        assert.include(axeSource, 'parent');
+      });
+    });
+
+    it('given no axe source use local source', () => {
+      const axeSource = utils.getAxeSource();
+      assert.isNotNull(axeSource);
+    });
+
+    it('given invalid axe source throws error', () => {
+      assert.throws(() => utils.getAxeSource('././././'));
+    });
+  });
+
+  describe('getAxeVersion', () => {
+    it('given valid axe version returns only version', () => {
+      assert.deepEqual(utils.getAxeVersion(`axe.version = '4.1.1'`), '4.1.1');
+    });
+
+    it('given invalid axe version returns unknown version string', () => {
+      assert.deepEqual(utils.getAxeVersion(`axe = '4.1.1'`), 'unknown version');
+    });
+  });
+
+  describe('splitList', () => {
+    it('given a comma delimited string returns array', () => {
+      const delimited = 'foo,bar,baz';
+      const array = utils.splitList(delimited);
+      assert.isArray(array);
+      assert.deepEqual(array, ['foo', 'bar', 'baz']);
+    });
+
+    it('given a single string returns an array', () => {
+      const string = 'foo';
+      const array = utils.splitList(string);
+      assert.isArray(array);
+      assert.deepEqual(array, ['foo']);
+    });
+  });
+});