---
title: "Verify a modal opens and returns focus coherently"
description: "Check visible modal context and a separately verified keyboard focus cycle, including focus returning to the original trigger after dismissal."
canonical_url: "https://vostride.com/agent-library/accessibility-flows/modal-focus-return.md"
md_url: "https://vostride.com/agent-library/accessibility-flows/modal-focus-return.md"
content_kind: "recipe"
topic: "accessibility-flows"
---

# Verify a modal opens and returns focus coherently

Check visible modal context and a separately verified keyboard focus cycle, including focus returning to the original trigger after dismissal.

## Risk

A modal can look correct while keyboard focus escapes behind it or disappears after closing. agent-qa screenshots support the visible journey; a separate keyboard and accessibility-tree check must establish focus behavior and semantics.

## Fixtures

- A test settings page has an Edit workspace name trigger that opens one modal with Name, Save, and Cancel controls.
- The prepared keyboard audit records focus targets and can inspect dialog role, accessible name, and background inertness.
- The expected focus contract starts at Name, keeps navigation within the open modal, and returns to the trigger after Cancel.

## Steps

1. Open the settings page and verify the Edit workspace name trigger is visible and unobstructed.
2. Activate it and verify the modal title, Name field, Save, and Cancel are visibly present.
3. Run the prepared keyboard audit and verify initial focus enters Name and repeated keyboard traversal stays within the modal.
4. Choose Cancel through the normal UI and verify the modal closes without changing the workspace name.
5. Use the separate focus audit to verify focus returns to the original trigger, then reopen the modal to confirm the trigger remains operable.

## Expected results

- The visible dialog contains the expected controls and disappears after cancellation.
- Independent keyboard evidence confirms initial focus, contained traversal, and return to the correct trigger.
- Independent semantic evidence identifies the dialog and its accessible name; this limited journey does not establish complete accessibility compliance.

## False-pass traps

- A focus ring visible in one screenshot cannot prove a complete keyboard cycle is contained.
- Clicking the trigger again after closing does not prove focus was automatically restored there.

## Cleanup

- Close the modal and restore any accidental workspace-name fixture edit.

## Use with agent-qa

Adapt this test design to your application's acceptance criteria and configured target using the [recipe execution guide](/agent-library/software-factory/turn-a-recipe-into-an-agent-qa-test.md). External fixture setup and non-UI checks require your own supported hooks or test tooling. Validate the authored test, execute it, and inspect the completed evidence; this recipe is not a recorded test result.

## References

- [agent-qa test](/docs/agent-qa/configuration/test.md)
- [agent-qa first test](/docs/agent-qa/guides/first-test.md)
- [agent-qa web testing](/docs/agent-qa/guides/web-testing.md)

- [Accessibility workflow QA recipes](/agent-library/accessibility-flows.md)
- [Software factory QA library](/agent-library.md)