🙌 OpenHands: AI-Driven Development
fix(settings): make switches keyboard accessible (#18370)
Engel Nyst8b9823a89ce5
diff --git a/.agents/skills/verify-openhands/references/feature-map/F16-application-settings.md b/.agents/skills/verify-openhands/references/feature-map/F16-application-settings.mdindex 13fdf50eb8..64916e382c 100644--- a/.agents/skills/verify-openhands/references/feature-map/F16-application-settings.md+++ b/.agents/skills/verify-openhands/references/feature-map/F16-application-settings.md@@ -47,7 +47,7 @@ Preconditions:- Baseline state (launched, doctored, `onboard --skip` done; it stores analytics off, so the analytics switch starts unchecked).- `F16.title-model`, `F16.title-model-fallback` and the agent half of `F16.git-identity` need LLM profiles: `control-openhands llm preset deepseek --api-key-file <key file>` (or `--api-key-env DEEPSEEK_API_KEY`), which saves `deepseek-flash` (active) and `deepseek-pro`.- Read the starting values once: `control-openhands api GET /api/settings`; backend-saved fields are under `body.misc_settings.app_preferences` (`language`, `user_consents_to_analytics`, `enable_sound_notifications`, `title_llm_profile`, `git_user_name`, `git_user_email`). Keys absent there mean defaults.-- The three switches are `<input hidden>` inside a `<label>`: click the label text scoped to the form, and read state with `control-openhands browser eval "document.querySelector('[data-testid=enable-analytics-switch]').checked"` (same for `enable-sound-notifications-switch`, `show-getting-started-checklist-switch`).+- The three switches are visually hidden native checkboxes inside a `<label>`: click the label text scoped to the form or focus them with Tab and toggle with Space, and read state with `control-openhands browser eval "document.querySelector('[data-testid=enable-analytics-switch]').checked"` (same for `enable-sound-notifications-switch`, `show-getting-started-checklist-switch`).- Every bullet starts on `/settings/app` at the desktop viewport unless it says otherwise (`control-openhands browser goto /settings/app`, then `control-openhands browser wait 'testid=submit-button'`).- `F16.analytics-cloud` is **blocked** without an OpenHands Cloud backend and account.@@ -68,7 +68,33 @@ Preconditions:- **Git identity (`F16.git-identity`).** Run `control-openhands browser fill 'testid=git-user-name-input' 'QA Tester'`, `control-openhands browser fill 'testid=git-user-email-input' '[email protected]'`, `control-openhands browser click 'testid=submit-button'`, `control-openhands browser wait-text 'Settings saved'`, `control-openhands browser reload`, then `control-openhands browser value 'testid=git-user-name-input'` (`QA Tester`) and `control-openhands api GET /api/settings` (`git_user_name`, `git_user_email` set). Agent half: `control-openhands conversation start --prompt "Run exactly this command and reply with only its output: env | grep -c '^GIT_'; git init -q qa_t && cd qa_t && git commit --allow-empty -qm x; git log -1 --format='%an <%ae>'" --wait --timeout 240`, then `control-openhands conversation events <id> --kinds ObservationEvent,MessageEvent` with the `id` from the start output. Expected: `QA Tester <[email protected]>`. **Known failure:** the observation is `0 Author identity unknown ...`: the identity is stored only in `misc_settings.app_preferences` and never reaches the agent.- **Git validation and defaults (`F16.git-identity-validation`).** Run `control-openhands browser fill 'testid=git-user-email-input' 'not-an-email'`, `control-openhands browser click 'testid=submit-button'`, then `control-openhands browser eval "document.querySelector('[data-testid=git-user-email-input]').validationMessage"` (`Please include an '@' in the email address. ...`); the API email is unchanged. Then `control-openhands browser fill 'testid=git-user-email-input' ''`, `control-openhands browser fill 'testid=git-user-name-input' ''`, click submit, `control-openhands browser wait-text 'Settings saved'`, `control-openhands browser reload`: the inputs read `openhands` and `[email protected]`, which also restores the baseline.- **Save button states (`F16.save-states`).** Click the analytics label once: `control-openhands browser enabled 'testid=submit-button'` is `true`; click it again: `false` (back to the stored value). Each successful save above made while the UI is in English shows the toast found by `control-openhands browser wait-text 'Settings saved'`; the Arabic save and the English restore in `F16.language` are made from a French and an Arabic UI and toast `Paramètres enregistrés` and `تم حفظ الإعدادات` instead (see Gotchas). Pending and failure: run `control-openhands service stop agent-server` (the open page keeps its form), click `testid=app-settings-screen >> text=Sound Notifications`, start a sampler with `control-openhands browser eval "(() => { window.__seen = []; window.__iv = setInterval(() => { const s = document.querySelector('[data-testid=submit-button]'); const k = (s ? s.textContent : '-') + ' skeleton=' + !!document.querySelector('[data-testid=app-settings-skeleton]'); if (window.__seen.at(-1) !== k) window.__seen.push(k); }, 10); return 'started'; })()"`, click `testid=submit-button`, `control-openhands browser wait-text 'An error occurred'` (after three `PATCH /api/settings` attempts answer `502`, `browser network --filter /api/settings` shows them; the ingress's plain-text 502 body carries no server message, so the toast is the generic one, #18051), then `control-openhands browser eval "(() => { clearInterval(window.__iv); return window.__seen.join(' -> '); })()"`: it starts with `Save Changes skeleton=false -> - skeleton=true`, i.e. the form and its Save button are replaced by the skeleton while pending; `Saving...` never appears. By the time the failure toast is read the form has usually come back, adding `-> Save Changes skeleton=false`; assert the prefix. Expected after the failure: the Sound switch stays on so the user can retry. **Known failure:** `control-openhands browser eval "document.querySelector('[data-testid=enable-sound-notifications-switch]').checked"` is `false` and Save is disabled: the edit is silently discarded. Bring the backend back with `control-openhands restart`, `control-openhands doctor`, `control-openhands browser goto /settings/app`.-- **Keyboard and screen readers (`F16.keyboard`).** Run `control-openhands browser focus 'testid=color-theme-input'`, then repeat `control-openhands browser press Tab` and `control-openhands browser eval "(document.activeElement.getAttribute('data-testid')||'') + ' ' + document.activeElement.tagName"`. Expected (the acceptance criterion): focus visits the three switches before `title-llm-profile-input`. **Known failure, today's result:** the first Tab lands on `title-llm-profile-input`; `control-openhands browser snapshot 'testid=app-settings-screen' --feature F16.keyboard --name aria` shows the switches only as `text: Send anonymous usage data Sound Notifications Show Getting Started checklist`, with no switch or checkbox nodes.+- **Keyboard and screen readers (`F16.keyboard`).** Run `control-openhands browser focus 'testid=color-theme-input'`, then repeat `control-openhands browser press Tab` and `control-openhands browser eval "(document.activeElement.getAttribute('data-testid')||'') + ' ' + document.activeElement.tagName"`. Expected (the acceptance criterion): focus visits the three switches before `title-llm-profile-input`. The first Tab lands on `enable-analytics-switch`, followed by `enable-sound-notifications-switch` and `show-getting-started-checklist-switch`; Space toggles the focused checkbox. `control-openhands browser snapshot 'testid=app-settings-screen' --feature F16.keyboard --name aria` exposes each checkbox label and checked state. The label draws a visible focus outline.++ ```sh+ control-openhands browser viewport desktop+ control-openhands browser goto /settings/app+ control-openhands browser wait 'testid=submit-button'+ control-openhands browser record start --feature F16.keyboard --name keyboard-desktop+ control-openhands browser focus 'testid=color-theme-input'+ control-openhands browser press Tab+ control-openhands browser press Escape+ control-openhands browser screenshot --feature F16.keyboard --name keyboard-desktop+ control-openhands browser record stop --gif+ control-openhands assert --field value --equals enable-analytics-switch -- browser eval "document.activeElement.getAttribute('data-testid')"+ ```++ ```sh+ control-openhands browser viewport phone+ control-openhands browser goto /settings/app+ control-openhands browser wait 'testid=submit-button'+ control-openhands browser record start --feature F16.keyboard --name keyboard-phone+ control-openhands browser focus 'testid=color-theme-input'+ control-openhands browser press Tab+ control-openhands browser press Escape+ control-openhands browser screenshot --feature F16.keyboard --name keyboard-phone+ control-openhands browser record stop --gif+ control-openhands assert --field value --equals enable-analytics-switch -- browser eval "document.activeElement.getAttribute('data-testid')"+ ```- **Phone layout (`F16.phone`).** Run `control-openhands browser viewport phone`, `control-openhands browser goto /settings/app`, `control-openhands browser bbox 'testid=app-settings-screen'` (`pageHorizontalOverflow: false`, width 348 at x 16), `control-openhands browser screenshot --feature F16.phone --name top`, `control-openhands browser scroll 'testid=submit-button'`, `control-openhands browser bbox 'testid=submit-button'` (`insideViewport: true`) and `control-openhands browser screenshot --feature F16.phone --name bottom`. Return with `control-openhands browser viewport desktop`.- **Clear the title model (`F16.title-model-clear`).** Run `control-openhands browser click 'testid=title-llm-profile-input'`, `control-openhands browser click 'role=option >> has-text=deepseek-flash'` (Save enables), `control-openhands browser hover 'testid=title-llm-profile-input'`, then `control-openhands browser click 'testid=title-llm-profile-input >> xpath=../..//button[not(@aria-label)]'`. `control-openhands browser value 'testid=title-llm-profile-input'` reads `Automatic (recommended)` and `control-openhands browser enabled 'testid=submit-button'` is `false`. Without the hover the click times out (`<div ...> intercepts pointer events`).- **Filter a dropdown by typing (`F16.dropdown-filter`).** Run `control-openhands browser fill 'testid=language-input' Deu` and `control-openhands browser snapshot 'role=listbox'`: the only option is `Deutsch`. Save is briefly `true` while the text is typed; `control-openhands browser press Escape` restores `control-openhands browser value 'testid=language-input'` to `English` and `control-openhands browser enabled 'testid=submit-button'` to `false`.@@ -82,7 +108,7 @@ Preconditions:- The success toast uses the language that was active when you clicked Save, not the one you saved. In `F16.language` the French Save toasts `Settings saved`, the Arabic Save toasts `Paramètres enregistrés`, and the English restore toasts `تم حفظ الإعدادات`, so `wait-text 'Settings saved'` times out on the last two. Assert with `browser text 'testid=submit-button'` after a reload, or read the toast with `browser toasts`.- Some chrome strings stay English after a language switch: the sidebar **Automate** label in every language (the automation interface supplies it, not the translation file), and most of the command menu's own texts (placeholder `Search actions, pages, and settings...`, the search box's `Search commands` name, the group names and the item names) in French and 11 other languages. Only the Model Router and Agent Context items are translated (`Routeur de modèles` and `Contexte de l'agent` in French), because they reuse the settings navigation's titles. Do not treat the English ones as a language switch failure; the sidebar trigger's `Search commands` is translated.- In Arabic (`dir="rtl"`) a switch that is on draws its thumb outside its track (on `show-getting-started-checklist-switch` the track spans `x` 778–818 and the thumb 822–838). Assert switch state with `.checked`, not from a screenshot.-- The switches are hidden checkboxes: `browser click 'testid=enable-analytics-switch'` times out (`element is not visible`). Click the label text scoped to `testid=app-settings-screen`, and read `.checked` through `eval`.+- The switches are visually hidden native checkboxes: Use the label as the pointer target. Click the label text scoped to `testid=app-settings-screen`, or use Tab/Space, and read `.checked` through `eval`.- `role=option[name^=...]` is not supported by the selector parser; use `role=option >> has-text=<profile>` for profile options whose names include the model.- `conversation start` leaves the browser on the conversation page, which also has a `testid=submit-button`; `goto /settings/app` before the next settings step or clicks hit the composer.- Which profile actually generated a title is not visible in the UI, the conversation API or the stack logs; `F16.title-model` proves the preference is stored and a title appears, not which model wrote it.@@ -92,6 +118,6 @@ Preconditions:- The Title generation model combobox has a clear (×) button with no accessible name (`- button` in the snapshot, visible as × at phone width). At desktop width it only takes clicks after `browser hover` on the input (`F16.title-model-clear`); otherwise use the Automatic option.- `browser eval` wraps its argument as an expression: statements separated by `;` fail with `SyntaxError: Unexpected token ';'`; wrap them in `(() => { ...; return x; })()`.- With `service stop agent-server`, a `browser reload` of `/settings/app` shows the backend-unavailable screen (`agent-server-onboarding-screen`, Manage backends), not the form: stop the service only after the page is loaded, and `restart` afterwards.-- Known product bugs (repro candidates): git identity never reaches the agent (#17899); switches are not keyboard reachable or announced (#17900); a failed save discards the user's edits (`F16.save-states`) (#17927).+- Known product bugs (repro candidates): git identity never reaches the agent (#17899); a failed save discards the user's edits (`F16.save-states`) (#17927).- The harness builds with `VITE_DO_NOT_TRACK=1`, so PostHog never starts: `browser network --filter 'posthog|z\.openhands\.dev'` reports `total` `0`, also after analytics consent is granted (#18086). A browser-only Do Not Track setting is outside this recipe. Consent reversal requires the explicit non-DNT build and loopback-only analytics configuration described above, served with `launch --build never` (`F16.analytics`).- The title model's clear button has no test id: the recipe's xpath relies on DOM nesting to skip the unnamed `Show suggestions` button. If both ever match, Playwright's strict mode fails the click instead of pressing the wrong one; report it as harness drift.diff --git a/__tests__/components/settings/settings-switch.test.tsx b/__tests__/components/settings/settings-switch.test.tsxindex 054bbc9328..5d9337b151 100644--- a/__tests__/components/settings/settings-switch.test.tsx+++ b/__tests__/components/settings/settings-switch.test.tsx@@ -4,6 +4,53 @@ import { describe, expect, it, vi } from "vitest";import { SettingsSwitch } from "#/components/features/settings/settings-switch";describe("SettingsSwitch", () => {+ // @spec SSW-001 — Expose checked state and native keyboard interaction.+ it("exposes its label and checked state and toggles with the keyboard", async () => {+ const user = userEvent.setup();+ const onToggle = vi.fn();+ render(+ <SettingsSwitch onToggle={onToggle}>Sound Notifications</SettingsSwitch>,+ );+ const checkbox = screen.getByRole("checkbox", {+ name: "Sound Notifications",+ });++ await user.tab();+ expect(checkbox).toHaveFocus();+ await user.keyboard(" ");++ expect(checkbox).toBeChecked();+ expect(onToggle).toHaveBeenLastCalledWith(true);+ await user.keyboard(" ");+ expect(checkbox).not.toBeChecked();+ expect(onToggle).toHaveBeenLastCalledWith(false);+ });++ // @spec SSW-001 — Disabled controls skip Tab and retain controlled state.+ it("skips a disabled switch and keeps its controlled state", async () => {+ const user = userEvent.setup();+ const onToggle = vi.fn();+ render(+ <>+ <SettingsSwitch isDisabled isToggled onToggle={onToggle}>+ Disabled Switch+ </SettingsSwitch>+ <SettingsSwitch togglePosition="right">Enabled Switch</SettingsSwitch>+ </>,+ );++ await user.tab();+ expect(+ screen.getByRole("checkbox", { name: "Enabled Switch" }),+ ).toHaveFocus();+ await user.click(screen.getByText("Disabled Switch"));++ expect(+ screen.getByRole("checkbox", { name: "Disabled Switch" }),+ ).toBeChecked();+ expect(onToggle).not.toHaveBeenCalled();+ });+it("should call the onChange handler when the input is clicked", async () => {const user = userEvent.setup();const onToggleMock = vi.fn();diff --git a/specs/settings-switches.md b/specs/settings-switches.mdnew file mode 100644index 0000000000..67965ccf66--- /dev/null+++ b/specs/settings-switches.md@@ -0,0 +1,10 @@+# Settings switch contracts++### SSW-001: Settings switches expose native checkbox interaction++- [x] Enabled settings switches participate in Tab order and expose their+ label and checked state through the native checkbox accessibility role.+- [x] Space and label clicks toggle the same value. Keyboard focus is visible+ on the displayed control and label.+- [x] Disabled switches remain disabled, are skipped by Tab, and preserve their+ controlled checked state. Toggle position does not change these behaviors.diff --git a/src/components/features/settings/settings-switch.tsx b/src/components/features/settings/settings-switch.tsxindex 93e63696ac..b264eebd16 100644--- a/src/components/features/settings/settings-switch.tsx+++ b/src/components/features/settings/settings-switch.tsx@@ -36,9 +36,10 @@ export function SettingsSwitch({onToggle?.(value);};+ // @spec SSW-001 — Native checkbox access with visible keyboard focus.const input = (<input- hidden+ className="sr-only"data-testid={testId}name={name}type="checkbox"@@ -67,7 +68,7 @@ export function SettingsSwitch({return (<labelclassName={cn(- "flex items-center gap-2",+ "flex items-center gap-2 rounded-sm has-focus-visible:outline-2 has-focus-visible:outline-offset-2 has-focus-visible:outline-focus",togglePosition === "right" ? "w-full justify-between" : "w-fit",isDisabled ? "cursor-not-allowed opacity-50" : "cursor-pointer",)}