Heuristic:Getgauge Taiko Element Actionability Checks
| Knowledge Sources | |
|---|---|
| Domains | Browser_Automation, Testing |
| Last Updated | 2026-02-12 03:00 GMT |
Overview
Pre-action validation framework checking element visibility, stability, connectedness, and non-coverage before performing browser actions.
Description
Before Taiko performs any action (click, write, etc.), it runs a series of actionability checks on the target element. These checks verify the element is visible, not disabled, connected to the DOM, positionally stable (not animating), and not covered by another element. If any check fails, Taiko scrolls to the element and retries for up to retryTimeout (10 seconds). The force option bypasses all checks.
Usage
Apply this heuristic when debugging test failures where elements exist in the DOM but actions fail with messages like "is not visible", "is covered by other element", or "is not stable". Understanding these checks helps determine whether to wait longer, scroll, or use `force: true`.
The Insight (Rule of Thumb)
- Action: When an action fails with actionability errors, diagnose using the specific check that failed:
- "is not visible" — element is outside viewport or has `display: none` / `visibility: hidden`
- "is covered by other element" — a modal, overlay, or tooltip is on top
- "is not stable" — CSS animation or reflow is moving the element
- "is disabled" — the form control has `disabled` attribute
- "is not connected to DOM" — element was removed from DOM after being found
- Value: Stability check uses `requestAnimationFrame` and compares bounding rects. It runs for up to 10 seconds before timing out.
- Trade-off: Using `force: true` skips all checks but may cause actions on wrong elements or produce unexpected behavior.
Reasoning
The four default checks (visible, disabled, connected, stable) cover the most common causes of flaky browser tests. The coverage check is not in the default set but is implicitly handled by Taiko's scroll-and-retry mechanism.
The stability check algorithm works by comparing an element's bounding rect across consecutive animation frames:
- Get initial bounding rect via `requestAnimationFrame`
- Get next frame's bounding rect
- Compute `|top_diff| + |left_diff| + |bottom_diff| + |right_diff|`
- If total difference is 0, element is stable
- Otherwise, retry with next frame
- Timeout after 10 seconds
This catches CSS transitions, JavaScript animations, and layout reflows that would cause clicks to miss their target.
Code Evidence
Default actionability checks from `lib/actions/pageActionChecks.js:154-159`:
// Default checks applied to all actions
[visible, disabled, connected, stable]
Stability check from `lib/actions/pageActionChecks.js:78-127`:
// Compares bounding rects across animation frames
// Resolves when position stabilizes (total diff = 0)
// Max 10 second timeout, then rejects with false
Coverage check with Shadow DOM support from `lib/actions/pageActionChecks.js:24-50`:
const checkIfElementIsNotCovered = async (e) => {
function isElementAtPointOrChild() {
// Uses document.elementsFromPoint(x, y)
// Recursively checks shadow DOM roots
// Considers opacity < 0.1 as covered
}
};
Force bypass from `lib/actions/pageActionChecks.js:206-208`:
// force: true skips ALL checks and uses first element