{"_id":"@emarty-maze/a11y-test","name":"@emarty-maze/a11y-test","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@emarty-maze/a11y-test","version":"1.0.0","description":"Standalone accessibility testing tool for any website using axe-core and Playwright. Test WCAG 2.0/2.1 compliance with configurable scenarios, password protection support, and multiple output formats (HTML, JSON, Markdown).","main":"a11y.test.js","type":"module","bin":{"a11y-test":"a11y.test.js"},"scripts":{"test":"node a11y.test.js --help"},"keywords":["accessibility","a11y","wcag","axe","axe-core","playwright","testing","automation","compliance","wcag2a","wcag2aa","wcag21","web-accessibility","accessibility-testing"],"author":{"name":"Erik Marty"},"license":"ISC","repository":{"type":"git","url":"git+https://github.com/emarty-maze/a11y-test.git"},"bugs":{"url":"https://github.com/emarty-maze/a11y-test/issues"},"homepage":"https://github.com/emarty-maze/a11y-test#readme","engines":{"node":">=16.0.0"},"dependencies":{"@axe-core/playwright":"^4.11.0","playwright":"^1.56.1"},"peerDependencies":{"playwright":">=1.40.0"},"publishConfig":{"access":"public"},"_id":"@emarty-maze/a11y-test@1.0.0","gitHead":"0d817cd5c9365eca7c54ec1ad723f641ba902ba9","_nodeVersion":"23.9.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-R5b8+agzCRC7CudsJ2Hbz/2UAkeSkjpJOwzZq3OHh8n9EAG3FlM2RCiiS/dcDER9EANDNC0IkGa6i8j/UtvhOg==","shasum":"8f33e3e784654605a46ccff44ead2d98102a9290","tarball":"https://registry.npmjs.org/@emarty-maze/a11y-test/-/a11y-test-1.0.0.tgz","fileCount":5,"unpackedSize":53195,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDVq0Tyy22ULO2EqVdtBpiDCy+u6fXZRDpBVYvmdWAr1gIgHuo2q9rvnf0GneEB17Xt3snwYFrfXPGn17MV4CcBZyY="}]},"_npmUser":{"name":"emarty-maze","email":"erik@themazegroup.com"},"directories":{},"maintainers":[{"name":"emarty-maze","email":"erik@themazegroup.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/a11y-test_1.0.0_1763143910622_0.2657038448121525"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-14T18:11:50.535Z","1.0.0":"2025-11-14T18:11:50.818Z","modified":"2025-11-14T18:11:51.098Z"},"maintainers":[{"name":"emarty-maze","email":"erik@themazegroup.com"}],"description":"Standalone accessibility testing tool for any website using axe-core and Playwright. Test WCAG 2.0/2.1 compliance with configurable scenarios, password protection support, and multiple output formats (HTML, JSON, Markdown).","homepage":"https://github.com/emarty-maze/a11y-test#readme","keywords":["accessibility","a11y","wcag","axe","axe-core","playwright","testing","automation","compliance","wcag2a","wcag2aa","wcag21","web-accessibility","accessibility-testing"],"repository":{"type":"git","url":"git+https://github.com/emarty-maze/a11y-test.git"},"author":{"name":"Erik Marty"},"bugs":{"url":"https://github.com/emarty-maze/a11y-test/issues"},"license":"ISC","readme":"# Standalone Accessibility Testing Script\n\nA portable, framework-agnostic accessibility testing tool that can test any website for WCAG 2.0/2.1 Level A/AA compliance using axe-core and Playwright.\n\n## Features\n\n- ✅ Test any website (no Shopify dependencies)\n- ✅ WCAG 2.0/2.1 Level A/AA compliance testing\n- ✅ Support for password-protected sites\n- ✅ Multiple browser support (Chromium, Firefox, WebKit)\n- ✅ Custom test scenarios with navigation actions\n- ✅ HTML and JSON reports with screenshots\n- ✅ Command-line interface or config file\n- ✅ Exclude specific elements from testing\n\n## Installation\n\n### As an npm Package (Recommended)\n\n```bash\n# Global installation (use anywhere)\nnpm install -g @emarty/a11y-test\n\n# Or local installation (project-specific)\nnpm install --save-dev @emarty/a11y-test\n```\n\n### Manual Installation\n\n```bash\n# Clone and install dependencies\ngit clone <repository-url>\ncd a11y\nnpm install\n```\n\nSee [INSTALLATION.md](INSTALLATION.md) for detailed installation instructions and publishing guide.\n\n## Quick Start\n\n### Test a Single URL\n\n```bash\n# If installed globally\na11y-test --url https://example.com\n\n# If installed locally or using directly\nnode a11y.test.js --url https://example.com\n```\n\n### Test with Password Protection\n\n```bash\na11y-test --url https://staging.example.com --password mypassword\n```\n\n### Test Multiple Pages with Config File\n\n```bash\na11y-test --config my-test-config.json\n```\n\n## Command-Line Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--url` | URL to test (required if no config file) | - |\n| `--password` | Password for password-protected sites | - |\n| `--output` | Output directory for reports | `./a11y-reports` |\n| `--name` | Test name for report files | Derived from URL |\n| `--browser` | Browser: `chromium`, `firefox`, `webkit` | `chromium` |\n| `--config` | JSON config file with test scenarios | - |\n| `--headless` | Run in headless mode | `true` |\n| `--exclude` | CSS selectors to exclude (comma-separated) | - |\n| `--fail-on` | Severity to fail on: `critical`, `serious`, `moderate`, `minor`, `all` | `serious` |\n| `--treat-incomplete-as-violations` | Treat incomplete checks as violations (recommended) | `false` |\n| `--help` | Show help message | - |\n\n## Configuration File Format\n\nCreate a JSON file with your test configuration:\n\n```json\n{\n  \"baseUrl\": \"https://example.com\",\n  \"password\": \"optional-password\",\n  \"outputDir\": \"./a11y-reports\",\n  \"browser\": \"chromium\",\n  \"headless\": true,\n  \"exclude\": [\n    \"#cookie-banner\",\n    \".third-party-widget\"\n  ],\n  \"scenarios\": [\n    {\n      \"name\": \"Homepage\",\n      \"path\": \"/\"\n    },\n    {\n      \"name\": \"About Page\",\n      \"path\": \"/about\"\n    },\n    {\n      \"name\": \"Products with Filter\",\n      \"path\": \"/products\",\n      \"actions\": [\n        {\n          \"type\": \"click\",\n          \"selector\": \".filter-button\"\n        },\n        {\n          \"type\": \"wait\",\n          \"duration\": 1000\n        }\n      ]\n    }\n  ]\n}\n```\n\nSee `standalone-a11y-config.example.json` for a complete example.\n\n## Usage Examples\n\n### Basic Testing\n\n```bash\n# Test a single page\nnode testing/standalone-a11y-test.js --url https://example.com\n\n# Test with custom output directory\nnode testing/standalone-a11y-test.js \\\n  --url https://example.com \\\n  --output ./my-reports\n\n# Test with Firefox\nnode testing/standalone-a11y-test.js \\\n  --url https://example.com \\\n  --browser firefox\n\n# Test in non-headless mode (see browser)\nnode testing/standalone-a11y-test.js \\\n  --url https://example.com \\\n  --headless false\n```\n\n### Advanced Testing\n\n```bash\n# Exclude specific elements\nnode testing/standalone-a11y-test.js \\\n  --url https://example.com \\\n  --exclude \"#cookie-banner,.ads-widget\"\n\n# Fail on all violations (including minor)\nnode testing/standalone-a11y-test.js \\\n  --url https://example.com \\\n  --fail-on all\n\n# Treat incomplete checks as violations (recommended for thorough testing)\nnode testing/standalone-a11y-test.js \\\n  --url https://example.com \\\n  --treat-incomplete-as-violations \\\n  --fail-on all\n\n# Test multiple scenarios from config\nnode testing/standalone-a11y-test.js \\\n  --config my-test-config.json\n\n# Override config file settings\nnode testing/standalone-a11y-test.js \\\n  --config my-test-config.json \\\n  --browser firefox \\\n  --output ./custom-reports\n```\n\n## Custom Actions in Scenarios\n\nYou can define custom actions to perform before running accessibility tests:\n\n```json\n{\n  \"name\": \"Search Results\",\n  \"path\": \"/search\",\n  \"actions\": [\n    {\n      \"type\": \"fill\",\n      \"selector\": \"#search-input\",\n      \"value\": \"test query\"\n    },\n    {\n      \"type\": \"click\",\n      \"selector\": \"#search-button\"\n    },\n    {\n      \"type\": \"wait\",\n      \"duration\": 2000\n    }\n  ]\n}\n```\n\n### Supported Action Types\n\n- **`click`**: Click an element\n  ```json\n  { \"type\": \"click\", \"selector\": \".button\" }\n  ```\n\n- **`fill`**: Fill a form field\n  ```json\n  { \"type\": \"fill\", \"selector\": \"#input\", \"value\": \"text\" }\n  ```\n\n- **`wait`**: Wait for a duration\n  ```json\n  { \"type\": \"wait\", \"duration\": 1000 }\n  ```\n\n## Output Reports\n\nThe script generates four types of output for each test:\n\n1. **HTML Report** - Visual report with detailed violation information\n2. **JSON Report** - Machine-readable report with full axe-core results\n3. **Markdown Report** - Formatted report for easy copy/paste into Confluence or documentation\n4. **Screenshot** - Full-page screenshot of the tested page\n\nAll reports are saved to the output directory with timestamped filenames:\n```\na11y-reports/\n├── homepage-chromium-2025-01-13-17-30-00.html\n├── homepage-chromium-2025-01-13-17-30-00.json\n├── homepage-chromium-2025-01-13-17-30-00.md\n└── homepage-chromium-2025-01-13-17-30-00.png\n```\n\n### Using Markdown Reports in Confluence\n\nThe `.md` files can be directly copied and pasted into Confluence:\n1. Open the `.md` file in any text editor\n2. Copy the entire contents\n3. In Confluence, create a new page or edit an existing one\n4. Paste the markdown - Confluence will automatically format it with tables, headings, and links\n\n## Understanding Results\n\n### Violation Severity Levels\n\n- **Critical** - Must be fixed immediately\n- **Serious** - Should be fixed as soon as possible\n- **Moderate** - Should be fixed\n- **Minor** - Nice to fix\n\n### Incomplete Checks\n\nSome accessibility issues cannot be automatically determined and are marked as \"incomplete\". These require manual review and often indicate real problems. Use `--treat-incomplete-as-violations` to fail tests when incomplete checks are found.\n\nCommon incomplete checks:\n- `color-contrast` - When background colors can't be determined\n- `aria-hidden-focus` - When focusable elements might be hidden\n- `aria-allowed-role` - When role usage needs manual verification\n\n### Configurable Failure Thresholds\n\nUse `--fail-on` to control which severity levels cause test failures:\n\n```bash\n# Fail only on critical issues\nnode a11y.test.js --url https://example.com --fail-on critical\n\n# Fail on serious and above (default)\nnode a11y.test.js --url https://example.com --fail-on serious\n\n# Fail on any violation\nnode a11y.test.js --url https://example.com --fail-on all\n```\n\n### Exit Codes\n\n- `0` - All tests passed (no violations meeting the `--fail-on` threshold)\n- `1` - Tests failed (violations found at or above the `--fail-on` threshold)\n\n## Integration with CI/CD\n\n### GitHub Actions Example\n\n```yaml\n- name: Run Accessibility Tests\n  run: |\n    node testing/standalone-a11y-test.js \\\n      --config test-config.json \\\n      --output ./a11y-reports\n\n- name: Upload Reports\n  if: always()\n  uses: actions/upload-artifact@v3\n  with:\n    name: accessibility-reports\n    path: a11y-reports/\n```\n\n### GitLab CI Example\n\n```yaml\naccessibility-test:\n  script:\n    - node testing/standalone-a11y-test.js --config test-config.json\n  artifacts:\n    when: always\n    paths:\n      - a11y-reports/\n```\n\n## Troubleshooting\n\n### Password Protection Not Working\n\nMake sure the site uses a standard password form with:\n- `<input type=\"password\">` for the password field\n- `<button type=\"submit\">` or `<input type=\"submit\">` for submission\n\n### Tests Timing Out\n\nThe script uses a 60-second timeout and waits for the page `load` event (not `networkidle`) to avoid timeouts on sites with continuous background requests.\n\nIf you still experience timeouts:\n1. Check your network connection\n2. Try running in non-headless mode to see what's happening\n3. Add explicit wait actions in your config:\n\n```json\n{\n  \"type\": \"wait\",\n  \"duration\": 3000\n}\n```\n\n### Elements Not Found\n\nUse browser DevTools to verify selectors:\n```bash\n# Run in non-headless mode to debug\nnode testing/standalone-a11y-test.js \\\n  --url https://example.com \\\n  --headless false\n```\n\n### Too Many Violations from Third-Party Content\n\nExclude third-party widgets and ads:\n```bash\nnode testing/standalone-a11y-test.js \\\n  --url https://example.com \\\n  --exclude \"#ads,.social-widgets,.cookie-banner\"\n```\n\n### Cookie Banners Blocking Content\n\nThe script automatically attempts to dismiss common cookie banners and overlays before scanning. If violations are still being blocked:\n\n1. Add the cookie banner to exclusions:\n```bash\nnode a11y.test.js --url https://example.com --exclude \"#cookie-consent\"\n```\n\n2. Or add a custom action to dismiss it:\n```json\n{\n  \"actions\": [\n    {\n      \"type\": \"click\",\n      \"selector\": \"#accept-cookies\"\n    },\n    {\n      \"type\": \"wait\",\n      \"duration\": 500\n    }\n  ]\n}\n```\n\n## Differences from Original Script\n\nThis standalone version removes:\n- Shopify-specific dependencies (store-resolver, storefront-api)\n- Theme preview parameters\n- Store configuration system\n- Brand-specific scenarios\n\nAnd adds:\n- Universal URL testing\n- Flexible configuration system\n- Command-line interface\n- Multiple browser support\n- Custom action support\n\n## License\n\nSame as parent project.\n","readmeFilename":"README.md","_rev":"1-2269cfb8507779a1d0f3c1bd96469dfd"}