Use Cases

Improving Website Accessibility for Screen Reader Users

Screen reader users struggle to understand and navigate between different website pages because all the navigational buttons are read out as “Buttons.” By using Oobee, agencies can:

• Scan the entire website to identify accessibility-related code issues and generate a comprehensive report.
• Utilise the report to quickly identify similar code issues and reference the relevant WCAG clauses for more information and potential solutions.
• If the affected code is part of a component, addressing it at the component level may enhance accessibility across all other pages that use that component.
• Use the other accessibility issues identified in the report to help plan the team’s accessibility roadmap.

Prioritising Accessibility Improvements

To assist agencies in improving their websites’ accessibility, the Oobee report categorises accessibility issues into two groups: “Must-Fix” and “Good-to-Fix.”

Must-Fix Issues: These issues require immediate attention as they create significant barriers for PWDs, preventing access to essential content or features. For instance, missing form labels hinder accessibility because they are vital for screen reader users to understand input expectations and navigate forms effectively.

Good-to-Fix Issues: While these issues may present challenges for PWDs, they do not entirely block access to essential content or features. For example, ensuring that all page content is organised within appropriate landmarks can facilitate easier navigation for screen reader users. Content outside of these landmarks may be hard to locate, and its purpose can be unclear, making it inconvenient for screen reader users.

Users should prioritise addressing “Must-Fix” issues first to prevent excluding PWDs. To aid in prioritisation, the report provides additional details on each issue, including:

• Why it Matters: An explanation of the impact and implications of the issue on accessibility.
• WCAG Success Criteria Conformance: Identification of the specific violation of the WCAG associated with the issue.
• Location of Each Occurrence: The specific areas or pages where the issue is present on the website or platform.
• Recommended Fixes: Suggestions and guidance on how to effectively address and resolve the issue.
  
  

Continuously Scanning for Website Accessibility

Scenario: An agency website is currently in a sprint focused on implementing accessibility fixes. A DevOps engineer at the agency wants to verify that these fixes have not disrupted any other parts of the codebase.

To achieve this, the engineer can run Oobee on any CI/CD tool that supports Docker-based runners.

The following instructions are specifically for SHIP-HATS GitLab, outlining the steps to implement Oobee in the CI/CD pipeline:

1. Create a SHIP-HATS GitLab Testing Pipeline within your project.

2. Build and push the Docker container:

   a) Oobee can be installed in a container environment using the provided Docker template in the Dockerfile.

   b) Build the image and push it to your GitLab project’s container registry.
   
   

   # Checkout the Oobee repository
   git clone https://github.com/GovTechSG/purple-a11y.git
   
   # Navigate to purple-a11y
   cd purple-a11y
   
   # Build the image locally
   # Refer to Colima on how to run Docker https://github.com/abiosoft/colima
   docker build --platform linux/amd64 -t purple-a11y .
   
   # Login to your container registry with you username and personal access token
   # You may generate personal access tokens with read registry and write registry permissions at
   # https://sgts.gitlab-dedicated.com/-/user_settings/personal_access_tokens
   # Your GitLab username is usually your e-mail address without the domain
   # You may have to turn off WARP if you encounter `Error response from daemon: Get "https://registry.sgts.gitlab-dedicated.com/v2/": tls: failed to verify certificate: x509: certificate signed by unknown authority`
   docker login registry.sgts.gitlab-dedicated.com
   
   # Tag your image ready for SHIP GitLab
   docker tag purple-a11y:latest registry.sgts.gitlab-dedicated.com/<GitLab username>/<project name>
   
   # Ensure you have created a GitLab project containing Oobee's sample .gitlab-ci.yml
   # Push to the GitLab container registry
   docker push registry.sgts.gitlab-dedicated.com/<GitLab username>/<project name>
   

3. Configure the pipeline on GitLab:

   a) If you haven’t already, create a .gitlab-ci.yml file in the test pipeline using the GitLab Editor.

   b) Copy the contents from gitlab-pipeline-template.yml and adjust the following settings:

       i) Set any tags needed to identify the GitLab runner for your pipeline, such as ship_docker.

       ii) Replace the placeholder with the URL of the Docker image.

       iii) Modify the accessibility scan parameters to specify the type of scan you wish to run:
   
   

   # Location of where you uploaded the docker image to registry
   DOCKER_IMAGE: registry.sgts.gitlab-dedicated.com/<GitLab username>/<project name>:latest
   
   # URL of the website or sitemap
   A11Y_SCAN_URL: "https://example.com"
   
   # Set the scan type [choices: "sitemap:", "website"]
   A11Y_SCAN_TYPE: "website"
   
   # Set the maximum number of pages to scan [default: 100]
   A11Y_SCAN_MAX_NUM_PAGES: 100
   
   # Zip filename of the artifact
   A11Y_SCAN_ARTIFACT_NAME: "ally-scan-results.zip"
   
   # Name:E-mail for telemetry data
   A11Y_SCAN_NAME_EMAIL: "John Doe:john@domain.com"
   

       iv) Commit the changes to GitLab.

   c) Verify that the pipeline has started by navigating to your project > CI/CD > Jobs. You should see the job complete, along with the following information:

       i) A summary of the total issue count and a breakdown of the issues will be displayed in the job log.

       ii) A generated Oobee report can be downloaded from the “Job artifacts” panel on the right side, as illustrated in the screenshot below.

Once the user has configured and executed an accessibility scan in the GitLab CI/CD pipeline, the results will be uploaded as a Job Artifact.

The user can access the scan results by navigating to the CI/CD Job page and clicking the Download button under Job artifacts to view the report.html file containing the Oobee report.