How to Troubleshoot Problems

Results Not Appearing in the Dashboard

If you've run your test suite and no results are showing up in the axe Developer Hub dashboard for a certain project, the cause could be found among the reasons in the following sections.

Failing to Flush Results with axeFlush()

You need to call the axeFlush() function to send the collected results back to Deque's servers so the results can be presented on the dashboard. Usually, you call cy.axeFlush() in the afterEach() function in Cypress.

For example, in the support/e2e.js file in Cypress:

// Flush axe-watcher results after each test.
afterEach(() => {
  cy.axeFlush()
})

Manual Mode and No Calls to axeAnalyze()

If you have set your test to manual mode, you need to call the axeAnalyze() function to whenever you want to check the page for accessibility defects. Otherwise the page is never checked.

Incorrect Server

The default server URL for axe Developer Hub is https://axe.deque.com, but if you are in a beta program or other testing program, you may need to change the name of your server in your config. (You can contact help@deque.com for server information.)

With Cypress, to change the name of the server, add the server URL to your cypress.config.js, as shown in the highlighted line below:

const { defineConfig } = require("cypress");
const { cypressConfig } = require("@axe-core/watcher");

module.exports = defineConfig(
  cypressConfig({
    axe: {
      apiKey: "2a343319-86ad-4857-b23d-79da58b7a0b4",
      serverURL: "https://axe.deque.com"    },
  })
);

If you have the wrong server set, you should receive an error message when you run your tests that indicate that the project cannot be found (if a server can be contacted).

Not Setting the Required Environment Variables

Instead of requiring changes to your config file as showing in the last section, the samples in the axe Developer Hub sample repository on GitHub use environment variables instead for setting the API key and server URL:

• API_KEY
• SERVER_URL

You can either set them in the environment or specify them on the command line when running tests.

Not Using an Encrypted Connection

Make sure you use https instead of http in the server's URL.

Test Running Too Quickly

Your tests might run too quickly and unload the page and free up its resources before the page can be analyzed. To fix this problem, you can add a delay at the end of the test to allow time to analyze the page.

For example, in Cypress you can add a delay of 10 seconds (10,000 milliseconds) with the cy.wait() method:

describe('Visitor', () => {
  it('should visit example.com', () => {
    cy.visit('https://www.example.com')
    cy.wait(10000);  })
})

Missing or Invalid API Key

An invalid or missing API key appears as an invalid configuration file in Cypress. The stack trace will reveal whether it is invalid or missing. A missing key results in the following:

AssertionError [ERR_ASSERTION]: API key is required
    at validateApiKey ...

(Many lines of the stack trace were deleted for brevity.)

An invalid key results in the following stack trace (shorted):

Error: Server responded to https://axe.dequelabs.com/api/api-keys/test/validate/axe-devtools-watcher with status code 404:
{"error":"Invalid API key"}
    at Response.getBody
...