Writing Tests for Axe DevTools for Web for Playwright

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard

How to write effective tests for accessibility using Axe DevTools for Web for Playwright

Not for use with personal data

Writing tests with Axe DevTools

Producing accessibility scan results with Axe DevTools can be as easy as one line of code. These results can be consumed raw, used in conjunction with an assertion library, or used to create accessibility reports.

The individual snippets in the sections below are JavaScript, and they compile unchanged in TypeScript. The Complete Sample File section gives the full test in both languages.

Prerequisites

In order to import and initialize Axe DevTools for Web it needs to be installed first. If you haven't yet, read the guide on how to install it from a bundle, from your artifact repository, or from Deque's Agora. You also need a downloaded and configured Playwright version of your choice.

Importing and Initializing

Import both Axe DevTools for Web and Playwright. The syntax depends on the language and module system your project uses. Pick the one that matches your project:

JavaScript with CommonJS modules

This is the default for a Node.js project without "type": "module" in its package.json.

const { AxeDevToolsBuilder } = require('@axe-devtools/playwright');
const playwright = require('playwright');

JavaScript with ES modules

Use this syntax in a project with "type": "module" in its package.json, or in .mjs files.

import { AxeDevToolsBuilder } from '@axe-devtools/playwright';
import * as playwright from 'playwright';

TypeScript

TypeScript uses the same import syntax as ES modules. @axe-devtools/playwright ships its own type declarations, so there is no separate @types/ package to install. Scan results are typed as AxeResults, which axe-core exports:

import { AxeDevToolsBuilder } from '@axe-devtools/playwright';
import * as playwright from 'playwright';
import type { AxeResults } from 'axe-core';

Initializing Playwright

Once you've imported Axe DevTools for Web, you can initialize the driver. Each scan requires its own instance of Axe DevTools for Web, so you'll initialize that while writing tests.

The initialization code is the same in JavaScript and TypeScript, except that TypeScript can infer or annotate the types Playwright returns. In JavaScript:

// This will open up a headless instance of chromium
const browser = await playwright.chromium.launch();
const context = await browser.newContext();
const page = await context.newPage();

In TypeScript, with the types written out:

import type { Browser, BrowserContext, Page } from 'playwright';

// This will open up a headless instance of chromium
const browser: Browser = await playwright.chromium.launch();
const context: BrowserContext = await browser.newContext();
const page: Page = await context.newPage();

Getting Scan Context

Before you can scan a page for accessibility, it needs to be accessed by Playwright.

//Launch the Playwright Driver
const browser = await playwright.chromium.launch();
//Create a new browser context
const context = await browser.newContext();
//Create a new page in the browser
const page = await context.newPage();
//Send the browser to the desired page to scan
await page.goto('$URL');

Bypassing Content Security Policy

If the page you are trying to scan has Content Security Policy enabled, you may have issues. If you encounter this problem, Axe DevTools includes a workaround. Simply include this statement after your page is created:

await context = await browser.newContext({ bypassCSP: true })

Once Playwright has accessed the page, you can scan it with Axe DevTools and save the results. The most simple way to view the results of the scan is to console log the results object.

const results = await new AxeDevToolsBuilder({ page }).analyze();
console.log(results);

Complete Sample File

The same test is shown below in JavaScript and in TypeScript. The Axe DevTools API is identical in both; the TypeScript version uses import syntax and annotates the values Playwright and the scan return.

JavaScript

const playwright = require('playwright');
const { AxeDevToolsBuilder } = require('@axe-devtools/playwright');

(async () => {

    //Launch the Playwright Driver
    const browser = await playwright.chromium.launch();
    //Create a new browser context
    const context = await browser.newContext();
    //Create a new page in the browser
    const page = await context.newPage();

    //launch page for testing (has intentional accessibility issues)
    await page.goto('https://broken-workshop.dequelabs.com');

    //analyze page
    const results = await new AxeDevToolsBuilder({ page }).analyze();
    
    //log results
    console.log(results);

    //close webdriver
    browser.close();
})();

TypeScript

import * as playwright from 'playwright';
import type { Browser, BrowserContext, Page } from 'playwright';
import { AxeDevToolsBuilder } from '@axe-devtools/playwright';
import type { AxeResults } from 'axe-core';

(async () => {

    //Launch the Playwright Driver
    const browser: Browser = await playwright.chromium.launch();
    //Create a new browser context
    const context: BrowserContext = await browser.newContext();
    //Create a new page in the browser
    const page: Page = await context.newPage();

    //launch page for testing (has intentional accessibility issues)
    await page.goto('https://broken-workshop.dequelabs.com');

    //analyze page
    const results: AxeResults = await new AxeDevToolsBuilder({ page }).analyze();

    //log results
    console.log(results);

    //close webdriver
    await browser.close();
})();

Next Steps

Now that you've successfully completed an accessibility scan, you're ready to move on to more advanced scanning topics like generating reports and using the results object.

Troubleshooting

If you have trouble with getting scan results, contact your Deque representative directly, reach us via our support desk, or send us an email. We'll be happy to help.

Is this page helpful?

Help us improve this page

Still need help?