
_This post was written Monday, March 20th, 2023._

Today was an _adventure_. And in a good way! 😊 Quite a few funny things happened, but it's currently after 11:00pm and I'm too tired to remember them all.

First, some context: My fiancé recently moved his desk to our space-y living room. We used to share a room as an office. The layout was slightly cramped with our 2 dogs' giant pile of pillows and blankets, and it was often difficult to figure out who could have their microphone on at various times of the day. It was also easy for me to get distracted sometimes when he was on his microphone. But since he volunteered to move his desk, I have my own office!

We love the new set up. I like to physically compartmentalize my work space away from my life space (so grateful for the privilege). It used to mean that my fiancé would continue to hang out and game in the room we shared while I spent my after work time in the living room. Now we're in close proximity during these times! It's so fun that I can play games on our living room TV while he plays games on his computer next to the couch. 💖

With the context out of the way: I've been slowly working on making the room a cute and cozy space. Being cozy while working is a necessity for me. I have an easier time keeping my mind clear and focused when I'm comfy. One of my favorite things about working from home is that I can wear sweatpants _all the time_.

One of today's tasks for cozy-fying my office was cleaning a little box fan. Since we have dogs, the fan can collected a lot of dog hair and dust. Unfortunately this lil' brain of mine forgets about this until it's very visible on the fan. 😅

This is really unhelpful for the yearround sinus issues I experience! In the springtime (which is basically now in Indiana, or something we like to call fake spring lol) my sinus issues get worse and I tend to get more migraines than usual. Plus, the fan was not pretty to look at. Can't have that in what's supposed to be cozy room now can we???

To clean the fan, I needed to go to my car to get the cleaning supplies. They were in there because I take them to my Grandma's house when I clean over there. Here are the events that followed in this adventure:

1. Found easy shoes to wear to the car
2. Decided to take the trash out while I was at it
3. Fiancé decided to come outside with me and enjoy the weather
4. I used my key fob to unlock my car
5. We took the trash out together on the way to my car
6. My car had decided to lock itself at some point, so I gave it the bird
7. We walked to the mailbox to check it
8. Fiancé decided he wanted to take the dogs on a mini walk while I went back out to my car
9. Proposed an adventure: we could all go pick up a package together and enjoy a short Windows Down Day drive
10. We went out to get my package
11. We went to the gas station to get cold drinks
12. Finally, we got home and all went inside
13. I completely forgot my cleaning supplies in my car
14. Went to the car again and grabbed the supplies
15. Realized that this entire thing started with me wanting to clean a fan
16. I cleaned the fan outside and enjoyed thinking about how fun and classically ADHD this was

I also spent time thinking about how to share my experience for other people to laugh about. There are a lot of tips & life hacks I've wanted to share too. In the year (and a few days) since being officially diagnosed with ADHD, I've learned so many helpful things that make my life easier and bring me further in accepting & loving my brain & body.

I've also really missed writing. This is my first post of 2023! I spent the end of 2022 working on trauma healing and burnout recovery, so there was a lot I wanted to do but couldn't. I'm not magically healed now 3 months later, but I'm feeling good again and ready to continue creating art from the things I've experienced and am experiencing.

This brings me to this new series: [My Neurodivergent Narratives](/blog/series/my-neurodivergent-narratives). I plan to write as much as my brain allows me about my journey as a late-diagnosed neurodivergent. I'm very proud of my progress, and I know I have lots of goodies to share that can potentially help someone else. I also hope to aggressively challenge many stigmas I've come to understand better, in a way that helps other people love and accept themselves more.

I'm still learning of course, and I am no spokesperson of the neurodivergent community. What I write about here is my own experience. I'll probably get some things wrong! I've been afraid of that for a while because I'm still so new in my journey. But I've also come a long way and want to spread the love and acceptance as far as possible.

We're all doing the best we can with what we have, and that is 100% enough. 💗


I tried to clean a fan. I ended up doing a whole bunch of other stuff. And almost forgot to clean my fan.

My Neurodivergent Narratives

My Neurodivergent Narratives #1


