# AxeService for WebdriverIO

A WebdriverIO service that integrates axe-core accessibility testing into your test automation framework.

## Overview

AxeService provides a seamless way to incorporate accessibility testing into your WebdriverIO test suite. It adds a custom `browser.runAxe()` command that runs accessibility tests on your web pages and generates detailed reports.

## Configuration

Add the AxeService to your conf file:

```javascript
import AxeService from './services/AxeService.js';

export const config = {
  // ...
  services: [
    [AxeService, {
      // Configuration options (see below)
    }]
  ],
  // ...
};
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `showSections` | Object | See below | Controls which sections appear in the HTML report |
| `attachReports` | Object | See below | Controls which report formats are attached to Allure |
| `failOnAccessibility` | Object | `undefined` | Optional configuration to fail tests based on accessibility issues |

### Default Options

```javascript
{
  // By default, only show violations and incomplete results
  showSections: {
    violations: true,
    incomplete: true,
    passes: false,
    inapplicable: false
  },
  // Configure which report formats to attach
  attachReports: {
    html: true,  // HTML report enabled by default
    json: false  // JSON report disabled by default
  }
  // All failure criteria are disabled by default
}
```

### Failing Tests on Accessibility Issues

To configure the service to fail tests when accessibility issues are found:

```javascript
{
  failOnAccessibility: {
    violations: {
      thresholds: {
        critical: 0,  // Fail on any critical violations
        serious: 0,   // Fail on any serious violations
        moderate: 5,  // Allow up to 5 moderate violations
        minor: 10     // Allow up to 10 minor violations
      }
    },
    incomplete: {
      thresholds: {
        critical: 0,  // Fail on any critical incomplete checks
        serious: 5    // Allow up to 5 serious incomplete checks
      }
    }
  }
}
```

## Usage

Once configured, you can use the `browser.runAxe()` command in your tests:

```javascript
describe('Accessibility testing', () => {
  it('should check accessibility on the homepage', async () => {
    await browser.url('/');
    const results = await browser.runAxe();
    
    // You can also make assertions on the results if needed
    // the results are returned in the results object
    // If the test fails, in the runAxe command the //
    // assertion below will fail as no result will be returned
    expect(results.violations.length).toBe(0);
  });
});
```

### Advanced Usage

You can customize the axe analysis with options:

```javascript
const results = await browser.runAxe({
  // Only test specific elements
  include: ['.main-content', 'header'],
  
  // Exclude elements from testing
  exclude: ['.ad-banner', '.cookie-notice'],
  
  // Only run rules with specific tags
  withTags: ['wcag2a', 'wcag2aa'],
  
  // Disable specific rules
  disableRules: ['color-contrast'],
  
  // Enable specific rules
  enableRules: ['landmark-one-main']
});
```

## Reports

The service automatically attaches accessibility reports to your Allure test results:

1. **HTML Report**: A detailed, interactive report showing all accessibility issues with filtering options
2. **JSON Report** (optional): Raw JSON data for further processing

## Features

- Integrates seamlessly with WebdriverIO and Allure reporting
- Provides detailed HTML reports with filtering by impact, type, and tags
- Supports failing tests based on configurable thresholds
- Includes XPath expressions for all elements with issues for easier debugging
- Allows customization of which axe rules to run

## Example HTML Report

The HTML report includes:
- Summary of violations, passes, incomplete, and inapplicable tests
- Filtering by impact level, result type, and tags
- Detailed information about each issue including:
  - HTML snippets
  - CSS selectors
  - XPath expressions
  - Failure summaries
  - Links to learn more about each rule

## Best Practices

1. Start with baseline testing to understand your current accessibility status
2. Gradually tighten thresholds as you fix issues
3. Focus on critical and serious issues first
4. Include accessibility testing in your CI/CD pipeline