Controlling Page Analysis

Normally, axe Developer Hub automatically analyzes each page visited by your test suite (known as automatic mode). Sometimes, this automatic analysis results in too many pages being analyzed, pages you don't care about being analyzed, or pages that belong to other departments in your organization--pages that your team has no ownership over--being analyzed. You can disable automatic mode, so you determine when (or whether) to analyze each page (known as manual mode).

Scenarios

Scanning Parts of a Website

You can use manual mode to scan only part of a website. For instance, if your team owns the shopping cart functionality on your site, but your test suite needs to visit catalog pages (which your team doesn't own) to add products to the cart, you likely want to avoid testing the accessibility of the catalog pages. Once you've reached the shopping cart page in your test suite, you can re-enable automatic analysis. Then, when the shopping cart tests are complete, you can disable automatic analysis again.

Next Steps

• Disable Automatic Analysis in Configuration to avoid testing the catalog pages.
• Enable Automatic Analysis for your shopping cart page.
• Disable Automatic Analysis via a Call at the end of testing your shopping cart page to prevent pages visited after the shopping cart page from being tested.

Dynamic Content Loading

You can use manual mode to avoid testing pages with complex loading sequences. If the page you want to test dynamically loads many resources in the background, you can turn off automatic mode until it fully loads. This will limit accessibility issues to those that exist only once the page is fully loaded. It would also prevent accessibility checks during loading animations or other loading UI.

Next Steps

• Disable Automatic Analysis in Configuration so the loading animations and UI aren't tested for accessibility errors.
• Enable Automatic Analysis to resume automatic accessibility testing once the page is completely loaded.

Capturing Specific Page States

If you want to make sure a specific page state is scanned, you can manually trigger an accessibility analysis after you've set up your page.

Next Steps

• Disable Automatic Analysis in Configuration to prevent accessibility analysis from occurring before the page is in the state you require.
• Manually Analyze Pages to test the specific page state you are interested in.

Limiting Scope of a Large Test Suite

By disabling automatic analysis, you can use a larger, more comprehensive test suite but limit your accessibility testing to only one part of it. In this case, you don't need to break up your larger test suite into smaller test suites and only test accessibility in the test suites you care about.

Next Steps

• Disable Automatic Analysis in Configuration to prevent automatic accessibility analysis from starting at the beginning of your test suite.
• Enable Automatic Analysis when you reach the part of your test suite you'd like to test.
• Disable Automatic Analysis via a Call to disable accessibility testing for parts of the test suite that you do not care to test for accessibility errors.

How to Use Manual Mode

You can disable automatic analysis in your configuration (see Disable Automatic Analysis in Configuration below).

Page analysis is controlled by three methods on the Controller object or the equivalent commands in Cypress.

1. analyze() (in Cypress: cy.axeWatcherAnalyze()) to perform an analysis of the current page.
2. start() (in Cypress: cy.axeWatcherStart()) to enable automatic accessibility analysis.
3. stop() (in Cypress: cy.axeWatcherStop()) to disable automatic accessibility analysis.

Obtaining a Controller Object

For information on obtaining a Controller object, see step four of your test framework's instructions page:

JavaScript:

• Playwright
• Puppeteer
• WebdriverIO
• WebdriverIO TestRunner
• WebDriverJS

TypeScript:

• Playwright
• Puppeteer
• WebdriverIO
• WebdriverIO TestRunner
• WebDriverJS

Cypress

For Cypress, you can use the global cy object with these equivalent commands:

Playwright Test

For Playwright Test, the Controller object (PlaywrightController) can be obtained from page, which contains an axeWatcher object. You can use the axeWatcher object to invoke the Controller methods (example below is in TypeScript):

import { test, expect } from './fixtures'

test('example test', async ({ page }) => {
  await page.goto('https://example.com')
  await page.axeWatcher.analyze()
})

Disable Automatic Analysis in Configuration

When you modified your test suite to add accessibility testing, you needed to create a axe configuration object. You can disable automatic accessibility testing by setting autoAnalyze to false in your axe object.

For example, you set autoAnalyze to false in your configuration (the line is highlighted in the Cypress JavaScript sample below):

const { defineConfig } = require('cypress');
const { cypressConfig } = require('@axe-core/watcher');

const API_KEY = process.env.API_KEY

module.exports = defineConfig(  
  cypressConfig({
    axe: {
      apiKey: API_KEY,
      autoAnalyze: false    },
    // Your existing Cypress configuration code here
  })
);

Disable Automatic Analysis via a Call

With Cypress, you can use the axeWatcherStop() command:

cy.axeWatcherStop()

The other test integrations use the stop() method on your Controller object:

await controller.stop()

See Obtaining a Controller Object for more information about obtaining a controller object for your test framework.

Manually Analyze Pages

After you've disabled automatic analysis, you can add calls to axeWatcherAnalyze() (for Cypress) or analyze() (with the other test integrations). For example, in Cypress:

describe('My Login Application', () => {
  it('should login with valid credentials', () => {
    cy.visit('https://the-internet.herokuapp.com/login')
      // Analyze the page.
      .axeWatcherAnalyze()      .get('#username')
      .type('tomsmith')
      .get('#password')
      .type('SuperSecretPassword!')
      .get('button[type="submit"]')
      .click()
      .wait(1000)
      // Analyze the page.
      .axeWatcherAnalyze()      // Restart automatic axe analysis.
      .axeWatcherStart()
      .get('#flash')
      .should('exist')
  })
})

See Obtaining a Controller Object for more information about obtaining a controller object for your test framework.

Enable Automatic Analysis

With Cypress, you can use the axeWatcherStart command:

cy.axeWatcherStart()

The other test integrations use the start method on your Controller object:

await controller.start()

See Obtaining a Controller Object for more information about obtaining a controller object for your test framework.

See Also

• For two working examples of manual mode tests (for Cypress and Playwright), see the following examples in the watcher-examples repo on GitHub:
  • For Cypress, see Cypress manual-mode
  • For Playwright, see Playwright manual-mode
• In the API Reference, you can find reference information about all of the APIs provided by the @axe-core/watcher package.