The `aria-label` property can be extremely useful when used correctly. When used incorrectly, it can wreak havoc on speech-input user experiences. It's an easy mistake to make and luckily it's pretty easy to fix!

## What is the `aria-label` property?

As defined by the WAI ARIA 1.2 standards, [the `aria-label` property](https://www.w3.org/TR/wai-aria-1.2/#aria-label) "defines a string value that labels the current element". It has the same purpose as [the `aria-labelledby` property](https://www.w3.org/TR/wai-aria-1.2/#aria-labelledby), which references another element that labels the current element. The purpose of both of these properties is to provide an [Accessible Name](https://www.w3.org/TR/accname-1.1/#dfn-accessible-name) of the current element.

Related to these properties is the `aria-describedby` property, which references another element that describes the current element. The purpose of this property is to provide an [Accessible Description](https://www.w3.org/TR/accname-1.1/#dfn-accessible-description) for the current element. The Accessible Name should be short and concise, and the Accessible Description should be more verbose and complement the Accessible Name.

The Accessible Name is part of what screen readers use to announce elements to a user when they come into focus. A `<button>` with no `aria-label` and plain text between its opening and closing tags would have an Accessible Name that matches its plain text. That same `<button>` can have its Accessible Name overridden with something completely different using the `aria-label` property.

Use the next two example code snippets to compare how the same button sounds with and without an `aria-label`.

<CallOut id="example-1" title="Example 1: <button> with no aria-label" type="example">

The code:

```html
<button>OK</button>
```

The output:

<br />
<button>OK</button>

</CallOut>

<CallOut id="example-2" title="Example 2: <button> with an aria-label" type="example">

The code:

```html
<button aria-label="Confirm selection">OK</button>
```

The output:

<br />
<button aria-label="Confirm selection">OK</button>

</CallOut>

## Why does `aria-label` need to match the visible label?

First of all, an `aria-label` must match its element's visible label because there is a Level A WCAG Success Criterion that says so. [SC 2.5.3: Label in Name](https://www.w3.org/TR/WCAG21/#label-in-name) says:

> For user interface components with labels that include text or images of text, the name contains the text that is presented visually.

This means that the Accessible Name computed for an element should contain the text of the element's visual label. One best practice for this is to have the Accessible Name start with the visual label's text. So if a link contains the text "Learn more" and the author of that link wants to include more information about the link's purpose in the `aria-label`, a good practice is to start the `aria-label` with "Learn more".

If you're like me and my ADHD brain, you might need a little more reasoning than "the rules say so" to motivate you to follow the rules. A lot of people don't like being told what to do, and that's fine!

So why do we need to follow Success Criterion 2.5.3? It partially has to do with speech-recognition technology. As it turns out, the Accessible Name for elements is how speech-input users can interact with elements in a web page.

Referencing our two previous examples:

- A speech-input user can activate the button from [Example 1](#example-1) by saying "Click OK". This is because the Accessible Name for that button is "OK".
- A speech-input user cannot activate the button in [Example 2](#example-2) in the same way. This is because the Accessible Name for that button is "Confirm selection". If a speech-input user wanted to activate this button, they would have to say "Click confirm selection".

For speech-input users that rely on visual labels to come up with voice commands, there no way for them to know before speaking a command if the Accessible Name of an element differs from its visual label. They will have to speak a command and find out if it does or does not work. If a command doesn't work, they may retry a couple of times. And if the command actually does not work at all because the Accessible Name doesn't match the visual label, their energy has been wasted and they're also stuck.

## What happens when `aria-label` doesn't match the visible label?

As I wrote this article, I started to learn about Voice Control on Mac. I wanted to see if I could find a real world example of speech-input navigation being broken due to mismatched visual labels and accessible names. I found a couple of examples right on the Twitter home page.

Unfortunately, more than half of the main navigation links have accessible names that don't match their visual labels. Even in the cases where a link's `aria-label` began with the text in the visual label, I was not successful in activating those links with speech-input. I made countless attempts.

- Home: The `aria-label` for this link is dynamic. If there are unread tweets in a user's feed, then the `aria-label` reads "Home (New unread Tweets)". The "Click Home" command only activates this link if there are no unread tweets.
- Explore: The `aria-label` for this link is "Search and explore". Saying "Click Explore" does not activate this link.
- Notifications: The `aria-label` for this link is dynamic. If a user has 2 notifications for example, the `aria-label` is "Notifications (2 unread notifications)". The "Click Notifications" command only activates this link if a user has 0 unread notifications.
- Messages: The `aria-label` for this link is dynamic. If a user has unread messages from one other user, for example, the `aria-label` is "Direct Messages (1 unread conversation)". If there are no unread messages, the `aria-label` is "Direct Messages". The "Click messages" command does not ever work.

Here's a quick demo of me trying to activate the "Messages" link that shows on the home page of Twitter:

<iframe
  title="Voice Control Demo - Twitter Messages link"
  width="100%"
  height="350"
  src="https://www.youtube-nocookie.com/embed/FBiKOt-ipO0"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

## Are there other users that benefit from `aria-label` matching the visible label?

This article primarily focuses on the sighted speech-input user's experience, but there are other users affected by this issue as well. Think of a sighted screen reader user that comes across the `<button>` element in [Example 2](#example-2). It is presented by their screen reader as "Confirm selection, button", but the text in the button says "OK".

This can be a very confusing and stressful experience for the user. How can they be certain the issue is with the website and not their own action? We're imposing an extra cognitive load on the user to process the mismatched audio and visual experiences. There is also extra cognitive load required to first memorize the behavior, and then recall it the next time they come across the element.

It's not necessary or kind to do this to users. It's energy-draining, and energy is an extremely limited resource for all kinds of people who rely on accessible interfaces.

## How do I fix mismatched `aria-label`s and visual labels?

Now that you know mismatching `aria-label` and visual labels is harmful for speech-input users, how do you go about preventing that harm? First, I'd recommend reading [Playing with state](https://sarahmhigley.com/writing/playing-with-state/) by Sarah Higley and [Be Careful with Dynamic Accessible Names](https://adrianroselli.com/2020/12/be-careful-with-dynamic-accessible-names.html) by Adrian Roselli.

Second, think about whether or not you need to provide an `aria-label` for the element that differs from its visual label. Some cases that come to mind:

- Are there duplicate visual labels?
  - Your markup can generally be improved by ensuring all visual labels are unique. This is beneficial for screen reader navigation.
  - The speech recognition technology probably has a way to help the user choose which element they want. With Voice Control on Mac, a number appears next to the elements with matching Accessible Names after the command is spoken. Then you're able to say the number of the element you want to activate.
- Is the content of the element plain text? Omit the `aria-label` property. The computed accessible name for the element will be its text content.
- Is the element a toggle button? Reference the [Playing with state](https://sarahmhigley.com/writing/playing-with-state/) article I mentioned and also check out the [Toggle Buttons](https://inclusive-components.design/toggle-button/) writeup from Inclusive Components. The `aria-pressed` property better suits your needs than a dynamic `aria-label`.

After you've spent time thinking thoroughly about your `aria-label`s and visual labels, make the updates and **test them with your users**. It's hard for us to know if something is usable if it doesn't intersect with our own needs. The only experiences we can truly be experts of are our own. Don't miss the step where you get your information from the source of truth: your users with expertise in their lived experiences.

## Related resources

- [Designing and coding for voice](https://www.briandeconinck.com/designing-coding-voice/)


Users suffer when the accessible name of an element doesn’t match its visual label.

Don’t Overwrite Visual Labels With `aria-label`

Despite being answered time and time again, the button vs. link question prevails.

Should I Use a Button or a Link?

If you've been working in web accessibility for a while, you know there are many foundational quick-wins that can go a long way. If you're new to web accessibility, hopefully this doesn't come as a surprise! There are definitely challenging aspects to web accessibility, but it's not all that way. And lucky for us, a lot of the quick-wins are also quick and easy to identify with some automated tools! [`pa11y-ci`](https://github.com/pa11y/pa11y-ci) is just one of those tools.

In this post, I'll show you how I set up a [GitHub Action](https://github.com/features/actions) that runs `pa11y-ci` as a pull request check. The check will run against a Vercel deploy preview, and then the results will be shared as a comment on the pull request for easy visibility.

If at any point you find yourself stuck or needing to troubleshoot, check out a GitHub repository I created that represents the end-result of this guide: https://github.com/ashleemboyer/pa11y-ci-test-app.

## Step 1 (optional): Create a Next.js App

If you don't already have a Next.js App to follow along with, I recommend creating one. There are multiple ways of doing this detailed on [the Next.js Getting Started page](https://nextjs.org/docs/getting-started). To keep things simple for this example, I'm using the Automatic Setup approach.

**To create the Next.js app:**

1. Open a terminal
2. Run `npx create-next-app@latest`
3. When prompted, name the app `pa11y-ci-test-app`
4. Change directory into the new folder: `cd pa11y-ci-test-app`
5. Briefly explore the code and learn your way around

Note: I will be using `npm` instead of `yarn` for the rest of this post. If your generated project uses `yarn`, and you would also like to to use `npm` instead:

1. Run `rm yarn.lock` to delete the file
2. Run `npm install` to create a `package-lock.json` file
3. Run `npm run build` so the `package-lock.json` file can be patched if needed
4. Run `npm install` one more time to download any missing dependencies
5. Run `git add .` to stage the changed files for a commit
6. Run `git commit -m "Using npm instead of yarn"` to commit the changes

## Step 2 (optional): Create and Connect a GitHub Repository

If you followed step 1 and created a new Next.js App, you should follow this step as well. You will need a GitHub Repository for your project in order to run the GitHub Action we're creating.

**To create the GitHub Repository:**

1. Go to [github.com/new](https://github.com/new)
2. If needed, log in to your account
3. Under "Owner", select your account
4. Under "Repository name", enter `pa11y-ci-test-app`
5. Select either "Public" or "Private"
6. Click the "Create repository" button
7. Leave this page open in your browser

**To connect the GitHub Repository to your project:**

1. In a terminal, go to your project folder
2. Run `git remote add origin git@github.com:<YOUR-USERNAME>/pa11y-ci-test-app.git` after replacing `<YOUR-USERNAME>` with the GitHub username you used to create the repository. (Read about [Working with Remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) and [Remote Branches](https://git-scm.com/book/en/v2/Git-Branching-Remote-Branches) if you're curious.)
3. Run `git push -u origin main` to push the code to the repository.
4. Verify these steps were successful by refreshing your new repository's page in your browser

## Step 3: Install and Configure `pa11y-ci`

It's always good to test new tools locally (on your machine) before testing them remotely in a place like a pull request. Testing remotely can be tedious and time consuming, and the results of the testing can also be more difficult to locate and read. And if you happen to be like me and have ADHD, all of that is a recipe for multiple distractions!

Before doing anything else, let's create a new git branch. That will be useful later when we need to create a pull request for our GitHub Action.

**To create a new `git` branch:**

1. In a terminal, go to your project folder
2. Run `git checkout -b add-pa11y-ci`

**To install `pa11y-ci`:**

1. In a terminal, go to your project folder
2. Run `npm install --save-dev pa11y-ci`
3. Open the `package.json` file in your project
4. Verify the `pa11y-ci` package is listed under `devDependencies`

**To configure `pa11y-ci` for local testing:**

1. In your project folder, create a file called `.pa11yci`
2. In the new file, paste the following JSON:

```json
{
  "urls": ["http://localhost:3000/"]
}
```

This configuration tells `pa11y-ci` exactly what `urls` in our app it needs to test.

## Step 4: Test `pa11y-ci` locally (on your machine)

Now that we have `pa11y-ci` installed and configured for local testing, we can get to testing!

1. In your project folder, open the `package.json` file
2. Under the `"scripts"` property, add a new entry: `"pa11y-ci": "pa11y-ci"`
3. Open two separate terminals to your project folder
4. In the first terminal, run `npm run dev` to start the app
5. In the second terminal, run `npm run pa11y-ci` to run the new script we added in step 2

After `pa11y-ci` has finished running, this is how the output should read:

```
> pa11y-ci-test-app@0.1.0 pa11y-ci
> pa11y-ci

Running Pa11y on 1 URLs:
 > http://localhost:3000/ - 1 errors

Errors in http://localhost:3000/:

 • The html element should have a lang or xml:lang attribute which describes the language of the document.

   (html)

   <html><head><meta name="viewport" con...</html>

✘ 0/1 URLs passed
```

Hooray! We have an error, but the good news is that means `pa11y-ci` is working! Now we can progress from local testing towards creating our GitHub Action.

## Step 5: Deploy to Vercel

Our current configuration for `pa11y-ci` only works for when we run our app locally with `npm run dev`. For remote testing, we want `pa11y-ci` to test against real builds and public-facing urls. In order to do that, we need to deploy our Next.js app. We'll use Vercel in this example.

**How to deploy to Vercel:**

1. Go to [vercel.com/new](https://vercel.com/new)
2. If needed, log in to your account
3. Under "Import Git Repository", select "Continue with GitHub"
4. Search for your new repo (mine is called `pa11y-ci-test-app`)
5. Click the Import button in-line with the repo name
6. Click the Deploy button (you should not need to change any configuration)

Once the deploy is complete, you can close this window.

## Step 6: Install and Configure `next-sitemap`

There's another way `pa11y-ci` can be used to test against urls, and that is with the `--sitemap` option. This option is nice when you have a `sitemap.xml` file on your site that updates every time a build occurs. It means you don't have to manually update the `.pa11yci` file's list of urls every time a new page is added. The tool we'll use for generating a `sitemap.xml` file is called [`next-sitemap`](https://www.npmjs.com/package/next-sitemap), which is the tool I use on my own website for `pa11y-ci` testing.

**To install `next-sitemap`:**

1. In a terminal, go to your project folder
2. Run `npm install next-sitemap`

**To configure `next-sitemap`:**

1. In your project folder, create a new file called `next-sitemap.config.js`
2. In the new file, paste the following JavaScript:

```javascript
module.exports = {
  siteUrl: process.env.VERCEL_URL
    ? `https://${process.env.VERCEL_URL}`
    : 'http://localhost:3000/',
};
```

This tells `next-sitemap` what the main url of your site is. If you use a different port number than `3000`, make sure to update the code above to match the port number you use.

## Step 7: Test `next-sitemap` locally (on your machine)

To make sure we have everything configured correctly, we're going to test `next-sitemap` locally just like we did with `pa11y-ci`.

1. In your project folder, open the `package.json` file
2. Under the `"scripts"` property, add a new entry: `"postbuild": "next-sitemap"`
3. In a terminal, go to your project folder
4. Run `npm run build`

The new `postbuild` script we added will run automatically after the `build` script has completed. You should see some new `sitemap` files in the `public` directory. We will add those to the `.gitignore` file in the next section.

You should also see something like this output in the terminal after the `build` script output:

```
> pa11y-ci-test-app@0.1.0 postbuild
> next-sitemap

✨ [next-sitemap] Loading next-sitemap config: file:///pa11y-ci-test-app/next-sitemap.config.js
✅ [next-sitemap] Generation completed
┌───────────────┬────────┐
│    (index)    │ Values │
├───────────────┼────────┤
│ indexSitemaps │   1    │
│   sitemaps    │   1    │
└───────────────┴────────┘
-----------------------------------------------------
 SITEMAP INDICES
-----------------------------------------------------

   ○ http://localhost:3000/sitemap.xml


-----------------------------------------------------
 SITEMAPS
-----------------------------------------------------

   ○ http://localhost:3000/sitemap-0.xml
```

## Step 8: Prepare for and Create a New Pull Request

Hopefully you created a new git branch called `add-pa11y-ci` [in Step 3](#step-3-install-and-configure-pa11y-ci), but it's also okay if you didn't! Go ahead and create it now. We'll need a different branch off of the main one in order to create a pull request in our GitHub repository.

**To prepare for the pull request:**

1. Make sure there is a `/public/sitemap*` entry in the `.gitignore` file. We **do not** want to commit these files since they need to be generated by the Vercel build process.
2. Make sure you have all your new `pa11y-ci` and `next-sitemap` work committed. I'm committing everything at once with the message: `"Adding pa11y-ci and next-sitemap"`.
3. Run `git push --set-upstream origin add-pa11y-ci` to push your new branch up to the repository.

**To create the new pull request:**

1. Go to `github.com/<YOUR-USERNAME>/pa11y-ci-test-app/compare` after replacing `<YOUR-USERNAME>` with the GitHub username you used to create the repository
2. Change the `compare` branch to `add-pa11y-ci`
3. The page should update have at least these 5 changed files:
   - `.gitignore`
   - `.pa11yci`
   - `next-sitemap.config.js`
   - `package-lock.json`
   - `package.json`
4. Click the "Create pull request" button
5. You should see 2 text boxes: one for the name of the pull request and one for the description
6. Fill in the title and description however you need
7. Click "Create pull request"

**To verify everything is set up correctly:**

1. Wait for the `vercel` bot to comment on the new pull request
2. In the new comment, open the "Visit Preview" link in a new tab
3. You should see your app built and running
4. Go to the `/sitemap.xml` page in the same app
5. You should see an XML file with contents that look something like this:

```xml
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>YOUR-APP-URL/sitemap-0.xml</loc>
  </sitemap>
</sitemapindex>
```

## Step 9: Create the pa11y-ci GitHub Action

Now that we have a live website to have `pa11y-ci` test against, we can create the GitHub Action that runs `pa11y-ci`.

**To create the GitHub Action:**

1. In your project folder, create a new folder called `.github`
2. In the new `.github` folder, create another folder called `workflows`
3. In the new `workflows` folder, create a new file called `pa11y-ci.yml`
4. Paste the following content in your new file:

```yml
# Wait to run until after the Vercel deployment has finished
# https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#deployment_status
on: deployment_status

jobs:
  pa11y-ci:
    # Only run if the Vercel deployment was successful
    # https://docs.github.com/en/developers/webhooks-and-events/webhooks/webhook-events-and-payloads#deployment_status
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest

    steps:
      # Checkout latest commit of repo
      # https://github.com/actions/checkout#checkout-v3
      - uses: actions/checkout@v3

      # Install project dependencies
      - run: npm install

      # Run pa11y-ci against the generated sitemap
      # https://github.com/pa11y/pa11y-ci#sitemaps
      - run: npm run pa11y-ci -- --sitemap ${{ github.event.deployment_status.target_url }}/sitemap.xml
```

Before committing and pushing this new file, make sure to delete the `.pa11yci` file. It's no longer needed.

**To verify the GitHub Action works:**

1. Commit and push the new `.github/workflows/pa11y-ci.yml` and the removed `.pa11yci` file
2. Go to your pull request in a browser
3. Towards the bottom of the page, wait until you see the `pa11y-ci` check finish
4. The check should fail
5. Click the "Details" link to inspect the failed check
6. You should see the same error that you saw when testing locally in [Step 4](#step-4-test-pa11y-ci-locally-on-your-machine)

## Step 10 (optional): Update the pa11y-ci GitHub Action to add a comment on pull requests

When I added this `pa11y-ci` GitHub Action to my own site's pull requests, I decided to make it also comment results on the pull request. There are a couple of reasons for this:

- Normally you have to click the "Details" link next to a failed pull request check. This takes you to another page and away from the pull request. For me, that means an opportunity to get easily distracted.
- The formatting of results in pull request checks can sometimes be difficult to read. Putting the results in a pull request comment gives an opportunity to re-format them in a more readable way.

So to update the GitHub Action to comment on pull requests, we'll need to tell the `pa11y-ci` command to output its results in a different way, and then we'll add a step to the GitHub Action that reads the output, formats it, and creates a comment.

1. Update the `pa11y-ci` `run` step in `.github/workflows/pa11y-ci.yml` to be:
   ```yml
   # Run pa11y-ci against the generated sitemap
   # https://github.com/pa11y/pa11y-ci#sitemaps
   - run: npm run pa11y-ci -- --json --sitemap ${{ github.event.deployment_status.target_url }}/sitemap.xml |& tee pa11y-output.txt
   ```
2. Add a new step at the end of the file like this:
   ```yml
   # Comment the formatted pa11y-ci results on the PR
   - uses: actions/github-script@v5
     env:
       BODY_PREFIX: ''
     with:
       script: |
         const script = require('./.github/workflows/scripts/pa11y-ci.js')
         await script({ context, core, github })
   ```
3. Add a new folder inside `.github/workflows` called `scripts`
4. Add a new file to `scripts` called `pa11y-ci.js`
5. In the new file, paste the following JavaScript:

   ````js
   const { promises: fs } = require('fs');

   module.exports = async ({ context, core, github }) => {
     // Find this PR & do nothing if this isn't a PR
     const { data } =
       await github.rest.repos.listPullRequestsAssociatedWithCommit({
         owner: context.repo.owner,
         repo: context.repo.repo,
         commit_sha: context.sha,
       });
     const prNumber = data[0] && data[0].number;
     if (!prNumber) {
       return;
     }

     // Read the pa11y output and build the comment body
     const pa11yOutput = await fs.readFile('./pa11y-output.txt', 'utf8');
     const lines = pa11yOutput.split('\n');
     const asJSON = JSON.parse(lines.find((line) => line.startsWith('{')));
     const { total, errors, results } = asJSON;

     let commentBody = `${process.env.BODY_PREFIX}\n<h2>:microscope: pa11y-ci results</h2>\n\n`;
     commentBody += `- Number of URLs tested: ${total}\n`;

     if (!errors) {
       commentBody += `- No errors were found! :tada:\n`;
     } else {
       commentBody += `- Number of errors found: ${errors}. :sob:\n`;

       let formattedOutput = '';
       Object.keys(results).forEach((urlKey) => {
         const errors = results[urlKey];
         if (errors.length < 1) {
           return;
         }

         formattedOutput += `- [${urlKey}](${urlKey}):\n\n`;
         errors.forEach((error) => {
           formattedOutput += '  ```\n';
           formattedOutput += `  ${error.message}\n\n`;
           formattedOutput += `  ${error.selector}\n\n`;
           formattedOutput += `  ${error.context}\n\n`;
           formattedOutput += `  ${error.code}\n`;
           formattedOutput += '  ```\n\n';
         });
       });

       commentBody += `<details><summary>See results :eyes:</summary>\n\n${formattedOutput}</details>`;
     }

     // Get the comments on this PR
     const { data: comments } = await github.rest.issues.listComments({
       owner: context.repo.owner,
       repo: context.repo.repo,
       issue_number: prNumber,
     });

     // Try to find an existing pa11y results comment
     const previousComment = comments.find((comment) =>
       comment.body.startsWith(process.env.BODY_PREFIX),
     );
     if (previousComment) {
       // Update the previous comment
       await github.rest.issues.updateComment({
         owner: context.repo.owner,
         repo: context.repo.repo,
         comment_id: previousComment.id,
         body: commentBody,
       });
     } else {
       // Create a new comment
       await github.rest.issues.createComment({
         owner: context.repo.owner,
         repo: context.repo.repo,
         issue_number: prNumber,
         body: commentBody,
       });
     }

     if (errors) {
       core.setFailed('Errors were found by pa11y-ci');
     }
   };
   ````

6. Commit and push the changes to `.github/workflows/pa11y-ci.yml` and the new `.github/workflows/scripts/pa11y-ci.js` file.

**To verify that everything is working as expected:**

1. Go to your pull request in your browser
2. Wait for the `pa11y-ci` check to finish
3. The check should fail just like it did before
4. Look for a comment by the `github-actions` bot that says "🔬 pa11y-ci results"
5. The comment should say that 1 error was found
6. Expand the "See results 👀" text
7. There should be one error listed that matches the same error you've been seeing

## Step 11. Celebrate! 🎉

Nicely done! You've added a `pa11y-ci` GitHub Action that runs on pull requests. You should be proud. Give yourself a pat on the back. 😊

Use pa11y-ci to test deploy previews before merging pull requests.

Ashlee M Boyer

Recommended writings

Most recent writings