Setting Up and Configuring Browsers for Use with Axe Watcher

Axe Watcher supports the following browsers:

• Google Chrome for Testing
• Chromium
• Microsoft Edge (JavaScript/TypeScript or Java with Playwright; not supported with Java Selenium)

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 JavaScript/TypeScript and with Java Playwright; it is not supported with Java Selenium. 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 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());