Update docs and types for axe commands. (#3996)

nightwatchjs · Jan 24, 2024 · 98c4c44 · 98c4c44
1 parent c5331d2
commit 98c4c44
Show file tree

Hide file tree

Showing 4 changed files with 66 additions and 68 deletions.
diff --git a/lib/api/client-commands/axeInject.js b/lib/api/client-commands/axeInject.js
@@ -1,10 +1,10 @@
 /**
- * Injects the [axe-core](https://github.com/dequelabs/axe-core) js library into the current page (using the .executeScript() command).
+ * Injects the [axe-core](https://github.com/dequelabs/axe-core) js library into the current page (using the `.executeScript()` command).
+ * To be paired with `.axeRun()` to evaluate the axe-core accessibility rules.
  *
  * @example
- * describe('accessibility testing', function() {
- *
- *   it('accessibility rule subset', function(browser) {
+ * describe('accessibility testing', function () {
+ *   it('accessibility rule subset', function (browser) {
  *     browser
  *       .url('https://www.w3.org/WAI/demos/bad/after/home.html')
  *       .assert.titleEquals('Welcome to CityLights! [Accessible Home Page]')
@@ -13,10 +13,9 @@
  *         runOnly: ['color-contrast', 'image-alt'],
  *       });
  *   });
- * })
+ * });
  *
  * @method axeInject
- * @link https://github.com/dequelabs/axe-core
  * @syntax browser.axeInject()
  * @api protocol.accessibility
  * @since 2.3.6

diff --git a/lib/api/client-commands/axeRun.js b/lib/api/client-commands/axeRun.js
@@ -2,9 +2,8 @@
  * Analyzes the current page against applied axe rules.
  *
  * @example
- * describe('accessibility testing', function() {
- *
- *   it('accessibility rule subset', function(browser) {
+ * describe('accessibility testing', function () {
+ *   it('accessibility rule subset', function (browser) {
  *     browser
  *       .url('https://www.w3.org/WAI/demos/bad/after/home.html')
  *       .assert.titleEquals('Welcome to CityLights! [Accessible Home Page]')
@@ -13,17 +12,16 @@
  *         runOnly: ['color-contrast', 'image-alt'],
  *       });
  *   });
- * })
+ * });
  *
  * @method axeRun
- * @link https://github.com/dequelabs/axe-core
  * @syntax browser.axeRun('body')
- * @param {string} selector The CSS selector used to locate the element.
- * @param {object} options Object containing rules configuration to use when performing the analysis
- * @see https://www.deque.com/axe/core-documentation/api-documentation/#options-parameter
- * @param {function} [callback] Optional callback function which is called with the results
+ * @param {*} [context] Defines the scope of the analysis, will cascade to child elements. See [axe-core docs](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#context-parameter) for more details.
+ * @param {object} [options] Object containing rules configuration to use when performing the analysis. See [axe-core docs](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#options-parameter) for more details.
+ * @param {function} [callback] Optional callback function which is called with the results.
  * @api protocol.accessibility
  * @since 2.3.6
+ * @see https://www.deque.com/axe/core-documentation/api-documentation/#api-name-axerun
  */
 module.exports = class AxeInject {
   static get allowOverride() {

diff --git a/types/index.d.ts b/types/index.d.ts
@@ -2516,16 +2516,21 @@ export interface ClientCommands extends ChromiumClientCommands {
   ): Awaitable<this, undefined>;
 
   /**
-   * Injects the axe-core js library into the current page (using the .executeScript() command) to be paired
-   * with axeRun to evaluate the axe-core accessibility rules.
+   * Injects the [axe-core](https://github.com/dequelabs/axe-core) js library into the current page (using the `.executeScript()` command).
+   * To be paired with `.axeRun()` to evaluate the axe-core accessibility rules.
    *
    * @example
-   * this.demoTest = function () {
-   *   browser
-   *     .url('https://nightwatchjs.org')
-   *     .axeInject()
-   *     .axeRun();
-   * };
+   * describe('accessibility testing', function () {
+   *   it('accessibility rule subset', function (browser) {
+   *     browser
+   *       .url('https://www.w3.org/WAI/demos/bad/after/home.html')
+   *       .assert.titleEquals('Welcome to CityLights! [Accessible Home Page]')
+   *       .axeInject()
+   *       .axeRun('body', {
+   *         runOnly: ['color-contrast', 'image-alt'],
+   *       });
+   *   });
+   * });
    *
    * @see https://nightwatchjs.org/api/axeInject.html
    */
@@ -2535,46 +2540,46 @@ export interface ClientCommands extends ChromiumClientCommands {
    * Analyzes the current page against applied axe rules.
    *
    * @example
-   * this.demoTest = function () {
-   *   browser
-   *     .url('https://nightwatchjs.org')
-   *     .axeInject()
-   *     .axeRun(
-   *        'body',
-   *        { runOnly: ['color-contrast', 'image-alt'] }
-   *     );
-   * };
-   *
-   * @example
-   * this.demoTest = function () {
-   *   browser
-   *     .url('https://nightwatchjs.org')
-   *     .axeInject()
-   *     .axeRun(
-   *        'body',
-   *        {
-   *          'color-contrast': {
-   *             enabled: false
-   *            }
-   *          },
-   *        }
-   *     );
-   * };
+   * describe('accessibility testing', function () {
+   *   it('accessibility rule subset', function (browser) {
+   *     browser
+   *       .url('https://www.w3.org/WAI/demos/bad/after/home.html')
+   *       .assert.titleEquals('Welcome to CityLights! [Accessible Home Page]')
+   *       .axeInject()
+   *       .axeRun('body', {
+   *         runOnly: ['color-contrast', 'image-alt'],
+   *       });
+   *   });
+   * 
+   *   it('accessibility rule subset 2', function (browser) {
+   *     browser
+   *       .url('https://nightwatchjs.org')
+   *       .axeInject()
+   *       .axeRun(['#navBar', 'nav'], {
+   *         rules: {
+   *           'color-contrast': { enabled: false },
+   *         }
+   *       });
+   *   });
+   * });
    *
-   * @param selector - CSS selector to scope rule analysis against, will cascade to child elements
-   * @param options - Allows configuration of what rules will be run (accessibility standard or rules to enable/disable)
-   * @see {@link https://www.deque.com/axe/core-documentation/api-documentation/#options-parameter}
+   * @param context - Defines the scope of the analysis, will cascade to child elements. See
+   * [axe-core docs](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#context-parameter) for more details.
+   * @param options - Allows configuration of what rules will be run (accessibility standard or rules to enable/disable).
+   * See [axe-core docs](https://www.deque.com/axe/core-documentation/api-documentation/#options-parameter) for more details.
+   * @param callback - Optional callback function which is called with the results.
    *
    * @see {@link https://nightwatchjs.org/api/axeRun.html}
+   * @see {@link https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axerun}
    */
   axeRun(
-    selector?: string,
+    context?: unknown,
     options?: { [key: string]: any },
     callback?: (
       this: NightwatchAPI,
-      result: NightwatchCallbackResult<null>
+      result: NightwatchCallbackResult<{[key: string]: any}>
     ) => void
-  ): Awaitable<this, null>;
+  ): Awaitable<this, {[key: string]: any}>;
 }
 
 export interface ElementCommands {

diff --git a/types/tests/index.test-d.ts b/types/tests/index.test-d.ts
@@ -123,22 +123,18 @@ const testGeneral: NightwatchTests = {
 
   'Can run accessibility tests': () => {
     browser
-      .url('https://www.google.com')
+      .url('https://nightwatchjs.org')
       .axeInject()
-      .axeRun(
-        'body',
-        {
-          rules: {
-            'color-contrast': {
-              enabled: false,
-            },
-            region: {
-              enabled: false,
-            },
-          },
+      .axeRun(['#navBar', 'nav'], {
+        rules: {
+          'color-contrast': { enabled: false },
+          region: { enabled: false }
         },
-        (results) => {}
-      );
+      }, (result) => {
+        if (result.status === 0) {
+          expectType<{[key: string]: any}>(result.value);
+        }
+      });
   },
 
   'step one: navigate to google': () => {