snowdogapps / a11y-audit-tool

Bootstrap project to easily run and develop a11y audits.

A11y Audit Tool

A11y Audit Tool is your comprehensive solution for web accessibility testing and report generation. With both automated and manual testing capabilities, this tool ensures your website's compliance with WCAG (Web Content Accessibility Guidelines) and helps you identify and address accessibility issues effectively.

Key Features

• Automated Tests: Run automatic tests on any website across many pages and various screen sizes.
• Manual Tests: Conduct manual tests using our template based on the Trusted Tester Conformance Process.
• Combined Testing Approach: Seamlessly integrate automatic tests with manual tests for comprehensive auditing.
• Downloadable Reports: Generate reports for easy reference and collaboration, facilitating improvement efforts.
• Project Organization: Group audits into projects for better organization and management of accessibility testing efforts.

Why Choose A11y Audit Tool?

• Comprehensive Testing: Unlike most tools that focus solely on automatic or manual tests, our tool offers both, ensuring comprehensive results. During manual tests, you can review and comment on automatic test results.
• Guided Testing: Our audit template guides you through accessibility features. It provides test conditions and techniques to solve issues. A tester doesn't need to be an expert in the accessibility field to perform an audit using our tool.
• Multi-page and Multi-screen Testing: Test multiple pages (URLs) and screen sizes in a single audit, enhancing efficiency.
• Clear Reports: Generated reports are clear and understandable, facilitating discussions with clients and roadmap planning for improvement efforts.
• Extensibility: Extend the tool's capabilities by adding custom test cases using Playwright, reducing manual work and enhancing efficiency.

Technology Stack

Database and Authentication

• Supabase

Full-Stack Application

• Nuxt 3
• Vue 3
• TypeScript
• Playwright
• Axe
• PrimeVue
• Tailwind CSS
• Nuxt Supabase
• VeeValidate with Yup schema validation
• Nuxt SVGO

Project setup

Prerequisites

• pnpm installed

Supabase

1. Create a Supabase project here.
2. Supabase projects rely on the postgresql database engine. In the ./sql directory you will find all the SQL installation files needed to make the whole application work. To install the necessary schema, please go to the SQL Editor tab of your project and RUN all SQL lines in the order presented on directory and inner file level.
3. In your Supabase project go to Project Settings -> API. Create .env file, copy .env.example content and set values from Supabase settings:

• NITRO_PUBLIC_SUPABASE_URL 👉 Project URL
• NITRO_PUBLIC_SUPABASE_KEY 👉 anon public
• NITRO_SUPABASE_SERVICE_KEY 👉 service_role secret

Alternatively, you can run Supabase locally:

1. Run npx supabase login and pass generated access token.
2. Run npx supabase start.
3. Pass envs from supabase started setup to .env file.

Learn more here.

Nuxt

1. Run:

pnpm install
pnpm exec playwright install
pnpm dev

2. Register new user on /register page.

Admin Role

Admins possess privileges to:

• Create a new project
• Assign user to a project
• Set user type
• See, edit and remove any audit

Admins have access to extra information and features on /admin page.

Admin role information is stored on the user custom claims level and can be found in claims_admin auth user's property. To check user custom claims run the following query in Supabase SQL Editor:

select get_claims('PASS-HERE-SPECIFIC-USER-UUID-FROM-AUTH-TABLE');

To grant admin privileges to a user, follow these steps:

1. Run the following query in Supabase SQL Editor:

   select set_claim('PASS-HERE-SPECIFIC-USER-UUID-FROM-AUTH-TABLE', 'claims_admin', 'true');

2. Re-login to Nuxt application to see the change.

User Types

The application supports 2 user types:

1. Auditor - can perform the following actions in projects he is assigned to:
   • Create new audits
   • View and edit his audit drafts
   • View all completed audits (called reports)
2. Viewer - can perform the following actions in projects he is assigned to:
   • View all completed audits (called reports)

User type information is stored on the user custom claims level and can be found in user_role auth user's property. When custom claim user_role is set/updated, the corresponding information in the profiles table (user_type column) is also updated.

To grant auditor/viewer privileges to a user, follow these steps:

1. Log in to Nuxt application as admin user, go to /admin and Update user type.

   Alternatively, run the following query in Supabase SQL Editor.

   Auditor:

   select set_claim('PASS-HERE-SPECIFIC-USER-UUID-FROM-AUTH-TABLE', 'user_role', '"auditor"');

   Viewer:

   select set_claim('PASS-HERE-SPECIFIC-USER-UUID-FROM-AUTH-TABLE', 'user_role', '"viewer"');

2. The user should re-login to Nuxt application to see the change.

Https Configuration

Install mkcert on your system. The installation instructions for macOS, Windows and Linux can be found in the mkcert Github repository.

Create a valid certificate by running the following command in your project folder:

mkcert [-install] localhost

Run your project using

npm run dev-secure

Your project will now be served on https://localhost:3000.

Contributing

Contributions are welcome! If you find a bug or have a feature request, feel free to open an issue or submit a pull request.

Like this project?

We'd appreciate it if you leave a ⭐ or share it with the world ✨.

Who is developing?

Hey there! Snowdog is all about creating top-notch Hyvä builds with our own Hyvä Sparq accelerator. We make sure to optimize Hyvä for both b2c and b2b commerce, and we’re a big accessibility advocate for the platform. You might also know us as the creator of the popular free Hyvä menu module. We’ve been working with Magento Open Source and Enterprise (now Adobe Commerce) for over a decade, and we even organize the Meet Magento conference since 2012. So if you're looking for a high-performing Hyvä store in no time, we’re your go-to agency!

We are also a team of digital accessibility specialists. A11y is our priority from day one of design and development. It's an integral part of our existing themes and design patterns, so not only do we build accessible solutions from scratch, but we have experience working with clients that need meet certain a11y requirements to comply with discrimination laws. Ready to elevate your online store and start your accessibility journey with us? Let's talk.

a11y-audit-tool's Issues

Add "incomplete" axe test result

In the audit results, there is an issues array inceomplete, also known as needs review.
All automatic tests should be reviewed, so I think we can add it to the issues in automatic test results.

Some pages are not fully loaded when automatic tests are conducted

When the page is not fully loaded and playwright-axe test is conducted, we don't get any valuable results.

I'm not a specialist in Playwright, but to make sure the page is loaded, you have to wait for a specific selector at the bottom of the page. I haven't found a better solution.

If you have any, please advice

Missing HTML selector in audit view

when HTML selector is provided for a specific URL, it's properly passed to database with audit configuration but it's not passed to database axe table and it doesn't display in the audit results view.