feat: clickFor + clickMenu — retry-safe click-to-reveal helper

[rickcedwhat-ai]

Problem

Multi-step click interactions flake when intermediate states are slow or transient — clicking a button to open a dropdown, then clicking an item inside it. toPass reruns the whole block blindly, which causes toggle-button problems (clicking again closes the thing you just opened).

Design

clickFor (internal primitive)

await clickFor(trigger, reveals, async (revealed) => {
  await revealed.getByRole('menuitem', { name: 'Delete' }).click();
});

Retry logic:

1. If reveals is not yet visible → click trigger
2. Wait for reveals to become visible (short timeout)
3. If still not visible → retry from top
4. Run callback
5. If callback fails and reveals is no longer visible → retry from top
6. If callback fails and reveals is still visible → throw (genuine error, not a flake)

Key insight: check visibility before clicking so retries don't toggle the trigger closed. A slow dropdown that's already open gets acted on directly without re-clicking.

No state revert on retry — clickFor targets single-action interactions. Multi-step rollback belongs in .cleanup().

clickMenu (public shorthand)

// Locator item
await clickMenu(trigger, page.getByRole('menuitem', { name: 'Delete' }));

// String shorthand
await clickMenu(trigger, 'Delete');

Built on clickFor — trigger click + wait for menu + click item, with the retry logic above.

Relationship to hoverMenu

