Searchable Dropdown

When to invoke

The page has a role="combobox" widget — typically used when the option list is long (countries, cities, products). The agent provides the desired option in vars.option_text.

Recipe

1. click selector="[role='combobox'], [aria-haspopup='listbox']"
2. wait_for_selector selector="[role='listbox']" state=visible timeout=2s
3. fill selector="[role='combobox'], [role='listbox'] input[type='text']" value="$vars.option_text"
4. wait_for_selector selector="[role='option']:not([aria-disabled='true'])" state=visible timeout=2s
5. click selector="[role='option']:not([aria-disabled='true'])"
6. wait extra=200ms

Success criteria

• assert combobox_has_value value="$vars.option_text"

When NOT to use

• Plain <select> elements — use select_option primitive directly.
• Multi-select comboboxes — v0.1 picks the first match only.
• Async-loaded options where the listbox doesn't render until the filter API responds. Lengthen the wait_for_selector timeout via vars.option_load_timeout.

Known failures

• Comboboxes without standard ARIA: Material-UI v4, antd v3, etc. use custom roles. The matcher's marker set covers the common libraries, but old/custom widgets need a fixture.
• Comboboxes where the input is separate from the listbox: v0.1 fills the visible input; some libraries hide it behind another click. Add an upfront click to expand.
• Comboboxes that auto-select on first matching keystroke: the recipe's explicit-click step is unnecessary but harmless.

Related skills

• date-picker-widget — often co-occurs in booking flows
• fill-multi-step-form — drops down inside form steps