Usage

There are two modes with which you can use @userway/a11y-webdriverio: manual and background.

Manual mode

Manual mode is done using function userwayAnalysis. It analyses the page, which is currently open on your “browser“ Object. Let’s imagine a scenario: you open a page, then call userwayAnalysis. Then if you interact with the page, making it change the layout, adding or removing elements for your final view of the page to be analyzed you need to call the function again.

Basic usage of userwayAnalysis:

describe('testing my page', () => {
  it('should pass userwayAnalysis', async () => {
    await browser.url('http://localhost:5000', {})
    await userwayAnalysis(browser, {
      screenshots: false,
    })
  })
})

The idea behind the function is that the first argument you pass is your WebdriverIO.Browser Object with the opened page, which you would like to analyze. The second argument is your config, with which you can override global config, which is created with setupUserway function.

userwayAnalysis analyzes your code and generates reports and screenshots, if you decide to use that option. It also returns analysis data, which includes your violations, full report and screenshots metadata.

The main drawback of this mode is that the function needs to be called each time after changing the page or switching to the other page, which can lead to a lot of calls.

Background mode

This mode helps you setup analyzing of your page and its changes in the background. It is done with the help of UserwayController. First you need to create it, for example, in your beforeAll block. Constructor accepts your WebdriverIO.Browser Object and config, which can override your global config, set up with setupUserway function. Then call start() method, which will enable background runner.

After the call of userwayController.start() calls of userwayAnalysis will be done in the background before calls of WebdriverIO api methods. If no page is open yet, userwayAnalysis is not run.

Basic usage of userwayController:

describe('test background runner', () => {
  before(async () => {
    userwayController = new UserwayController(browser, {
      elementScreenshots: true,
      printViolationsTable: true,
      ignoreUrls: ['http://localhost:5000'],
    })
 
    userwayController.start()
  })
 
  afterEach(async () => {
    await userwayController.analyze()
  })
 
  after(async () => {
    await userwayController.stop()
  })
 
  it('calls userway analysis', async () => {
    // analyze is not called yet
    await browser.url(returnUrl, {})
 
    // background runner is called
    await browser.setWindowSize(1000, 1000)
  })
 
  it('calls userway analysis', async () => {
    // background runner is called
    const a = $('#paragraph')
    await a.click()
  })
})

You can also setup the stop method to be called to stop the background runner. After that - analysis on the background is not called. You can also begin the analysis again just by typing in userwayController.start().

You can also use analyze method of the controller to manually call analyze. It does the same thing as userwayAnalysis, but uses the same browser object and config, passed prior to Controller constructor.

For internal usage:

You can use both modes at the same time by default, but if you would like to use only one of them, all you need to do is pass to set environment variable USERWAY_WEBDRIVERIO_MODE set to “background“ for background mode or “manual” for manual mode. This means, that if you set “background“, all calls to userwayAnalysis will not run analysis itself. Default value for USERWAY_WEBDRIVERIO_MODE is “all“, but if you assign to the variable any value other than “background“ or “manual“, it will count as “all“.