Set Timeouts

When running accessibility tests with Axe Watcher, you may encounter timeouts, especially on complex pages, over slow networks, or in CI/CD environments with limited resources. This guide explains how to configure timeout values to ensure your tests complete successfully.

Understanding Watcher Timeouts

Axe Watcher communicates with Deque's servers during test runs and performs analysis operations that can vary in duration depending on page complexity. Four operations have configurable timeouts:

• analyze: Time allowed for analyzing a page's accessibility (default: 5000ms)
• flush: Time allowed for sending results to Axe Developer Hub (default: 5000ms)
• start: Time allowed for resuming auto-analysis (default: 2000ms)
• stop: Time allowed for pausing auto-analysis (default: 5000ms)

If you encounter timeout errors with Watcher, you'll see a message similar to:

Error: Watcher could not send results to the server. To resolve this problem, adjust your `timeout.flush` property within your configuration or see [Troubleshooting](https://docs.deque.com/devtools-for-web/wa-troubleshooting) for more troubleshooting guidance.

JavaScript and TypeScript Configuration

For JavaScript and TypeScript projects using the @axe-core/watcher package, you can configure timeouts through the timeout property in your AxeConfiguration object.

Basic Timeout Configuration

const config = playwrightConfig({
  axe: {
    apiKey: process.env.API_KEY,
    projectId: process.env.PROJECT_ID,
    timeout: {
      analyze: 10000,  // 10 seconds
      flush: 15000,    // 15 seconds
      start: 5000,     // 5 seconds
      stop: 10000      // 10 seconds
    }
  }
});

You only need to specify the timeouts you want to override; any omitted values use their defaults.

Important Considerations for JavaScript/TypeScript

Watcher's timeout values are independent of your test framework's own timeouts. If you're seeing timeout failures, you may need to adjust both. The example below shows how to set Playwright's timeout to match Watcher's.

// In your Watcher config
timeout: {
  analyze: 45000,
  flush: 20000
}

// Adjust the timeout for a single Playwright test.
test('basic functionality test', async ({ page }) => {
  test.setTimeout(45000);
  // ...
});

If you're chaining commands, ensure your overall test timeout accounts for the total duration of operations.

Java Configuration

Java Watcher does not currently support custom timeouts. The timeout values are set in the Java implementation to the initial JavaScript/TypeScript values.

Workarounds for Java Timeout Issues

While you cannot directly configure timeouts in Java, consider these approaches:

1. Optimize page complexity: If pages consistently time out during analysis, consider breaking tests into smaller, more focused test cases that analyze fewer page states.

2. Check network conditions: Ensure stable network connectivity between your test environment and Deque's servers, particularly in CI/CD pipelines.

3. Contact Deque support: If timeout issues persist, reach out to Deque's support team, as future versions of Java Watcher may include configurable timeouts.

When to Increase Timeouts

Consider increasing timeout values when:

• Testing pages with large DOM structures (thousands of elements)
• Running tests in resource-constrained CI/CD environments
• Testing over high-latency network connections
• Analyzing pages with complex DOMs
• Running multiple parallel test processes

Troubleshooting Timeout Errors

If you're experiencing timeout errors:

1. Identify which operation is timing out: The error message indicates whether it's analyze, flush, start, or stop.

2. Check for other issues: Timeouts can sometimes indicate underlying problems like network issues, misconfigured proxies, or pages that fail to fully load.

3. Review the troubleshooting guide: See Troubleshooting for additional guidance.

Summary

For JavaScript and TypeScript projects, configuring appropriate timeouts ensures reliable test execution across environments. Java users should focus on optimizing test structure and network conditions.