refactor(webdriverjs): rewrite webdriverjs to TS (dequelabs#197)

.circleci/config.yml

@@ -128,7 +128,7 @@ jobs:
     steps:
       - checkout
       - restore_dependency_cache
-      - run: npm run test --prefix=packages/webdriverjs
+      - run: npm run coverage --prefix=packages/webdriverjs
 
   webdriverio:
     <<: *defaults

.github/axe-linter.yml

@@ -7,3 +7,4 @@ exclude:
   - packages/react/cypress/**/*
   - packages/cli/test/**/*
   - packages/cli/testutils/**/*
+  - packages/webdriverjs/src/test/fixtures/**

.gitignore

@@ -2,7 +2,7 @@ node_modules
 dist
 __tests__
 coverage
-
+.nyc_output
 packages/react/example/build
 packages/react/test/index.js
 packages/react/cypress/screenshots

packages/webdriverjs/.eslintrc.js

@@ -1,9 +1,12 @@
 module.exports = {
   overrides: [
     {
-      files: 'test/**/*.js',
+      files: 'src/test/**/*.ts',
       env: {
         mocha: true
+      },
+      rules: {
+        '@typescript-eslint/no-var-requires': 'off'
       }
     }
   ]

packages/webdriverjs/README.md

@@ -1,6 +1,6 @@
 # @axe-core/webdriverjs
 
