refactor(webdriverio): rewrite webdriverio to TS (dequelabs#196)

.circleci/config.yml

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

.github/axe-linter.yml

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

packages/webdriverio/.eslintrc.js

@@ -1,14 +1,9 @@
 module.exports = {
-  rules: {
-    '@typescript-eslint/no-empty-function': 'off',
-    'prefer-spread': 'off',
-    'prefer-rest-params': 'off'
-  },
   overrides: [
     {
-      files: 'tests/**/*.js',
-      env: {
-        jest: true
+      files: ['*.test.ts', '*.test.tsx'],
+      rules: {
+        '@typescript-eslint/no-explicit-any': 'off'
       }
     }
   ]

packages/webdriverio/README.md

@@ -1,5 +1,140 @@
 # @axe-core/webdriverio
 
-Provides bindings for axe with webdriverio
+> Provides a chainable axe API for WebdriverIO and automatically injects into all frames.
 
-Previous versions of this program were maintained at [dequelabs/axe-webdriverio](https://github.com/dequelabs/axe-webdriverio).
+## Getting Started
+
+Install [Node.js](https://docs.npmjs.com/getting-started/installing-node) if you haven't already.
+
+> Download and install any necessary browser drivers on your machine's PATH. [More on WebdriverIO setup](https://v6.webdriver.io/docs/gettingstarted.html#taking-the-first-step).
+
+Install `@axe-core/webdriverio` and its dependencies:
+
+NPM:
+
+```console
+npm install @axe-core/webdriverio
+```
+
+Yarn:
+
+```console
+yarn add @axe-core/webdriverio
+```
+
+## Usage
+
+This module uses a chainable API to assist in injecting, configuring, and analyzing axe with WebdriverIO. As such, it is required to pass an instance of WebdriverIO.
+
+Here is an example of a script that will drive WebdriverIO to a page, perform an analysis, and then log results to the console.
+
+```js
+const AxeBuilder = require('@axe-core/webdriverio').default;
+const { remote } = require('webdriverio');
+
+(async () => {
+  const client = await remote({
+    capabilities: {
+      browserName: 'firefox'
+    }
+  });
+
+  await client.url('https://dequeuniversity.com/demo/mars/');
+
+  const builder = new AxeBuilder({ client });
+  try {
+    const results = await builder.analyze();
+    console.log(results);
+  } catch (e) {
+    console.error(e);
+  }
+})();
+```
+
+## AxeBuilder({ client: WebdriverIO.BrowserObject })
+
+Constructor for the AxeBuilder helper. You must pass an instance of WebdriverIO as the first argument.
+
+```js
+const builder = new AxeBuilder({ client });
+```
+
+### AxeBuilder#include(selector: String)
+
+Adds a CSS selector to the list of elements to include in analysis
+
+```js
+new AxeBuilder({ client }).include('.results-panel');
+```
+
+### AxeBuilder#exclude(selector: String)
+
+Add a CSS selector to the list of elements to exclude from analysis
+
+```js
+new AxeBuilder({ client }).exclude('.another-element');
+```
+
+### 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.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.
+
+```js
+new AxeBuilder({ client }).options({ checks: { 'valid-lang': ['orcish'] } });
+```
+
+### 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.
+
+```js
+new AxeBuilder({ client }).withRules('html-lang');
+```
+
+```js
+new AxeBuilder({ client }).withRules(['html-lang', 'image-alt']);
+```
+
+### 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.
+
+```js
+new AxeBuilder({ client }).withTags('wcag2a');
+```
+
+```js
+new AxeBuilder({ client }).withTags(['wcag2a', 'wcag2aa']);
+```
+
+### 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.
+
+```js
+new AxeBuilder({ client }).disableRules('color-contrast');
+```
+
+### AxeBuilder#analyze(): Promise<axe.Results | Error>
+
+Performs analysis and passes any encountered error and/or the result object.
+
+```js
+new AxeBuilder({ client }).analyze((err, results) => {
+  if (err) {
+    // Do something with error
+  }
+  console.log(results);
+});
+```
+
+```js
+new AxeBuilder({ client })
+  .analyze()
+  .then(results => {
+    console.log(results);
+  })
+  .catch(e => {
+    // Do something with error
+  });
+```

packages/webdriverio/fixtures/context.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Context Test</title>
+  </head>
+  <body>
+    <h1>Context Test</h1>
+    <div class="include">include me</div>
+    <div class="exclude">exclude me</div>
+  </body>
+</html>

packages/webdriverio/fixtures/frames/bar.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Bar</title>
+  </head>
+  <body>
+    <h1>Bar</h1>
+    <iframe src="/frames/baz.html"></iframe>
+  </body>
+</html>

packages/webdriverio/fixtures/frames/baz.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Baz</title>
+  </head>
+  <body>
+    <h1>Baz</h1>
+  </body>
+</html>

packages/webdriverio/fixtures/frames/foo.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Foo</title>
+  </head>
+  <body>
+    <h1>Foo</h1>
+    <iframe src="/frames/bar.html"></iframe>
+  </body>
+</html>

packages/webdriverio/fixtures/frames/recursive.html

@@ -0,0 +1,10 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Recursive</title>
+  </head>
+  <body>
+    <h1>Recursive</h1>
+    <iframe src="/frames/recursive.html"></iframe>
+  </body>
+</html>

packages/webdriverio/fixtures/index.html

@@ -0,0 +1,6 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Test</title>
+  </head>
+</html>

packages/webdriverio/fixtures/multiple-frames.html

@@ -0,0 +1,16 @@
+<!-- this page has 3 iframes each going to same src  -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Multiple Frames</title>
+  </head>
+
+  <body>
+    <h1>this page has 3 iframes (no recursion)</h1>
+    <br /><br /><br />
+    <iframe src="/frames/baz.html"></iframe>
+    <iframe src="/frames/baz.html"></iframe>
+    <iframe src="/frames/baz.html"></iframe>
+    <iframe class="ignoredFrame" src="/frames/baz.html"></iframe>
+  </body>
+</html>

packages/webdriverio/fixtures/nested-frames.html

@@ -0,0 +1,11 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Nested Frames</title>
+  </head>
+  <body>
+    <h1>This page has nested frames!</h1>
+    <br /><br /><br />
+    <iframe src="/frames/foo.html"></iframe>
+  </body>
+</html>

packages/webdriverio/fixtures/recursive-frames.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Recursive Frames</title>
+  </head>
+  <body>
+    <h1>This page has a weird recursive frams!</h1>
+    <br /><br /><br />
+    <iframe src="/frames/baz.html"></iframe>
+    <iframe src="/frames/recursive.html"></iframe>
+  </body>
+</html>