How to Test Modal Focus Trap with Playwright: Complete 2026 Guide

1. Why Testing Modal Focus Traps Is Harder Than It Looks

A modal dialog looks simple on the surface: render a box, dim the background, show some content. But the keyboard behavior that makes a modal accessible is a tightly choreographed sequence of focus management events. The WAI-ARIA Dialog pattern (APG) requires that when a modal opens, focus moves to the first focusable element inside it. When the user presses Tab at the last focusable element, focus must wrap back to the first. When the user presses Shift+Tab at the first element, focus must wrap forward to the last. When the user presses Escape, the modal must close and focus must return to the element that originally triggered it.

That is already four distinct behaviors to test, and it gets more complex from there. The modal must set aria-modal="true" and role="dialog" on the container. It must have an accessible name via aria-labelledby or aria-label. The body behind the modal must prevent scrolling (typically via overflow: hidden on the document body). Nested modals, where a confirmation dialog opens inside a settings modal, require a stack of focus traps where only the topmost trap is active.

The reason these behaviors are hard to test with Playwright specifically is that Playwright's page.keyboard.press dispatches real keyboard events, but verifying which element received focus requires checking document.activeElement via page.evaluate(). Standard Playwright locator assertions like toBeVisible do not tell you whether an element is focused. You need toBeFocused() or manual evaluation of the active element. Many teams skip these assertions entirely, resulting in modals that look correct visually but fail completely for keyboard users.

2. Setting Up Your Test Environment

Focus trap testing requires a few specific configuration choices in your Playwright setup. First, you need a real browser context with keyboard event support. Playwright's Chromium, Firefox, and WebKit engines all handle focus events, but their behavior on Tab key presses differs slightly. Run your focus trap tests across all three engines to catch browser-specific edge cases.

The test page should contain a well-structured modal component. For this guide, we will use a modal with a title, a text description, two form inputs, a cancel button, and a confirm button. That gives us six focusable elements inside the trap, which is enough to exercise the full Tab cycle logic.

Helper Utilities for Focus Testing

Focus assertions come up repeatedly, so extract a small helper module that wraps the common patterns. This keeps individual test files concise and readable.

9. Common Pitfalls That Break Focus Trap Tests

Timing: Focus Moves Before the Animation Completes

Most modal libraries animate the dialog in with a CSS transition (opacity, transform, or both). If you assert focus immediately after triggering the modal open, the element may not yet be focusable because it has visibility: hidden or display: none during the first frame of the animation. Use await expect(modal).toBeVisible() before checking focus. In some frameworks, you may also need await page.waitForTimeout(100) to let the CSS transition settle, though this should be a last resort.

Portal-Rendered Modals Break DOM Queries

React portals, Vue Teleport, and similar patterns render the modal DOM at the end of the document body rather than inside the component tree. This means a query like modal.locator('button') may return zero results if the modal is not the direct DOM parent. Always query from page level using getByRole('dialog') first, then scope subsequent locators to that dialog locator. Never assume the modal is a child of the component that triggered it.

Shadow DOM Swallows Focus Events

Web components that render modals inside shadow DOM create a separate focus scope. document.activeElement will point to the shadow host, not the actual focused element inside the shadow tree. You need to traverse document.activeElement.shadowRoot?.activeElement recursively to find the real focused element. The focus helper utility from Section 2 can be extended to handle this case.

iOS Safari and VoiceOver Focus Behavior

WebKit on iOS handles focus differently from desktop browsers. VoiceOver can move focus outside a focus trap by swiping, because the swipe gesture traverses the accessibility tree rather than dispatching keyboard events. The inertattribute on background content is the only reliable way to prevent this. If your modal implementation uses only JavaScript keydown listeners for trapping, it will break on iOS VoiceOver. Test on real devices or use Playwright's WebKit engine as a first-pass proxy, though it does not fully replicate VoiceOver behavior.

Multiple Modals from Different Libraries

Large applications sometimes use multiple UI libraries (a design system dialog, a third-party date picker modal, a custom confirmation dialog). Each library registers its own focus trap listener. When two traps compete, focus can oscillate between them in an infinite loop or get stuck on a single element. If your test detects a focus assertion failure that only happens intermittently, check whether two focus trap handlers are active simultaneously. Standardize on one focus trap mechanism across your application.

10. Writing These Scenarios in Plain English with Assrt

The six scenarios above add up to over 300 lines of Playwright TypeScript. Each test uses page.evaluate() calls to inspect document.activeElement, manual traversal of focusable element lists, and fragile selectors like [data-testid="cancel-btn"]. When your design team changes the modal layout, renames a button, or swaps the focus trap library, every one of those tests breaks silently. Assrt lets you describe the accessibility requirements in plain English and regenerates the Playwright implementation when the underlying DOM changes.

The nested modal scenario from Section 7 is a good example. In raw Playwright, you need to know the exact accessible name for both dialogs, the data-testid of the cancel button in the inner modal, and the correct Tab count to verify wrapping. In Assrt, you describe the intent: open the confirmation dialog inside the settings modal, verify that Tab cycles only within the confirmation dialog, close it, and verify focus returns to the settings modal.

Assrt compiles each scenario block into the Playwright TypeScript shown in the preceding sections and commits it to your repo as real tests you can read, run, and extend. When your design system updates the modal component (renaming the close button, changing the focus trap library, adding new focusable elements), Assrt detects the assertion failures, analyzes the new DOM structure, and opens a pull request with updated locators. Your scenario files stay untouched.

Start with the Tab cycle containment test. Once it passes in CI, add Shift+Tab wrapping, then Escape close, then focus restore, then nested modals, then scroll lock and ARIA validation. In a single afternoon you can have comprehensive focus trap coverage that catches the accessibility regressions most teams never test for at all.