-Provides a chainable axe API for Selenium's WebDriverJS and automatically injects into all frames.
+> Provides a chainable axe API for Selenium's WebDriverJS and automatically injects into all frames.
 
 Previous versions of this program were maintained at [dequelabs/axe-webdriverjs](https://github.com/dequelabs/axe-webdriverjs).
 
@@ -16,18 +16,18 @@ Install @axe-core/webdriverjs and its dependencies: `npm install @axe-core/webdr
 
 ## Usage
 
-This module uses a chainable API to assist in injecting, configuring and analyzing using aXe with Selenium WebDriverJS. As such, it is required to pass an instance of WebDriver.
+This module uses a chainable API to assist in injecting, configuring, and analyzing axe with WebdriverJS. As such, it is required to pass an instance of WebdriverJS.
 
-Here is an example of a script that will drive Selenium to this repository, perform analysis and then log results to the console.
+Here is an example of a script that will drive WebdriverJS to a page, perform an analysis, and then log results to the console.
 
-```javascript
-var AxeBuilder = require('@axe-core/webdriverjs');
-var WebDriver = require('selenium-webdriver');
+```js
+const AxeBuilder = require('@axe-core/webdriverjs');
+const WebDriver = require('selenium-webdriver');
 
-var driver = new WebDriver.Builder().forBrowser('firefox').build();
+const driver = new WebDriver.Builder().forBrowser('firefox').build();
 
-driver.get('https://dequeuniversity.com/demo/mars/').then(function () {
-  new AxeBuilder(driver).analyze(function (err, results) {
+driver.get('https://dequeuniversity.com/demo/mars/').then(() => {
+  new AxeBuilder(driver).analyze((err, results) => {
     if (err) {
       // Handle error somehow
     }
@@ -36,140 +36,115 @@ driver.get('https://dequeuniversity.com/demo/mars/').then(function () {
 });
 ```
 
-### AxeBuilder(driver:WebDriver[, axeSource:string])
+## AxeBuilder(driver: Webdriver.WebDriver[, axeSource: string])
 
-Constructor for the AxeBuilder helper. You must pass an instance of selenium-webdriver as the first and only argument.
+Constructor for the AxeBuilder helper. You must pass an instance of WebdriverJS as the first argument.
 
-```javascript
-var builder = new AxeBuilder(driver);
+```js
+const builder = new AxeBuilder(driver);
 ```
 
-If you wish to run a specific version of axe-core, you can pass the source axe-core source file in as a string. Doing so will mean axe-webdriverjs runs this version of axe-core, instead of the one installed as a dependency of axe-webdriverjs.
+If you wish to run a specific version of [axe-core](https://github.com/dequelabs/axe-core), you can pass the source of axe-core source file in as a string. Doing so will mean `@axe-core/webdriverjs` run this version of axe-core, instead of the one installed as a dependency of `@axe-core/webdriverjs`.
 
-```javascript
-var axeSource = fs.readFileSync('./axe-1.0.js', 'utf8');
-var builder = new AxeBuilder(driver, axeSource);
+```js
+const axeSource = fs.readFileSync('./axe-1.0.js', 'utf-8');
+const builder = new AxeBuilder(driver, axeSource);
 ```
 
-### AxeBuilder#include(selector:String)
+### AxeBuilder#include(selector: String)
 
 Adds a CSS selector to the list of elements to include in analysis
 
-```javascript
+```js
 new AxeBuilder(driver).include('.results-panel');
 ```
 
-### AxeBuilder#exclude(selector:String)
+### AxeBuilder#exclude(selector: String)
 
 Add a CSS selector to the list of elements to exclude from analysis
 
-```javascript
-new AxeBuilder(driver).include('.results-panel').exclude('.results-panel h2');
+```js
+new AxeBuilder(driver).include('.some-element').exclude('.another-element');
 ```
 
-### AxeBuilder#options(options:Object)
+### AxeBuilder#options(options: [axe.RunOptions](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter))
 
-Specifies options to be used by `axe.a11yCheck`. **Will override any other configured options, including calls to `withRules` and `withTags`.** See [axe-core API documentation](https://github.com/dequelabs/axe-core/blob/master/doc/API.md) for information on its structure.
+Specifies options to be used by `axe.run`. Will override any other configured options. including calls to `AxeBuilder#withRules()` and `AxeBuilder#withTags()`. See [axe-core API documentation](https://github.com/dequelabs/axe-core/blob/master/doc/API.md) for information on its structure.
 
-```javascript
+```js
 new AxeBuilder(driver).options({ checks: { 'valid-lang': ['orcish'] } });
 ```
 
-### AxeBuilder#withRules(rules:Mixed)
+### AxeBuilder#withRules(rules: String|Array)
 
-Limits analysis to only those with the specified rule IDs. Accepts a String of a single rule ID or an Array of multiple rule IDs. **Subsequent calls to `AxeBuilder#options`, `AxeBuilder#withRules` or `AxeBuilder#withRules` will override specified options.**
+Limits analysis to only those with the specified rule IDs. Accepts a String of a single rule ID or an Array of multiple rule IDs. Subsequent calls to `AxeBuilder#options`, `AxeBuilder#withRules` or `AxeBuilder#withRules` will override specified options.
 
-```javascript
+```js
 new AxeBuilder(driver).withRules('html-lang');
 ```
 
-```javascript
+```js
 new AxeBuilder(driver).withRules(['html-lang', 'image-alt']);
 ```
 
-### AxeBuilder#withTags(tags:Mixed)
+### AxeBuilder#withTags(tags: String|Array)
 
-Limits analysis to only those with the specified rule IDs. Accepts a String of a single tag or an Array of multiple tags. **Subsequent calls to `AxeBuilder#options`, `AxeBuilder#withRules` or `AxeBuilder#withRules` will override specified options.**
+Limits analysis to only those with the specified rule IDs. Accepts a String of a single tag or an Array of multiple tags. Subsequent calls to `AxeBuilder#options`, `AxeBuilder#withRules` or `AxeBuilder#withRules` will override specified options.
 
-```javascript
+```js
 new AxeBuilder(driver).withTags('wcag2a');
 ```
 
-```javascript
+```js
 new AxeBuilder(driver).withTags(['wcag2a', 'wcag2aa']);
 ```
 
-### AxeBuilder#disableRules(rules:Mixed)
+### AxeBuilder#disableRules(rules: String|Array)
 
-Skips verification of the rules provided. Accepts a String of a single rule ID or an Array of multiple rule IDs. **Subsequent calls to `AxeBuilder#options`, `AxeBuilder#disableRules` will override specified options.**
+Skips verification of the rules provided. Accepts a String of a single rule ID or an Array of multiple rule IDs. Subsequent calls to `AxeBuilder#options`, `AxeBuilder#disableRules` will override specified options.
 
-```javascript
+```js
 new AxeBuilder(driver).disableRules('color-contrast');
 ```
 
-or use it combined with some specified tags:
+### AxeBuilder#configure(config: [axe.Spec](https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure))
 
-```javascript
-new AxeBuilder(driver)
-  .withTags(['wcag2a', 'wcag2aa'])
-  .disableRules('color-contrast');
-```
-
-### AxeBuilder#configure(config:Object)
-
-Inject an aXe configuration object to modify the ruleset before running Analyze. Subsequent calls to this
-method will invalidate previous ones by calling `axe.configure` and replacing the config object. See
-[axe-core API documentation](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure)
-for documentation on the object structure.
+Inject an axe configuration object to modify the ruleset before running Analyze. Subsequent calls to this method will invalidate previous ones by calling `axe.configure` and replacing the config object. See [axe-core API documentation](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axeconfigure) for documentation on the object structure.
 
-```javascript
-var config = {
-  checks: [Object],
-  rules: [Object]
-};
+```js
+const config = {
+  checks: axe.Check[],
+  rules: axe.Rule[]
+}
 
-new AxeBuilder(driver).configure(config).analyze(function (err, results) {
+new AxeBuilder(driver).configure(config).analyze((err, results) => {
   if (err) {
     // Handle error somehow
   }
-  console.log(results);
-});
+  console.log(results)
+})
 ```
 
-### AxeBuilder#analyze(callback:Function)
+### AxeBuilder#analyze(): Promise<axe.Results>
 
-Performs analysis and passes any encountered error and/or the result object to the provided callback function or promise function. **Does not chain as the operation is asynchronous**
+Performs analysis and passes any encountered error and/or the result object.
 
-```javascript
-new AxeBuilder(driver).analyze(function (err, results) {
+```js
+new AxeBuilder(driver).analyze((err, results) => {
   if (err) {
-    // Handle error somehow
+    // Do something with error
   }
   console.log(results);
 });
 ```
 
-Using the returned promise (optional):
-
-```javascript
+```js
 new AxeBuilder(driver)
   .analyze()
-  .then(function (results) {
+  .then(results => {
     console.log(results);
   })
-  .catch(err => {
-    // Handle error somehow
+  .catch(e => {
+    // Do something with error
   });
 ```
-
-## Examples
-
-This project has a couple integrations that demonstrate the ability and use of this module:
-
-1. [Running a single rule](test/integration/doc-lang.js)
-1. [Running against a page with frames](test/integration/frames.js)
-1. [SauceLabs example](test/sauce/sauce.js)
-
-## Contributing
-
-Read the [documentation on contributing](CONTRIBUTING.md)

packages/webdriverjs/example-with-callback.js

@@ -0,0 +1,15 @@
+const AxeBuilder = require('@axe-core/webdriverjs');
+const WebDriver = require('selenium-webdriver');
+
+const driver = new WebDriver.Builder().forBrowser('chrome').build();
+
+driver.get('https://html5-sandbox.glitch.me/').then(() => {
+  const axe = new AxeBuilder(driver, null, { noSandbox: true });
+  axe.analyze(async (err, results) => {
+    if (err) {
+      // Handle error somehow
+    }
+    console.log(results);
+    await driver.quit();
+  });
+});

packages/webdriverjs/example.js

@@ -1,13 +1,13 @@
-const AxeBuilder = require('./lib');
+const AxeBuilder = require('@axe-core/webdriverjs');
 const WebDriver = require('selenium-webdriver');
 
-const driver = new WebDriver.Builder().forBrowser('chrome').build();
-driver.get('https://html5-sandbox.glitch.me/').then(function () {
-  const axe = new AxeBuilder(driver, null, { noSandbox: true });
-  axe.analyze(function (err, results) {
-    if (err) {
-      // Handle error somehow
-    }
-    console.log(results);
-  });
-});
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+(async () => {
+  const driver = new WebDriver.Builder().forBrowser('chrome').build();
+  await driver.get('https://html5-sandbox.glitch.me/');
+  const results = await new AxeBuilder(driver, null, {
+    noSandbox: true
+  }).analyze();
+  console.log(results);
+  await driver.quit();
+})();