hoverMenu already has per-step retry (re-hover current step if next doesn't appear) plus the L-shaped mouse path for diagonal-move safety. They solve similar flake problems but the mechanics are different enough to keep them separate. Both could share the "check before acting" principle though.

Open questions

• What should the default retry count and reveal timeout be?
• Should clickFor be exported or stay internal? Current thinking: internal only.
• Are there other natural clickFor wrappers beyond clickMenu? (clickToSelect for custom dropdowns/comboboxes was floated)
• Should hoverMenu be refactored to use the same "check visibility before hovering" pattern on retries?

Related

• Closes or relates to the broader DX theme of eliminating toPass boilerplate for common interaction patterns

[coderabbitai]

🔗 Related PRs

#30 - feat: hoverMenu() helper for flake-resistant nested menu navigation [merged]
#33 - feat: watchFor — proactive polling helper for overlay handling [merged]
#39 - feat: playwright sugar poc with resilient navigation [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Summary

• Implement clickFor as an internal primitive with "check visibility before clicking" retry logic to prevent toggle-button flakes, following option patterns from clickToOpen.ts
• Build clickMenu as a thin public wrapper that handles the common "click trigger → click menu item" flow with string shorthand support
• Export only clickMenu publicly while keeping clickFor internal for future flexibility
• Test both utilities with JavaScript-controlled visibility fixtures following hoverMenu.spec.ts patterns, with specific focus on the toggle-avoidance behavior

Design Choices

Design Choice 1: Default timeout and retry values

Options Considered:

1. Match clickToOpen exactly: maxRetries=3, revealTimeout=2000ms
2. Match hoverMenu: retries=2, stepTimeout=5000ms
3. Middle ground: maxRetries=3, revealTimeout=3000ms

Chosen Option: 3

Rationale: Use maxRetries=3 and revealTimeout=3000ms — aligns with clickToOpen's retry count while using a slightly longer reveal timeout since menu reveal typically involves layout/animation that may be slower than simple show/hide.

Design Choice 2: File organization for clickFor and clickMenu

Options Considered:

1. Single clickFor.ts containing both clickFor and clickMenu
2. Separate clickFor.ts and clickMenu.ts files

Chosen Option: 1

Rationale: Single file — clickMenu is a thin wrapper over clickFor (similar to how detectState wraps attemptAction in the same file), and keeping them together makes the relationship explicit.

Design Choice 3: Export visibility of clickFor

Options Considered:

1. Export both clickFor and clickMenu publicly
2. Export only clickMenu, keep clickFor as a non-exported implementation detail

Chosen Option: 2

Rationale: Follow ticket guidance — export only clickMenu publicly. If users need custom click-to-reveal patterns, this can be revisited. The types (ClickForOptions) should still be exported if useful for advanced usage.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Core Implementation

Implement the clickFor primitive with "check visibility before clicking" retry logic, then build the clickMenu wrapper on top of it.

Task 1: Implement clickFor primitive

Create the core retry-safe click-to-reveal function that checks visibility before each click attempt to avoid toggle problems.

• Create src/clickFor.ts with the clickFor function and supporting types
• Define ClickForOptions type with: maxRetries (default 3), revealTimeout (default 3000ms for per-attempt visibility wait), timeout (default 30000ms wall-clock cap)
• Implement the retry loop with this structure:
  • Check if reveals is already visible via reveals.isVisible()
  • If not visible, click trigger and wait for reveals via waitFor({ state: 'visible', timeout: revealTimeout })
  • If still not visible after wait, retry from top (up to maxRetries)
  • Once visible, execute the callback
  • If callback throws AND reveals is no longer visible → retry (transient flake)
  • If callback throws AND reveals is still visible → rethrow (genuine error)
• Include wall-clock timeout check to prevent infinite retry loops
• Follow error message patterns from clickToOpen.ts (descriptive, include timeout values and locator info)

Task 2: Implement clickMenu wrapper

Build the public shorthand for click-to-menu interactions that simplifies the common "click trigger → click menu item" pattern.

• Add clickMenu function to src/clickFor.ts
• Signature: clickMenu(trigger: Locator, item: Locator | string, options?: ClickMenuOptions)
• Define ClickMenuOptions extending ClickForOptions with optional menuSelector for customizing how the menu container is found (default: look for role="menu" or common dropdown patterns)
• Handle string shorthand: convert item string to page.getByRole('menuitem', { name: item }) when a string is passed
• Internally call clickFor with trigger, menu container as reveals, and a callback that clicks the resolved item locator
• If the item is a string, derive the Page reference from the trigger locator to build the menuitem locator

Task 3: Add exports to index.ts

Expose the new clickMenu function and relevant types through the public API.

• Add export { clickMenu } from './clickFor.js' to src/index.ts
• Export ClickMenuOptions and ClickForOptions types for consumers who need to pass custom options
• Do NOT export the clickFor function itself (keep internal per ticket guidance)

🤖 Prompt for AI agents

Implement the `clickFor` internal primitive and `clickMenu` public wrapper in a
single file, then wire up exports. The goal is a retry-safe click-to-reveal
utility that checks visibility before clicking to avoid toggle-button flakes.

**Create `src/clickFor.ts`:**
- Define `ClickForOptions` type with fields: `maxRetries` (default 3),
`revealTimeout` (default 3000ms), `timeout` (default 30000ms wall-clock cap)
- Implement the `clickFor` function (not exported) with the following retry loop
logic:
  - Check if `reveals` is already visible via `reveals.isVisible()`
- If not visible, click `trigger` then wait via `reveals.waitFor({ state:
'visible', timeout: revealTimeout })`
  - If still not visible after wait, retry from the top (up to `maxRetries`)
  - Once visible, execute the callback
- If callback throws AND `reveals` is no longer visible → retry the full
sequence (transient flake)
- If callback throws AND `reveals` is still visible → rethrow immediately
(genuine error)
- Include a wall-clock timeout check before each retry to prevent infinite loops
- Follow descriptive error message patterns from `clickToOpen.ts` (include
timeout values and locator info)
- Define `ClickMenuOptions` extending `ClickForOptions` with an optional
`menuSelector` field for customizing how the menu container is found (default:
look for `role="menu"` or common dropdown patterns)
- Implement the `clickMenu` function (exported) with signature
`clickMenu(trigger: Locator, item: Locator | string, options?:
ClickMenuOptions)`:
- When `item` is a string, derive the Page reference from the trigger locator
and convert to `page.getByRole('menuitem', { name: item })`
- Internally call `clickFor` with `trigger`, the menu container as `reveals`,
and a callback that clicks the resolved item locator

**Update `src/index.ts`:**
- Add `export { clickMenu } from './clickFor.js'`
- Export `ClickMenuOptions` and `ClickForOptions` types
- Do NOT export the `clickFor` function itself

Phase 2: Testing

Create comprehensive tests following the established patterns from hoverMenu.spec.ts, focusing on the visibility-before-click behavior and retry scenarios.

Task 1: Create test fixtures and setup

Build HTML fixtures that simulate click-to-reveal menus with JavaScript-controlled visibility toggling.

• Create tests/clickFor.spec.ts with test fixtures
• Build HTML fixture with a button trigger and hidden dropdown menu, using JavaScript click handlers (not CSS :hover) to toggle display property — mirrors the pattern from hoverMenu.spec.ts
• Include a __clicked flag pattern for verifying menu item clicks
• Create fixtures for: normal dropdown, slow-appearing dropdown (setTimeout delay), and toggle-button dropdown (clicking again closes it)

Task 2: Test clickFor retry scenarios

Verify the core retry logic works correctly, especially the "check before clicking" behavior that distinguishes this from clickToOpen.

• Test: reveals already visible → no trigger click, callback runs directly
• Test: reveals not visible → trigger clicked, waits for reveal, callback runs
• Test: slow reveal → retries until visible, then runs callback
• Test: callback fails while reveals still visible → throws immediately (no retry)
• Test: callback fails while reveals disappeared → retries the full sequence
• Test: toggle button scenario → second retry doesn't re-close the dropdown because visibility is checked first
• Test: wall-clock timeout exceeded → throws descriptive error
• Test: maxRetries exhausted → throws descriptive error with attempt count

Task 3: Test clickMenu shorthand

Verify the public wrapper correctly handles both Locator and string item formats.

• Test: Locator item variant → clicks trigger, waits for menu, clicks item
• Test: string shorthand variant → converts string to menuitem role locator and clicks
• Test: inherits retry behavior from clickFor (one integration test confirming retry works through the wrapper)
• Test: options passthrough (custom retries/timeouts are respected)

🤖 Prompt for AI agents

Create `tests/clickFor.spec.ts` with comprehensive tests for both `clickFor`
retry logic and the `clickMenu` public wrapper, following the patterns
established in `hoverMenu.spec.ts`.

**Test fixtures and setup:**
- Build an HTML fixture with a button trigger and a hidden dropdown menu
- Use JavaScript click handlers (not CSS `:hover`) to toggle the `display`
property — mirrors `hoverMenu.spec.ts` patterns
- Include a `__clicked` flag pattern for verifying menu item clicks
- Create fixtures for: normal dropdown, slow-appearing dropdown (using
`setTimeout` delay), and toggle-button dropdown (clicking again closes it)

**`clickFor` retry scenario tests:**
- `reveals` already visible → no trigger click, callback runs directly
- `reveals` not visible → trigger clicked, waits for reveal, callback runs
- Slow reveal → retries until visible, then runs callback
- Callback fails while `reveals` still visible → throws immediately (no retry)
- Callback fails while `reveals` disappeared → retries the full sequence
- Toggle button scenario → second retry does not re-close the dropdown because
visibility is checked first
- Wall-clock timeout exceeded → throws a descriptive error
- `maxRetries` exhausted → throws a descriptive error with attempt count

**`clickMenu` shorthand tests:**
- Locator item variant → clicks trigger, waits for menu, clicks item
- String shorthand variant → converts string to `menuitem` role locator and
clicks
- Integration test confirming retry behavior is inherited through the wrapper
- Options passthrough test confirming custom `maxRetries`/`timeout` values are
respected

Research

The codebase is a Playwright utility library with established patterns for retry-safe interactions. Key utilities include clickToOpen.ts (click → wait → retry loop), hoverMenu.ts (multi-step hover with per-step retry and L-shaped mouse paths), and attemptAction.ts (outcome-based action with polling). All modules use flat exports through index.ts, follow consistent option patterns (e.g., maxRetries, timeout, subTimeout), and have corresponding test files in tests/ with HTML fixture patterns for simulating interactive UI elements via JavaScript event listeners.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement the `clickFor` internal primitive and `clickMenu` public wrapper in a
single file, then wire up exports. The goal is a retry-safe click-to-reveal
utility that checks visibility before clicking to avoid toggle-button flakes.

**Create `src/clickFor.ts`:**
- Define `ClickForOptions` type with fields: `maxRetries` (default 3),
`revealTimeout` (default 3000ms), `timeout` (default 30000ms wall-clock cap)
- Implement the `clickFor` function (not exported) with the following retry loop
logic:
  - Check if `reveals` is already visible via `reveals.isVisible()`
- If not visible, click `trigger` then wait via `reveals.waitFor({ state:
'visible', timeout: revealTimeout })`
  - If still not visible after wait, retry from the top (up to `maxRetries`)
  - Once visible, execute the callback
- If callback throws AND `reveals` is no longer visible → retry the full
sequence (transient flake)
- If callback throws AND `reveals` is still visible → rethrow immediately
(genuine error)
- Include a wall-clock timeout check before each retry to prevent infinite loops
- Follow descriptive error message patterns from `clickToOpen.ts` (include
timeout values and locator info)
- Define `ClickMenuOptions` extending `ClickForOptions` with an optional
`menuSelector` field for customizing how the menu container is found (default:
look for `role="menu"` or common dropdown patterns)
- Implement the `clickMenu` function (exported) with signature
`clickMenu(trigger: Locator, item: Locator | string, options?:
ClickMenuOptions)`:
- When `item` is a string, derive the Page reference from the trigger locator
and convert to `page.getByRole('menuitem', { name: item })`
- Internally call `clickFor` with `trigger`, the menu container as `reveals`,
and a callback that clicks the resolved item locator

**Update `src/index.ts`:**
- Add `export { clickMenu } from './clickFor.js'`
- Export `ClickMenuOptions` and `ClickForOptions` types
- Do NOT export the `clickFor` function itself
===============================================================================

Task: 2

Create `tests/clickFor.spec.ts` with comprehensive tests for both `clickFor`
retry logic and the `clickMenu` public wrapper, following the patterns
established in `hoverMenu.spec.ts`.

**Test fixtures and setup:**
- Build an HTML fixture with a button trigger and a hidden dropdown menu
- Use JavaScript click handlers (not CSS `:hover`) to toggle the `display`
property — mirrors `hoverMenu.spec.ts` patterns
- Include a `__clicked` flag pattern for verifying menu item clicks
- Create fixtures for: normal dropdown, slow-appearing dropdown (using
`setTimeout` delay), and toggle-button dropdown (clicking again closes it)

**`clickFor` retry scenario tests:**
- `reveals` already visible → no trigger click, callback runs directly
- `reveals` not visible → trigger clicked, waits for reveal, callback runs
- Slow reveal → retries until visible, then runs callback
- Callback fails while `reveals` still visible → throws immediately (no retry)
- Callback fails while `reveals` disappeared → retries the full sequence
- Toggle button scenario → second retry does not re-close the dropdown because
visibility is checked first
- Wall-clock timeout exceeded → throws a descriptive error
- `maxRetries` exhausted → throws a descriptive error with attempt count

**`clickMenu` shorthand tests:**
- Locator item variant → clicks trigger, waits for menu, clicks item
- String shorthand variant → converts string to `menuitem` role locator and
clicks
- Integration test confirming retry behavior is inherited through the wrapper
- Options passthrough test confirming custom `maxRetries`/`timeout` values are
respected

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!