{"id":28718746,"url":"https://github.com/eotsevych/axe-playwright-report","last_synced_at":"2026-01-20T17:34:13.124Z","repository":{"id":293123422,"uuid":"981187536","full_name":"eotsevych/axe-playwright-report","owner":"eotsevych","description":null,"archived":false,"fork":false,"pushed_at":"2025-06-12T20:04:03.000Z","size":2384,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-12T21:24:53.142Z","etag":null,"topics":["axe-core","playwright","reporting"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/axe-playwright-report","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eotsevych.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-10T14:38:02.000Z","updated_at":"2025-06-12T20:04:07.000Z","dependencies_parsed_at":"2025-05-13T19:55:56.148Z","dependency_job_id":"c29ae98a-5d69-48bf-8703-808694e503e4","html_url":"https://github.com/eotsevych/axe-playwright-report","commit_stats":null,"previous_names":["eotsevych/axe-playwright-report"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/eotsevych/axe-playwright-report","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eotsevych%2Faxe-playwright-report","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eotsevych%2Faxe-playwright-report/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eotsevych%2Faxe-playwright-report/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eotsevych%2Faxe-playwright-report/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eotsevych","download_url":"https://codeload.github.com/eotsevych/axe-playwright-report/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eotsevych%2Faxe-playwright-report/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259924678,"owners_count":22932782,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["axe-core","playwright","reporting"],"created_at":"2025-06-15T05:03:35.593Z","updated_at":"2026-01-20T17:34:13.118Z","avatar_url":"https://github.com/eotsevych.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# axe-playwright-report\n\n[![npm version](https://img.shields.io/npm/v/axe-playwright-report.svg)](https://www.npmjs.com/package/axe-playwright-report)\n\nOpen-source library for generating accessibility dashboard reports with Playwright and axe-core.\n\n![Example Dashboard Report](./assets/dashboard_example.png)\n\n## Main Aim\n\nThe primary goal of this library is to enhance standard UI automation tests and the Page Object Pattern by enabling integrated accessibility scans. Instead of maintaining separate accessibility tests—which often duplicate the structure of regular UI tests—this library lets you trigger accessibility checks directly within your existing test flows. This approach reduces maintenance overhead when test flows change, as accessibility scans can be performed at any point in your current tests without the need for dedicated accessibility test cases.\n\n#### ℹ️ Reasonable Remark:\n\u003e q: Page object methods are reused in multiple tests, which will create multiple reports for the same page.\n\u003e\n\u003e a: During dashboard generation, the library will automatically de-duplicate results and retain only the scan with the most accessibility issues for each page.\n\n## Features\n\n- **Playwright + axe-core integration**: Easily scan your web pages for accessibility issues during Playwright tests.\n- **Dashboard report**: Generates a filterable HTML dashboard summarizing all accessibility findings.\n- **Customizable**: Configure scan options, output directory, and screenshot capture.\n- **Reuse of UI automation tests**: Leverage existing Page Object Pattern methods to run accessibility scans without duplicating test logic.\n\n## What This Library Offers\n\n1. **@axeScan() decorator**: Runs an accessibility scan after the method body is executed, allowing you to integrate accessibility checks seamlessly into your existing test methods.\n2. **`build-report` command**: Generates a dashboard report with backward compatibility for reports generated with axe-core/playwright.\n3. **`test` command**: enforces strict build rules in CI/CD pipelines.\n\n## Installation\n\n```bash\nnpm install axe-playwright-report --save-dev\n```\n\n## Usage\n\n### 1. Decorate your Playwright test methods\n\n```typescript\nimport { axeScan } from 'axe-playwright-report';\n\nclass MyTest {\n    page: Page;\n\n    constructor(page: Page) {\n        this.page = page;\n    }\n\n    @axeScan()\n    async testHomePage() {\n        await this.page.goto('https://example.com');\n        // ... your test logic ...\n    }\n}\n```\n\n- The `@axeScan()` decorator will run an accessibility scan after the decorated method.\n- Results are saved as JSON in the output directory (default: `axe-playwright-report/pages`).\n\n\n\u003e ### ⚠️ **Limitations**\n\u003e The Page Object Class must contain an object of type `Page`. If you decompose the page and use `Locator` as a base for searching elements, the accessibility scan will be skipped.\n\u003e\n\u003e **Applicable ✅**: `new sideMenu(page)`\n\u003e\n\u003e **Not-applicable ❌**: `new sideMenu(page.locator('#sideMenu'))`\n\n### 2. Configure scan options (optional)\n\nHaving accessibility env file gives you the flexibility to customize your scan settings.\nWith the config file it allows:\n- enable/disable scanning (default: `on`)\n- custom output directory (default: `axe-playwright-report`)\n- enable/disable screenshots capture (default: `off`)\n- filter rules by axe-core tags (default: `no filtering, all rules included`)\n- merge reports strategy (default: `best`)\n    - `none` - keep all reports,\n    - `exact` - merge only identical reports,\n    - `best` - keeps the report with the most accessibility issues\n- use custom regular expression for improving page normalization algorithm\n    - pass a list of regular expressions in array format '[\"regExp1\", \"regExp2\"]'\n- and all configuration options from axe-core, such as:\n    - `tags` - running access specific WCAG success criteria\n    - `withRules` - specify a list of rules to run\n    - `excludeRules` - specify a list of rules to exclude from running\n    - `include` - constrain an accessibility scan to only run against one specific part of a page\n    - `exclude` - exclude the specified elements and all of their descendants\n\nCreate a `.env.a11y` file in your project root:\n\n```\nSCAN=on\nOUTPUT_DIR=custom-report-dir\nMERGE_STRATEGY=best\nSCREENSHOT=on\nCUSTOM_REG_EXP='[\"^\\/\\w+-\\w+-\\w+\\.html$\", \"\\/([^\\/]*-[^\\/]*)\"]'\nTAGS=wcag2a,wcag2aa\nWITH_RULES=color-contrast,image-alt\nEXCLUDE_RULES=link-in-text-block\nINCLUDE='.main-content'\nEXCLUDE='.main-content .footer'\n```\n\n- `SCAN`: Set to `on` to enable scanning.\n- `OUTPUT_DIR`: Directory for report output (default: `axe-playwright-report`).\n- `SCREENSHOT`: Set to `on` to capture screenshots of issues.\n- `TAGS`: Comma-separated list of axe-core tags to filter rules.\n- `WITH_RULES`: Comma-separated list of axe-core rule IDs to run.\n- `EXCLUDE_RULES`: Comma-separated list of axe-core rule IDs to exclude from running.\n- `INCLUDE`: Selector to constrain an accessibility scan to only run against one specific part of a page.\n- `EXCLUDE`: Selector to exclude the specified elements and all of their descendants.\n- `MERGE_STRATEGY`: Set to `none` to keep all reports, `exact` to merge only identical reports, `best` to keep the report with the most accessibility issues.\n- `CUSTOM_REG_EXP`: Custom regular expression for improving page normalization algorithm.\n\nYou can find example of `.env.a11y` file [here](./.env.a11y.example)\n\n#### Recommendation for custom RegExp\nBy default, the library uses a normalization algorithm to avoid duplicate reports for the same page, for example, UUID, numeric or alphanumeric IDs.  \nIf you have a specific page structure not normalized by the default algorithm, you can use the `CUSTOM_REG_EXP` option to improve the results. \nFollow the structure of how the library operates with the regular expression.\nExamples:\n```\n- CUSTOM_REG_EXP='[\"^\\/\\w+-\\w+-\\w+\\.html$\", \"\\/([^\\/]*-[^\\/]*)\"]'\n- CUSTOM_REG_EXP='[\"^\\/\\w+-\\w+-\\w+\\.html$\"]\n```\n\n\n### 3. Generate the dashboard report\n\nAfter running your tests, build the dashboard:\n\n```bash\nnpx axe-playwright-report build-report\n```\n\nThis will generate an interactive HTML dashboard in your output directory.\n\n\u003e #### Backward Compatibility with Axe-core/playwright\n\u003e if you have existing reports generated with axe-core/playwright, you can still use this library to build the dashboard.\n\u003e Just place your existing JSON report files in the `axe-playwright-report/pages` directory and run the `build-report` command.\n\n## Output\n\n- **Dashboard**: `index.html` and supporting files in your output directory.\n- **Per-page results**: JSON files for each scanned page.\n- **Screenshots**: PNGs highlighting issues (if enabled).\n\n## Generating Bug Summary Reports\n\nYou can generate bug summary reports directly from the report page for selected accessibility issues.  \nThis feature allows you to quickly create bug reports with pre-filled titles and descriptions, saving time on repetitive reporting tasks.  \nBased on the number of selected issues, it generates either a single bug report for each issue or a grouped report for multiple issues.\n\n#### Single Bug Report Example\n![Single Bug Report Example](./assets/single_bug_report.png)\n#### Grouped Bug Report Example\n![Grouped Bug Report Example](./assets/grouped_bug_report.png)\n\n\n## Playwright Custom Reporter\nUsing the Playwright custom reporter, you can generate an accessibility report after test run automatically.  \nTo enable this feature, add the following code to your `playwright.config.ts` file:\n```typescript\nimport { defineConfig } from '@playwright/test';\n\nexport default defineConfig({\n    reporter: [\n        ['axe-playwright-report/axeBuildReport',\n            {\n                softAssert: true // if true, the process will not fail if there are accessibility issues. Default: false.\n            }\n        ],\n    ],\n});\n```\n`softAssert` parameter is optional and used for controlling the 'test' command behavior within the following cases:\n- `true`: the process will fail if there are accessibility issues.\n- `false`: the process will not fail if there are accessibility issues.\n- not specified: the test command will be not initiated, a process will not fail if there are accessibility issues.\n\n\n## CI/CD Pipeline Integration\nYou can integrate the accessibility checks into your CI/CD pipeline by adding the `test` command to your build process.\n```bash\nnpx axe-playwright-report test\n```\nThis command will enforce accessibility baselines according provided `VIOLATION_THRESHOLD` and `INCOMPLETE_THRESHOLD` in array format by **Critical** and **Serious** impact separated by comma.  \nFor example:\n```\nVIOLATION_THRESHOLD=10,10\nINCOMPLETE_THRESHOLD=25\n```\nmeans that the process will fail if there are more than 10 critical and 10 serious accessibility violations and more than 25 incomplete issues with critical impact level.  \nArguments `--allow-failure` will allow the process to continue and report failers as warnings.\n\n## axe-playwright-report CLI\nThere are two commands available in the CLI:\n- `build-report`: Generates a dashboard report.\n- `merge-reports`: Merges multiple reports into a single report. This command is integrated into the `build-report` command. As the separate command will be useful when you run tests in parallel using Playwright Sharding.\n- `test`: Check accessibility baselines.\n\n\n### Example Report\n\nBelow is an example of the generated dashboard report:\n\n![Example Report Page](./assets/report_example_1.png)\n![Example Report Page Expanded](./assets/report_example_2.png)\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feotsevych%2Faxe-playwright-report","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feotsevych%2Faxe-playwright-report","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feotsevych%2Faxe-playwright-report/lists"}