Background: How Sahi Pro Identifies Elements

1. Object Identification Strategy

Sahi Pro uses a combination of APIs like _setValue(), _click(), and _near() to locate elements. Unlike traditional XPath selectors, Sahi’s heuristics are more tolerant to DOM changes but still prone to ambiguity if the page structure changes dynamically or asynchronously.

2. Role of Accessor Repository

The Accessor Repository (AR) contains mappings between logical names and element locators. Failures often stem from stale or imprecise mappings that do not adapt well to SPA (Single Page Application) transitions or AJAX-loaded content.

Symptoms of Element Identification Failures

• Test passes intermittently for the same script
• _click() or _setValue() fails with Element not found error
• UI appears fully loaded visually but interaction commands fail
• Tests run reliably on developer machines but fail in CI

Root Causes

1. Asynchronous Loading without Waits

Modern UIs load content dynamically using AJAX or SPAs. If Sahi does not wait for the correct DOM state, it attempts to access elements prematurely.

_click(_link("Submit")); // fails if DOM isn't ready

2. Ambiguous Locators

If multiple elements match the same _near() or _in() condition, Sahi may select the wrong one, leading to failures or false positives.

3. Stale Accessor Repository Entries

Manually edited AR files may reference outdated or removed UI elements, especially in fast-moving Agile releases.

4. Environmental Differences in CI

Headless mode, slower network latency, and lower screen resolutions in CI agents can subtly alter DOM timing or visibility, affecting element recognition.

Diagnostic and Debugging Approach

1. Enable Stepwise Logging

Use diagnostics.log and playback.log to trace exact failure points. Set logging level to DEBUG to capture DOM snapshot comparisons.

2. Use _wait() and _exists()

Wrap element interactions with conditional waits to ensure visibility and readiness.

_wait(5000);
if (_exists(_button("Submit"))) {
  _click(_button("Submit"));
} else {
  _log("Submit button not found");
}

3. Visualize DOM Changes

Use Sahi Pro's Controller to inspect real-time DOM and validate if accessors map correctly. Compare CI vs. local DOM state.

4. Update Accessor Repository

Regenerate AR entries using the Controller whenever the UI changes significantly. Avoid copy-pasting selectors from earlier builds.

Step-by-Step Fixes

1. Refactor to Use Unique Accessors

Replace generic accessors like _near("OK") with more specific ones like _button("OK") _in(_div("modal")) for clarity and stability.

2. Use Deliberate Wait Conditions

Replace fixed _wait() calls with _waitUntil() tied to DOM state.

_waitUntil(_isVisible(_div("confirmation")), 10000);

3. Modularize Accessors

Use external AR files per module or screen to isolate failures and simplify maintenance.

4. Enhance CI Robustness

• Use XVFB with screen resolution matching local test environments
• Increase Sahi timeout thresholds for slower CI agents
• Disable animations in test environments using custom CSS overrides

Best Practices

• Dynamic Waits: Avoid hardcoded delays. Use _waitUntil() wherever possible.
• Review AR Regularly: Refresh AR mappings post UI updates or refactorings.
• Test on Multiple Viewports: Screen size affects DOM positioning, especially for modals and dynamic panels.
• Centralize Logging: Integrate logs with centralized dashboards for faster failure triage.
• Version Accessor Repos: Track AR files under version control with test scripts.

Conclusion

Sahi Pro remains a robust tool for enterprise test automation, but its power depends on stable element recognition and disciplined accessor management. By using intelligent waits, modular repositories, and rigorous diagnostics, teams can prevent flaky test runs and build reliable, maintainable automation frameworks across varied environments.

FAQs

1. Why do my Sahi tests fail only in CI?

CI environments often differ in screen resolution, network latency, and DOM readiness, leading to race conditions or visibility issues.

2. How often should I update the Accessor Repository?

Update the AR whenever the UI changes or during every major sprint to maintain accuracy and avoid stale mappings.

3. Is Sahi Pro compatible with SPAs?

Yes, but you must use _waitUntil() and _exists() to synchronize interactions with dynamic content.

4. Can I customize logging in Sahi?

Yes, use _log(), _logException(), and advanced log configurations to trace execution paths and DOM mismatches.

5. How do I debug a flaky _click() failure?

Check if the element exists and is visible, confirm there are no overlays or modals obstructing it, and inspect logs for timing issues.