Modals Guided Test
Dialogs, pop-ups, and overlays must work for keyboard and screen reader users. When a modal opens, focus must move into it. While it is open, focus must stay inside it and the page behind it must be hidden from assistive technology. The modal must be closable with the keyboard, and when it closes, focus must return to the control that opened it.
The Modals test checks one modal at a time. You say how the modal opens and pick the control that opens it, or the open modal itself. The extension then opens the modal, moves through it with real Tab presses, presses Escape, tries its close control and its backdrop, and watches where focus goes at each point. It asks you to confirm each result, with the answers already filled in from what it observed.
Every answer comes from the automated checks in the browser, so the test does not use Verify with AI and does not use AI credits. The same page gives the same answers on every run.
When to use this
Use this test on pages with dialogs, confirmation pop-ups, cookie or consent overlays, and session-timeout dialogs.
Prerequisites
The TestMu AI Accessibility Toolkit is installed. See Install Toolkit.
What the test checks
| Rule | WCAG | Severity |
|---|---|---|
| Modal does not expose a dialog role | 4.1.2 (A) | Critical |
| Modal has no accessible name | 4.1.2 (A) | Serious |
| Page behind the modal is not hidden from assistive technology | 1.3.2 (A) | Serious |
| Focus does not move into the modal when it opens | 2.4.3 (A) | Critical |
| Focus is not trapped inside the open modal | 2.4.3 (A) | Serious |
| Focused element is completely hidden behind the modal | 2.4.11 (AA) | Serious |
| Focused element is partially hidden behind the modal | 2.4.12 (AAA) | Moderate |
| Escape does not close the modal | 2.4.3 (A), best practice | Moderate |
| Modal cannot be closed with the keyboard | 2.1.2 (A) | Critical |
| Focus does not return to the trigger when the modal closes | 2.4.3 (A) | Serious |
The Escape rule is a best practice. It follows the best-practice switch in DevTools Settings, like the best-practice rules of a normal scan.
The report includes only the rules that fall within the WCAG version and level you set in DevTools Settings.
Run the test
Start the test
Open Assisted Tests in Accessibility DevTools and select Modals. See Start a guided test.
Pick the modal
First, say how the modal opens:
- The modal has a launcher. Pick the launcher and let the test open the modal, so that it can see where focus goes.
- The modal opens another way, for example a session-timeout dialog. Open it yourself, and then pick the open modal.
There are two equivalent ways to pick an element:
- Select using mouse. Click the element on the page with the crosshair picker.
- DOM Selector. Expand the DOM tree in the panel and select the element there.
If you pick an element inside a modal that you opened, the test moves the pick to the dialog that contains it, and the panel tells you so.
When the page has no dialog markup, the test picks the largest new overlay and shows a confirmation screen before it runs any checks. The screen shows the overlay's accessible name and asks whether this is the modal:
- Select Yes and then Yes, run the checks to run the checks on that overlay.
- Select No and then Next question to go on without checking it.
- Select Highlight all on the page to see the overlay highlighted on the page before you answer.
If the test cannot find an overlay after the launcher runs, it shows Could not detect the modal. Select Try again to run the launcher again, or Skip this modal to go on without it.
The page must have focus for a pick to register. If you were last working in the DevTools panel and your click on the page is not picked up, click once on an empty part of the page, and then click the element again.
Let the test run the checks
Select Run the checks. The test walks the open modal forward with Tab and backward with Shift+Tab, presses Escape, activates a close control from the keyboard, and clicks the backdrop.
The test never activates a control that could have side effects, such as Accept, Submit, a link that leaves the page, or a form button.
Confirm the results
For each modal, the test asks seven questions:
- Does focus move into the modal when it opens?
- Does Tab keep focus inside the modal?
- Which elements did Tab reach outside the modal?
- Does Escape close the modal?
- Do the close controls work?
- Does focus return to the trigger when the modal closes?
- Is there another modal to test?
Each answer is filled in from the checks. When a measurement is not conclusive, the answer is left blank and the row says why. You can change any answer.
For the third question, the test lists every element that Tab reached outside the modal, and says for each one whether the dialog or its backdrop hides it fully, partly, or not at all.
If the checks cannot run, for example because another DevTools window holds the tab, the questions are shown blank and you answer from what you see. The markup checks still run.
Test another modal
The last question asks if there is another modal to test. Answer Yes to go back to the Pick step for the next modal. The answers for the modals you already tested are kept, and the findings for every modal go into one report, so one run can cover every modal on the page.
Finish the test
Finish the test to generate the report. Each finding opens in a pane with three tabs:
- Element Details shows the element the finding is about.
- How to fix explains how to fix the issue for that rule.
- Image View shows the dialog as it was during the checks, not the closed page.
Resume a test
Your progress is saved, so you can close the panel and continue later. If you leave in the middle of a test, the next time you open the Modals test it shows Resume your Modals test?. Select Resume to continue where you left off, or Start over to begin a new test.
Product boundary
- The test checks one modal at a time. Pick each modal you want to cover.
- The test does not activate Accept, Submit, form buttons, or links that leave the page, so it does not cover what happens after those controls are used.
- The test checks how each modal behaves, not whether its content is clear or useful.
Chat with Us