![](\"logo.png\")
\n This is a test page.
\n\n\n`;\n\nconst result = await wave.analyzeSource(htmlSource);\nconsole.log(`Errors found: ${Object.keys(result.categories.error || {}).length}`);\n```\n\n#### ngrok Configuration\n\n`analyzeSource` uses ngrok to create a temporary public URL for the WAVE API. While ngrok works without authentication for basic usage, you may want to set up an authtoken for:\n\n* Higher rate limits\n* Longer session times\n* Custom domains (paid plans)\n\nTo configure ngrok with an authtoken:\n\n1. Sign up for a free ngrok account at [https://ngrok.com/](https://ngrok.com/)\n2. Get your authtoken from the ngrok dashboard\n3. Set it using one of these methods:\n\n##### Option 1: Environment Variable\n\n```bash\nexport NGROK_AUTHTOKEN=your_authtoken_here\n```\n\n##### Option 2: ngrok Configuration File\n\n```bash\nngrok config add-authtoken your_authtoken_here\n```\n\n##### Option 3: Programmatically\n\n```javascript\nimport { setAuthtoken } from '@ngrok/ngrok';\n\n// Set authtoken before using analyzeSource\nawait setAuthtoken('your_authtoken_here');\n\n// Then use wave.analyzeSource as normal\nconst result = await wave.analyzeSource(htmlSource);\n```\n\n**Note**: The module will work without an authtoken, but you may encounter rate limits with heavy usage. This is especially true if using as part of CI/ CD or running a large set of automated functional testing\n\n### Advanced Options\n\n```javascript\nconst result = await wave.analyze('https://example.com', {\n reporttype: 2, // 1-4, controls level of detail\n format: 'json', // 'json' or 'xml'\n viewportwidth: 1920, // Viewport width for analysis (default: 1200)\n viewportheight: 1080, // Viewport height for analysis\n evaldelay: 2000, // Delay before evaluation in ms (default: 250)\n username: 'user', // Username for authenticated pages\n password: 'pass', // Password for authenticated pages\n useragent: 'Mozilla/5.0...' // Custom user agent string\n});\n\n// Options work the same way with analyzeSource\nconst sourceResult = await wave.analyzeSource(htmlSource, {\n reporttype: 2,\n viewportwidth: 1920\n});\n```\n\n#### Report Types\n\n* **Type 1** (1 credit): Basic statistics only\n* **Type 2** (2 credits): Includes detailed error/alert/feature listings\n* **Type 3** (3 credits): Adds XPath selectors for elements\n* **Type 4** (3 credits): Adds CSS selectors for elements\n\n## API Reference\n\n### WaveClient\n\n#### Constructor\n\n```typescript\nnew WaveClient(options: WaveOptions)\n```\n\nOptions:\n\n* `apiKey` (required): Your WAVE API key\n* `baseUrl` (optional): API base URL (default: `https://wave.webaim.org/api`)\n* `timeout` (optional): Request timeout in milliseconds (default: 30000)\n\n#### Methods\n\n##### analyze(url: string, options?: WaveAnalysisOptions): Promise<WaveAnalysisResult>\n\nAnalyzes a URL for accessibility issues.\n\nParameters:\n\n* `url`: The URL to analyze (must be publicly accessible)\n* `options`: Optional analysis parameters (see below)\n\n##### analyzeSource(source: string, options?: WaveAnalysisOptions): Promise<WaveAnalysisResult>\n\nAnalyzes HTML source code for accessibility issues by creating a temporary public URL via ngrok.\n\nParameters:\n\n* `source`: HTML source code as a string (can include inline CSS and JavaScript)\n* `options`: Optional analysis parameters (see below)\n\n###### How it works\n\n1. Creates a local HTTP server serving your HTML source\n2. Establishes an ngrok tunnel to make it publicly accessible\n3. Sends the ngrok URL to WAVE API for analysis\n4. Automatically cleans up the server and tunnel after completion\n\n###### Requirements\n\n* Active internet connection\n* Port availability for local server (uses random port)\n* Optional: ngrok authtoken for extended usage\n\n#### Analysis Options\n\nBoth `analyze` and `analyzeSource` accept the following options:\n\n* `reporttype`: Level of report detail (1-4, default: 1)\n* `format`: Response format ('json' or 'xml', default: 'json')\n* `viewportwidth`: Browser viewport width in pixels (default: 1200)\n* `viewportheight`: Browser viewport height in pixels\n* `evaldelay`: Delay before evaluation in milliseconds (default: 250)\n* `username`: Username for HTTP authentication\n* `password`: Password for HTTP authentication\n* `useragent`: Custom user agent string for browser simulation\n\n### Response Structure\n\nThe analysis result includes:\n\n* `status`: Success status and HTTP status code\n* `statistics`: Page statistics including title, URL, credits remaining\n* `categories`: Accessibility findings organized by type\n * `error`: Accessibility errors\n * `alert`: Accessibility alerts\n * `feature`: Accessibility features\n * `structure`: Structural elements\n * `aria`: ARIA usage\n * `contrast`: Contrast issues\n\n## Error Handling\n\nThe client throws `WaveApiError` for API-related errors:\n\n```javascript\ntry {\n const result = await wave.analyze('https://example.com');\n} catch (error) {\n if (error.code === 'INVALID_KEY') {\n console.error('Invalid API key');\n } else if (error.statusCode === 429) {\n console.error('Rate limit exceeded');\n } else {\n console.error('Error:', error.message);\n }\n}\n```\n\n## Credits and Pricing\n\nEach API request consumes credits:\n\n* Basic page analysis: 1 credit\n* Advanced features: 2-3 credits\n\nMonitor your remaining credits:\n\n```javascript\nconst result = await wave.analyze('https://example.com');\nconsole.log(`Credits remaining: ${result.statistics.creditsremaining}`);\n```\n\n## License\n\nMIT\n\n## Troubleshooting\n\n### analyzeSource Issues\n\n#### Error: \"Failed to connect to ngrok\"\n\n* Ensure you have an active internet connection\n* Check if your firewall is blocking ngrok\n* Try setting an authtoken (see ngrok Configuration above)\n\n#### Error: \"ngrok tunnel expired\"\n\n* Free ngrok accounts have session limits\n* Consider setting up an authtoken for longer sessions\n* The module automatically retries once on tunnel errors\n\n#### Timeout errors\n\n* Increase the timeout in WaveClient options\n* Check if the HTML contains external resources that are slow to load\n* Consider using the `evaldelay` option to give the page more time to render\n\n## Security Considerations\n\nWhen using `analyzeSource`:\n\n* The HTML content is temporarily exposed via a public ngrok URL\n* The server and tunnel are automatically cleaned up after analysis\n* Consider the sensitivity of your HTML content before using this feature\n* For highly sensitive content, use the standard `analyze()` method with your own secure hosting\n\n## Testing\n\nThe module includes comprehensive test coverage with both unit and integration tests.\n\n### Running Tests\n\n```bash\n# All tests\nnpm test\n\n# Unit tests only\nnpm run test:unit\n\n# Integration tests only (requires API keys)\nnpm run test:integration\n\n# Watch mode\nnpm run test:watch\n\n# Coverage report\nnpm run test:coverage\n```\n\n### Integration Tests\n\nIntegration tests require environment variables:\n\n```bash\nexport WAVE_API_KEY=your_wave_api_key\nexport NGROK_AUTHTOKEN=your_ngrok_token # Optional, for analyzeSource tests\nnpm run test:integration\n```\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on the process for submitting pull requests.\n\nAll contributions are expected to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).\n\n### Development Scripts\n\n```bash\nnpm run build # Build TypeScript to JavaScript\nnpm run dev # Build in watch mode\nnpm run lint # Run ESLint\nnpm run lint:fix # Fix linting issues\nnpm test # Run all tests\nnpm run test:unit # Run unit tests only\nnpm run test:integration # Run integration tests (requires API keys)\n```\n\n## Additional Resources\n\n### WAVE Documentation API\n\nTo get detailed information about specific WAVE issue types, you can use the documentation API:\n\n```text\nhttps://wave.webaim.org/api/docs?id={item_id}\n```\n\nFor a full list of all WAVE issue types and their descriptions:\n\n```text\nhttps://wave.webaim.org/api/docs\n```\n\n## Links\n\n* [GitHub Repository](https://github.com/karlgroves/wave-node)\n* [NPM Package](https://www.npmjs.com/package/@afixt/wave-node)\n* [WAVE API Documentation](https://wave.webaim.org/api/)\n* [WAVE API Details](https://wave.webaim.org/api/details)\n* [WAVE Web Interface](https://wave.webaim.org/)\n* [WebAIM](https://webaim.org/)\n","readmeFilename":"README.md"}