Skip to content

🙌 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.md
index 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.tsx
index 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.md
new file mode 100644
index 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.tsx
index 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 (
<label
className={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",
)}