QA getting started

Understand accessibility standards

As a tester, it is important to have knowledge of the WCAG.
These are set of internationally recognised guidelines aimed at making web content more accessible to people with disabilities.

These guidelines are developed by the World Wide Web Consortium (W3C) through its Web Accessibility Initiative (WAI) and are designed to ensure that websites, apps, and other digital products can be accessed and used by as many people as possible, regardless of physical or cognitive abilities.

You should be aware of the legal requirements governing accessibility.

Integrate BAgel into your test plan

A test plan is essential to ensure thoroughness, organization, and efficiency. In order to meet the accessibilty criteria, here's how to approach it:

Familiarise yourself with the documentation: Review the docs section, which provides detailed guidance for each component, including parent-child combinations.
Define the scope: Identify the specific pages, functionality, and user flows that will be tested.
Set Clear Goals: Establish the accessibility criteria to meet in accordance with WCAG 2.2 Level AA compliance.
Develop a testing strategy: Determine the types of tests to conduct to fulfill accessibility requirements..
Create detailed test cases: Write precise test cases that outline the testing techniques, expected results, and actual outcomes to ensure comprehensive coverage.

Check BAgel has been implemented correctly

When implemented correctly, BAgel will automatically apply best practices to create an accessible website. However, it's still possible to assemble components in a non-accessible way.
If you enable the BAgel helper in your test environments, it will flag issues such as incorrect parent/child combinations and invalid attributes or prop values in the console

How to add BAgel helper to your project BAgel helper.

How to identify Bagel components in the page.

BAgel components use a consistent naming convention that prefixes components with 'ba-', such as ba-button, ba-link, and ba-card.

Certain components, like ba-content, have additional classes that can be applied to their children, e.g., ba-c-content__summary.

Some BAgel components may also have custom attributes or events, such as baClick on ba-button components, which can be used as hooks when writing tests.

Be aware that some components will generate dynamic IDs within their code. These IDs are updated randomly and should not be used as test hooks.

IDs, classes, and data attributes can be added to the component just as you would with a normal HTML element for test hooks.

It is recommended to refer to the documentation to understand the attributes and events available for the component you're trying to test

Accessibility test tools.

Below is a list of popular accessibility testing tools that can help ensure your website complies with the WCAG 2.2 accessibility standard. It's vital to note that these tools won't catch all errors.

Manual Testing Tools

NVDA (NonVisual Desktop Access)
VoiceOver (Built-in on macOS and iOS)
Color Contrast Analyzer(by Google)
Windows high contrast
Talkback (andriod)

Automated Testing Tools

Axe Accessibility (by Deque Systems) Axe.
Lighthouse (by Google) Lighthouse
Accessibility Insights (by Microsoft) Insights

Other tools

Siteimprove
Chrome DevTools Accessibility Panel

Follow a sequence

Testing a web page for accessibility with Bagel components in a structured manner ensures that all critical issues are adequately addressed. Here's a step-by-step process you can follow:

Keyboard operation is available for every functions.
Verify that you can: - navigate through all links and controls using the Tab key.
Shift-tab to go backward; enter to access links

a place where form controls, like checkboxes, can be selected
Arrow keys for tabs or radio buttons.

Testing with assistive technology

Testing with assistive technology is a critical part of ensuring web accessibility. It helps verify that people with disabilities, such as visual, hearing, motor, or cognitive impairments, can interact with your website effectively.

You can use screen readers like JAWS, NVDA, or VoiceOver to navigate and interact with your website. Please refer to Assistive technology and Browser support policy for all combinations to test.

Colour contrast and visual checks

Make sure there is enough contrast between the text and background colours.

Contrast Tools: Use tools such as Colour Oracle, Mac OS, and Windows Contrast Checker.
Contrast Ratio: Make sure the text contrasts well with the background (a standard text should have a minimum ratio of 4.5:1).

Note: If you are using BAgel components then this has been covered however for integration purposes like there has been a clash with css, then it it advisable to conduct this tests.

