How sclavijosuero/wick-a11y works
Main Components
• Cypress Integration Layer – This includes integration hooks in the Cypress configuration (e.g., the import and registration of accessibility tasks in cypress.config.js) as well as custom commands (imported in cypress/support/e2e.js or tests).
• Accessibility Analysis Engine – Built on top of the axe-core and cypress-axe plugins, this is where the actual accessibility tests, rule configurations, and violation aggregations take place.
• Reporting Module – Responsible for generating HTML reports (with graphs, screenshots, and accessibility violation details) and terminal reports. This is also linked to the custom styling logic (impactStyling) that visually differentiates violation levels.
• Voice Feedback Module – Provides audible accessibility alerts and summaries levels (suite, test, violation type and DOM element) in the Cypress Log and on the webpage.
• Cypress Tests & Configuration – Contains sample test files under the “cypress” directory with example usage of the “cy.checkAccessibility()” command and a configuration setup (cypress.config.js, cypress.env.json).
• Core Source Files – Found in the “src” folder, which include various accessibility command and logging utilities (i.e., accessibility-commands.js, accessibility-report.js, etc.) that help drive the plugin functionality.
Out the Interactions
• From the Cypress Runner, show how the Cypress configuration file (cypress.config.js) registers the plugin’s accessibility tasks and imports the core source modules.
• How test files (in the cypress/e2e/ directory) call the custom “cy.checkAccessibility()” command.
• Reporting pathway, branching off from the analysis step to generate:
– HTML Reports (in the accessibility reports folder, configurable via cypress.config.js)
– Terminal Logs (with detailed summaries and severity highlights)
• Voice feature as a parallel module activated when the Cypress runner is in interactive mode and when the “enableAccessibilityVoice” environment variable is true.
• Integration with image assets (screenshots) related to accessibility violations, with the “images” folder supplying resources for diagrammatic representation of severity levels (red, orange, yellow, blue).
Architectural Patterns & Design Principles
• Modular Design: Different components (analysis engine, reporting, voice feedback) are encapsulated in their own source files.
• Plugin Pattern: The solution extends Cypress functionality via custom commands and tasks that integrate seamlessly with the existing testing framework.
• Configurability: The plugin makes heavy use of configuration parameters (both in code and through environment variables) to modify behavior as needed.
• Separation of Concerns: The file structure divides concern areas (source code versus tests, GitHub workflows for CI/CD, report generation logic, etc.).
Specify Relevant Technologies & Libraries
• Cypress (for end-to-end test execution)
• axe-core® and cypress-axe (for performing and configuring the accessibility tests)
• Node.js (for plugin execution and integration with Cypress)
• GitHub Actions (.github/workflows/main.yml for CI/CD automation)
• Reporting Technologies (HTML/CSS for report generation and layout)
• Optional Voice APIs (for the voice feedback module)
• Each Component should have a clear label (e.g., “Cypress Runner”, “Accessibility Analysis Engine”, “Reporting Module”, “Voice Feedback Module”).
– From the Cypress Runner to the custom command layer.
– From the command layer to the analysis engine.
– From the analysis engine to both report generators and the voice feedback module.
– Backwards flow if necessary to show how detailed logs are returned to the runner.
• Use annotations or side notes to indicate key configuration options such as “includedImpacts”, “onlyWarnImpacts”, and paths to reports.