0
# Testing and Validation
1

2
Automated accessibility testing capabilities that run axe-core tests on stories, with support for different execution modes and detailed result reporting.
3

4
## Capabilities
5

6
### Accessibility Test Runner
7

8
Exported function for executing accessibility tests using axe-core.
9

10
```typescript { .api }
11
/**
12
 * Executes accessibility tests using axe-core
13
 * @param input - Optional A11yParameters for configuring the test run
14
 * @param storyId - The ID of the story being tested
15
 * @returns Promise resolving to enhanced accessibility test results
16
 */
17
function run(
18
  input?: A11yParameters, 
19
  storyId: string
20
): Promise<EnhancedResults>;
21
```
22

23
The `run` function can be imported and used directly for custom accessibility testing scenarios:
24

25
```typescript
26
import { run } from '@storybook/addon-a11y';
27

28
// Run accessibility tests programmatically
29
const results = await run(
30
  {
31
    options: {
32
      rules: {
33
        'color-contrast': { enabled: true }
34
      }
35
    }
36
  },
37
  'button--primary'
38
);
39

40
console.log('Violations:', results.violations.length);
41
```
42

43
The function is also used internally by the addon's `afterEach` hook and can be triggered manually through the addon panel.
44

45
### After Each Hook
46

47
Automated test execution hook that runs after each story renders.
48

49
```typescript { .api }
50
/**
51
 * Hook that runs accessibility tests after each story render
52
 * Automatically called by Storybook's preview system
53
 */
54
const afterEach: AfterEach<any> = async ({
55
  id: storyId,
56
  reporting,
57
  parameters,
58
  globals,
59
  viewMode,
60
}) => Promise<void>;
61
```
62

63
The `afterEach` hook automatically:
64
- Checks if accessibility testing is enabled
65
- Runs axe-core tests on the story
66
- Reports results through Storybook's reporting system
67
- Handles different test modes ('off', 'todo', 'error')
68
- Integrates with Vitest for standalone testing
69

70
### Result Enhancement
71

72
Internal utility for enhancing axe-core results with navigation links (not directly exported).
73

74
```typescript { .api }
75
/**
76
 * Internal utility that augments axe results with debuggable links for Storybook navigation
77
 * Used internally by the addon to add linkPath properties to results
78
 * @param results - Raw axe-core test results
79
 * @param storyId - The story ID for generating navigation links
80
 * @returns Enhanced results with linkPath properties
81
 */
82
// Note: This is an internal utility, not part of the public API
83
function withLinkPaths(
84
  results: AxeResults, 
85
  storyId: string
86
): EnhancedResults;
87
```
88

89
The `withLinkPaths` function is used internally to augment axe-core results with navigation links that allow users to jump directly to violations in the Storybook interface. This enhancement is applied automatically to all test results.
90

91
### Environment Detection
92

93
Exported utilities for detecting test environment and execution context.
94

95
```typescript { .api }
96
/**
97
 * Detects if running in standalone Vitest mode (outside Storybook)
98
 * @returns true if running in Vitest standalone mode
99
 */
100
function getIsVitestStandaloneRun(): boolean;
101

102
/**
103
 * Detects if running in any Vitest test mode
104
 * @returns true if running in Vitest environment
105
 */
106
function getIsVitestRunning(): boolean;
107
```
108

109
These utilities can be imported and used to adapt accessibility testing behavior based on the execution environment:
110

111
```typescript
112
import { getIsVitestStandaloneRun, getIsVitestRunning } from '@storybook/addon-a11y';
113

114
// Adapt behavior based on test environment
115
if (getIsVitestStandaloneRun()) {
116
  // Running in Vitest outside Storybook - violations should throw errors
117
  console.log('Running in Vitest standalone mode');
118
} else if (getIsVitestRunning()) {
119
  // Running in Vitest but within Storybook context
120
  console.log('Running in Vitest within Storybook');
121
} else {
122
  // Running in regular Storybook mode
123
  console.log('Running in Storybook');
124
}
125
```
126

127
These functions are used internally by the addon to detect test environments and adjust behavior accordingly. In Vitest standalone mode, accessibility violations will throw errors to properly fail tests.
128

129
## Enhanced Result Types
130

131
### Enhanced Results
132

133
Extended axe-core results with additional metadata and navigation links.
134

135
```typescript { .api }
136
interface EnhancedResults extends Omit<AxeResults, 'incomplete' | 'passes' | 'violations'> {
137
  incomplete: EnhancedResult[];
138
  passes: EnhancedResult[];
139
  violations: EnhancedResult[];
140
}
141

142
interface EnhancedResult extends Omit<Result, 'nodes'> {
143
  nodes: EnhancedNodeResult[];
144
}
145

146
interface EnhancedNodeResult extends NodeResult {
147
  linkPath: string;
148
}
149
```
150

151
### A11Y Report
152

153
Union type representing the result of accessibility testing.
154

155
```typescript { .api }
156
type A11YReport = EnhancedResults | { error: Error };
157
```
158

159
## Test Integration
160

161
### Storybook Integration
162

163
The addon integrates seamlessly with Storybook's testing infrastructure:
164

165
- **Automatic Execution**: Tests run automatically when stories are rendered
166
- **Reporting Integration**: Results are reported through Storybook's reporting system
167
- **Panel Integration**: Results are displayed in the accessibility panel
168
- **Story Navigation**: Violations include links to navigate to specific story elements
169

170
### Vitest Integration
171

172
Special handling for Vitest test environments:
173

174
- **Standalone Mode**: When running outside Storybook, violations throw errors to fail tests
175
- **Matcher Extensions**: Automatically extends Vitest expectations with `toHaveNoViolations` matcher
176
- **Error Propagation**: Accessibility violations properly fail test suites
177

178
**Example Vitest Integration:**
179

180
```typescript
181
// vitest.config.ts
182
import { defineConfig } from 'vitest/config';
183

184
export default defineConfig({
185
  test: {
186
    environment: 'jsdom',
187
  },
188
});
189

190
// test file
191
import { expect } from 'vitest';
192
import { run, getIsVitestStandaloneRun } from '@storybook/addon-a11y';
193

194
test('component has no accessibility violations', async () => {
195
  const results = await run({}, 'button--primary');
196
  
197
  // Check if running in standalone mode
198
  if (getIsVitestStandaloneRun()) {
199
    // In Vitest standalone mode, this will automatically extend expect
200
    expect(results).toHaveNoViolations();
201
  } else {
202
    // Manual assertion for other environments
203
    expect(results.violations).toHaveLength(0);
204
  }
205
});
206
```
207

208
## Rule Configuration
209

210
The addon includes default rule configuration to reduce false positives in component testing:
211

212
```typescript { .api }
213
const DISABLED_RULES = [
214
  // In component testing, landmarks are not always present
215
  // and the rule check can cause false positives
216
  'region',
217
] as const;
218
```
219

220
## Queue Management
221

222
The addon includes a queue system to ensure axe-core tests run sequentially:
223

224
- Tests are queued and executed one at a time
225
- Prevents concurrent axe-core execution issues
226
- Ensures reliable test results in multi-story environments
227

228
## Error Handling
229

230
Comprehensive error handling ensures graceful degradation:
231

232
- **Test Failures**: Caught and reported through Storybook's reporting system
233
- **Configuration Errors**: Invalid parameters are handled gracefully
234
- **Environment Issues**: Fallback behavior for different execution contexts
235
- **Axe-core Loading**: Handles dynamic import issues and UMD fallbacks