Setting Up and Configuring Browsers for Use with Axe Watcher

Axe Watcher supports the following browsers:

• Google Chrome for Testing
• Chromium
• Microsoft Edge (with Java Selenium, Microsoft Edge requires Watcher 4.5.1 or later and Selenium 4 or later; with WebdriverIO, Microsoft Edge requires Watcher 4.6.0 or later)

Playwright and Puppeteer manage their own browser installations: they always download a Chromium version that Axe Watcher supports, so you don't need to install a browser binary yourself on those platforms. WebdriverIO, WebDriverJS, and Java Selenium instead connect to a browser already installed on the machine, so you must install a supported browser binary yourself and point your test configuration to it, as covered in the sections below.

Install Chrome for Testing or Chromium

Choose one of the following installation methods:

• Using npm: @puppeteer/browsers is a standalone browser download tool; it does not require Puppeteer to be installed in your project. To install Chrome for Testing, run:

  npx @puppeteer/browsers install chrome@stable

  To install Chromium instead, run:

  npx @puppeteer/browsers install chromium@latest

  The command prints the path to the installed binary at the end of its output, for example:

  chrome@stable /home/user/.cache/puppeteer/chrome/linux-136.0.7103.92/chrome-linux64/chrome

  Set the CHROME_PATH environment variable to that path before running your tests.

  important

  @puppeteer/browsers install downloads the browser into a subdirectory of the current working directory. Run the command from a location where a large download is appropriate, and consider adding the resulting directory to your .gitignore.

• Using GitHub Actions: Add the following step to your workflow file. To install Chrome for Testing:

  - name: Setup Chrome for Testing
    uses: browser-actions/setup-chrome@latest
    id: setup-chrome
    with:
      chrome-version: stable
      install-chromedriver: true

  To install Chromium instead, use latest for chrome-version:

  - name: Setup Chromium
    uses: browser-actions/setup-chrome@latest
    id: setup-chrome
    with:
      chrome-version: latest
      install-chromedriver: true

  In both cases, the binary path is available from the step's output:

  ${{ steps.setup-chrome.outputs.chrome-path }}

Configure Your Platform

Once CHROME_PATH is set, configure your test setup as follows.

WebdriverIO

Pass the binary path inside goog:chromeOptions in your WebdriverIO capabilities.

For the standalone package (wdioConfig()):

const browser = await remote(
  wdioConfig({
    axe: {
      apiKey: ACCESSIBILITY_API_KEY,
      projectId: PROJECT_ID
    },
    capabilities: {
      browserName: 'chrome',
      'goog:chromeOptions': {
        binary: process.env.CHROME_PATH
      }
    }
  })
)

For WDIO Testrunner (wdioTestRunner()):

export const config = wdioTestRunner({
  axe: {
    apiKey: ACCESSIBILITY_API_KEY,
    projectId: PROJECT_ID
  }
}, {
  capabilities: [{
    browserName: 'chrome',
    'goog:chromeOptions': {
      binary: process.env.CHROME_PATH
    }
  }]
})

WebDriverJS

Call webdriverConfig() first to get the Chrome options object, then set the binary path before building the browser:

const chromeOptions = webdriverConfig({
  axe: {
    apiKey: ACCESSIBILITY_API_KEY,
    projectId: PROJECT_ID
  }
})
chromeOptions.setBinaryPath(process.env.CHROME_PATH)

const browser = await new Builder()
  .forBrowser('chrome')
  .setChromeOptions(chromeOptions)
  .build()

Java Selenium

Set the binary path on ChromeOptions before calling watcher.configure():

AxeWatcherOptions options =
    new AxeWatcherOptions()
        .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
        .setProjectId(System.getenv("PROJECT_ID"));
AxeWatcher watcher = new AxeWatcher(options);
ChromeOptions chromeOptions = new ChromeOptions();
chromeOptions.setBinary(System.getenv("CHROME_PATH"));
chromeOptions = watcher.configure(chromeOptions);
WebDriver wrappedDriver = watcher.wrapDriver(new ChromeDriver(chromeOptions));

Use Microsoft Edge Instead

Microsoft Edge is supported with every Axe Watcher integration, subject to the minimum versions noted below. If Edge is already installed on the machine, no separate download is required. Configure your platform to launch Edge instead of Chrome for Testing or Chromium.

WebdriverIO with Microsoft Edge

Set browserName to MicrosoftEdge in your WebdriverIO capabilities.

For the standalone package (wdioConfig()):

const browser = await remote(
  wdioConfig({
    axe: {
      apiKey: ACCESSIBILITY_API_KEY,
      projectId: PROJECT_ID
    },
    capabilities: {
      browserName: 'MicrosoftEdge'
    }
  })
)

For WDIO Testrunner (wdioTestRunner()):

export const config = wdioTestRunner({
  axe: {
    apiKey: ACCESSIBILITY_API_KEY,
    projectId: PROJECT_ID
  }
}, {
  capabilities: [{
    browserName: 'MicrosoftEdge'
  }]
})

WebDriverJS with Microsoft Edge

Build the browser with MicrosoftEdge as the target browser:

const browser = await new Builder()
  .forBrowser('MicrosoftEdge')
  .build()

Java Selenium with Microsoft Edge

Use EdgeOptions and EdgeDriver in place of ChromeOptions and ChromeDriver. No CHROME_PATH is needed: Selenium launches the Edge installation it finds on the machine, and Selenium Manager (Selenium 4.6 and later) downloads a matching msedgedriver automatically. On earlier Selenium 4 versions, put an msedgedriver that matches your installed Edge version on your PATH.

AxeWatcherOptions options =
    new AxeWatcherOptions()
        .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
        .setProjectId(System.getenv("PROJECT_ID"));
AxeWatcher watcher = new AxeWatcher(options);
EdgeOptions edgeOptions = new EdgeOptions();
edgeOptions = watcher.configure(edgeOptions);
WebDriver wrappedDriver = watcher.wrapDriver(new EdgeDriver(edgeOptions));

To launch an Edge installation that isn't in the default location, call setBinary() on your EdgeOptions before watcher.configure(); configure() preserves the binary path you set:

EdgeOptions edgeOptions = new EdgeOptions();
edgeOptions.setBinary(System.getenv("EDGE_PATH"));
edgeOptions = watcher.configure(edgeOptions);

Java Playwright with Microsoft Edge

Playwright launches Edge through its msedge channel, so no separate binary path is needed. Set the channel to msedge on the launch options after calling watcher.configure():

AxeWatcherOptions options =
    new AxeWatcherOptions()
        .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
        .setProjectId(System.getenv("PROJECT_ID"));
AxeWatcherPlaywright watcher = new AxeWatcherPlaywright(options);
BrowserType.LaunchPersistentContextOptions launchOptions =
    watcher.configure(new BrowserType.LaunchPersistentContextOptions().setChannel("msedge"));
launchOptions.setHeadless(false);
BrowserContext context =
    playwright.chromium().launchPersistentContext(userDataDir, launchOptions);
AxeWatcherPage page = watcher.wrapPage(context.newPage());