Text Resizing & Multilingual

Ensure that no functionality or information is lost in any supported language when:
The font size is increased up to 200%.
The page is zoomed in up to 400%.
Correct Language Attribute: Ensure that each page or content block has the correct lang attribute in the HTML. This helps screen readers and other assistive technologies correctly interpret and pronounce the content
Ensure that the screen reader correctly pronounces the content and switches languages properly when reading multilingual sections.
For each language, check if the screen reader accurately interprets the content in that language, particularly when switching between languages within the same page.

Voice control testing

This ensures the application is fully usable through voice commands, which is vital for users with mobility impairments or other disabilities that limit their ability to use traditional input methods like a mouse or keyboard. Voice control software allows users to interact with websites using spoken commands.

Testing for voice control helps ensure that all interactive elements and content are accessible in this way. It is essential to familiarize yourself with popular voice control systems such as

Dragon NaturallySpeaking:
Apple Voice Control: Built-in voice control on macOS and iOS devices.
Windows Speech Recognition: Integrated into Windows OS
Google Assistant / Siri: These tools provide voice control capabilities but are more focused on voice commands for the operating system.

Start with general navigation to ensure users can move through the site using voice commands:

Test basic commands like "Scroll down," "Scroll up," "Go back," and "Go forward."
Check voice-activated clicks for links and buttons using commands like "Click [link text]" or "Click [button text]."
Test navigation by headings, where users can say commands like "Go to heading [level or text]."
Verify that users can interact with all interactive elements using voice commands like form fields,
buttons,links, dropdowns and menus.

Forms and inputs

Ensure that the form labels, instructions, and error messages are accessible.

Label Associations: Ensure that labels are correctly related with form controls.
Error Handling: Make that error messages for components like ba-input-text, ba-input-textarea, and ba-input-number are descriptive and announced to assistive technology.
Instructions and Feedback: Provide clear instructions and feedback for form submission, ensuring that assistive technology accurately express this information.

Multimedia content

Ensure videos have captions and transcripts

Audio Descriptions: Provide audio descriptions for important visual content.
Autoplay Content: Avoid autoplay for videos or audio; if used, ensure it can be paused or stopped easily.

Responsive design testing

Testing responsive design is crucial to ensure that a website or web application works well across various screen sizes and devices, providing a consistent user experience. Responsive design adapts the layout, images, and functionality to different screen widths (e.g., mobile, tablet, desktop). Here’s a step-by-step guide on how to test responsive design effectively:

Identify Breakpoints: Review the breakpoints defined in the CSS for different screen widths (e.g., 320px for mobile, 768px for tablets, and 1024px or above for desktops).
Device Types: Test on various devices (smartphones, tablets, desktops) and orientations (portrait and landscape).
Browser Coverage: Ensure your site works on major browsers (Chrome, Firefox, Safari, Edge, etc.) as rendering may vary. Please refer to Browser support policy
Resize your browser window by dragging the edges manually to test how the layout adjusts at various screen widths.
Focus on breakpoints where the design might change (e.g., when the navigation menu shifts to a hamburger menu or when a grid layout switches from multiple columns to a single column).
Check that images, text, and other media scale correctly without distortion or overlap.

How to target BAgel components

BAgel components are built as web components with encapsulated shadow DOM.
Do not access elements inside the shadow root directly in your tests.

Correct – test user-facing behaviour:

Clicking on a button

const button = await page.locator('ba-button');
await button.evaluate((el) => el.click());

Test What the User Sees and Does

Use ARIA roles, accessible labels, or visible text to locate elements.
Use Playwright's queries such as: getByRole, getByLabel, getByText.

Why Not Target Shadow DOM?

Shadow DOM encapsulation ensures component internals can change safely.
Tests should validate public-facing behaviour, not implementation details.
Direct access to shadow DOM is not forward-compatible with BAgel.

Testable Without Shadow Access

If you are unable to interact with a component without accessing the shadow DOM, raise an issue or feature request with the BAgel team.