E2E test frameworks
Playwright
Background Runner

Background Runner

UserWay Background Runner is a tool that simplifies adding UserWay accessibility analysis to your existing Playwright or Playwright-test E2E tests.

Once enabled, the Background Runner implicitly analyzes your pages while tests are running, without requiring changes to your test logic. It watches your Playwright page object and automatically triggers accessibility analysis whenever you perform actions that can impact the page's content or appearance, such as clicking a button or navigating between pages.

Why using Background Runner?

If you have a large number of E2E tests, manually adding UserWay analysis after each action (e.g., clicks, form submissions, or navigation) becomes time-consuming. The Background Runner eliminates this effort by automatically performing the analysis after each significant action, saving you time and ensuring comprehensive accessibility checks without modifying each individual test.

Usage

To configure the Background Runner, follow these steps:

  1. Set up a global configuration for all UserWay accessibility analyses that will run in the background before all your tests.

  2. For every new Playwright page instance, wrap it with our proxy by calling the makeAnalysisController method, which wraps the page and manages the controller.

  3. Enable Background Runner for test you wish. By default Background Runner is disable.

Example

The Background Runner should be configured and enabled before all tests For this, we can use beforeAll hooks. We use vitest but you can use other tools.

import { beforeAll, describe, test, expect } from 'vitest'
import * as playwright from 'playwright'
import {
  UserwayController,
  makeAnalysisController,
} from '@userway/a11y-playwright-test'
 
describe('My accessibility test suite', () => {
  let page: playwright.Page
  let controller: UserwayController
 
  beforeAll(async () => {
    const browserContext = await playwright.chromium.launchPersistentContext('')
 
    const basePage = await browserContext.newPage()
 
    const a11ySetup = await makeAnalysisController(
      { switchOff: false },
      basePage,
    )
 
    page = a11ySetup.page
    controller = a11ySetup.controller
    await controller.start()
  })
 
  test('should trigger analysis after user actions', async () => {
    await page.goto('https://example.com')
  })
})

Now that the Background Runner is set up, you can modify your test cases to use the proxied page and let the runner handle the analysis implicitly:

test('Example Test', async () => {
  await page.goto('https://example.com');
  await page.click('button'); // The Background Runner will automatically trigger analysis after this action.
});

Playwright-test Integration

If you're using Playwright-test, you can integrate the Background Runner into the fixture system to automatically wrap the page and manage accessibility analysis for each test:

import { makeA11yFixture } from '@userway/a11y-playwright-test'
 
const { test } = makeA11yFixture({
  switchOff: false,
})
 
test.describe('My accessibility test suite', () => {
  test.beforeEach(async ({ userwayController }) => {
    await userwayController.start()
  })
 
  test('should trigger analysis after user actions', async ({ page }) => {
    await page.goto('https://example.com')
    await page.click('.btn') // Analysis is automatically triggered after this action
  })
})

This setup ensures that the Background Runner is active throughout the test lifecycle and performs a final analysis once the test is fully rendered, ensuring accurate accessibility checks.

APIGetting started