SeleniumLibrary and Browser Automation Integration: Diagnostics, Failure Modes, and Production Practices

1. Diagnostic sequence: isolate the failing layer

1. Preserve first-failure evidence: original output.xml, log/report, screenshot/trace, exact command, browser/library versions.
2. Confirm versions: Python, Robot, SeleniumLibrary/Selenium or Browser/Playwright, browser binary/driver.
3. Confirm execution identity: source revision, selected test, variables, URL, headless/headed mode, test data.
4. Validate imports and keyword resolution: resource graph and duplicate keyword names.
5. Inspect browser ownership: was a session/context/page actually created by this test and still current?
6. Inspect locator and DOM state: locator matches, visibility, enabledness, overlays, re-rendering.
7. Inspect application readiness: distinguish actionability from business completion.
8. Inspect parallel/CI/container state only if relevant: ports, profiles, downloads, display/sandbox, worker collisions.
9. Apply the least destructive correction and rerun the smallest controlled slice.

2. Failure: browser/driver or Playwright binary missing

SeleniumLibrary symptom: Open Browser fails before the test reaches the first application assertion. Confirm an installed supported browser and inspect Selenium Manager diagnostics. Do not download a random driver executable from an untrusted source or disable security controls.

Browser symptom: New Browser fails because the Playwright browser executable is absent. Verify rfbrowser --version, then use the installation path that matches your environment: BrowserBatteries + rfbrowser install chromium, or Node-managed Browser + rfbrowser init chromium. Version the dependency pair.

3. Failure: wrong Browser initialization route

BrowserBatteries users should use rfbrowser install; rfbrowser init is the Node-managed route. Treat a missing npm during init as a configuration mismatch if you intentionally chose BrowserBatteries—not as a reason to install arbitrary Node versions into the environment.

4. Failure: brittle locator

# Intentionally brittle
Click Element    xpath=/html/body/div[2]/form/div[3]/button

# Prefer a stable application-owned attribute
Click Button    css:[data-testid="submit"]

Absolute DOM-position selectors encode layout rather than intent. Repair the locator in the resource, not in every test. If the AUT lacks stable test attributes, discuss adding them with the application team.

5. Failure: fixed sleeps

# Broken production pattern
Sleep    5s
Click Button    css:[data-testid="submit"]

A sleep changes only wall-clock time; it proves no state. On a fast machine it wastes time, and on a slow machine it can still fail. Replace it with a bounded observation of the needed state. For SeleniumLibrary use the appropriate Wait Until... keyword. For Browser rely on supported actionability/assertion waiting and add a specific Wait For Condition/Wait For Elements State only when the application condition is not otherwise covered.

6. Failure: stale Selenium element reference

# Diagnostic anti-pattern: storing a WebElement across a re-render
${button}=    Get WebElement    css:[data-testid="submit"]
# Application re-renders here
Click Element    ${button}

# Repair: keep the stable locator, let SeleniumLibrary resolve the current element
Click Button    css:[data-testid="submit"]

A WebElement object represents a particular DOM element instance. A framework re-render can detach it, producing a stale reference. A locator string is a query contract and lets the next keyword resolve the current element.

7. Failure: visible but covered element in Selenium

An element can be visible yet not clickable because an overlay intercepts the click. Do not retry the click blindly. Inspect screenshot/DOM, identify the overlay, and wait for the overlay’s specific disappearance or for the actual readiness signal. If the overlay never leaves, that is application behavior to diagnose, not a timeout to enlarge indefinitely.

8. Failure: misunderstanding Browser auto-wait

Playwright actionability can wait for a click target to become actionable. It cannot infer arbitrary business readiness such as “invoice generation finished.” Likewise, Browser Get Text without an assertion operator reads once. If you need retrying assertion semantics, use the assertion form; if you need a separate readiness condition, wait for that condition explicitly.

9. Failure: duplicate keyword names

*** Settings ***
Library    SeleniumLibrary
Library    Browser

*** Test Cases ***
Ambiguous Cleanup
    Close Browser

Both libraries expose a Close Browser-style capability, so importing them together can create ambiguous resolution. Robot should surface the collision rather than guessing. A local repair is explicit qualification (for example SeleniumLibrary.Close Browser versus Browser.Close Browser), but the stronger architecture is separate resources/suites unless a mixed stack is genuinely required.

10. Failure: browser state leaks between tests

Cookies, local storage, pages, and authentication can survive if the suite reuses the wrong session/context. A test that passes only after another test is order-dependent. Repair by restoring per-test isolation or by creating/cleaning a context with explicit ownership. Tags do not isolate browser state; test order is not a fixture.

11. Failure: screenshots/traces leak data

Do not capture production credentials, account dashboards, tokens, or customer data into broadly retained CI artifacts. Browser 20.4.0 itself includes security-focused logging fixes, but that does not make artifacts automatically safe. Use synthetic accounts, redact or avoid sensitive values, and treat traces as protected evidence.

12. Failure: cleanup hides the original browser failure

Teardown should attempt deterministic cleanup, but your diagnosis must preserve the first browser/assertion failure. If cleanup also fails, retain both messages. Do not delete screenshots/traces/output because teardown eventually succeeded, and do not convert the original failure to PASS simply because the browser closed.

13. Intentionally broken example and repair

Change the Browser resource selector from [data-testid="submit"] to [data-testid="submit-missing"] and run only the Browser test with tracing enabled. Predict: setup passes, input actions pass, the click fails after a bounded wait, teardown still closes the browser, and the original trace/log show the missing selector.

Repair only the selector in the resource, rerun the smallest test, and compare the two outputs. Do not add a retry, sleep, or broad error catch. The original failure remains evidence that the locator contract was broken.

14. Performance diagnosis by layer

Knowledge check

15. Summary and bridge

Browser failures become tractable when you preserve evidence and classify the owner: Robot import/resolution, library runtime, browser binary/driver, locator/DOM, readiness, shared state, or cleanup. Lesson 5 combines both stacks in one governed checkpoint without mixing their lifecycle.

References and version anchors

• Robot Framework 7.4.2 User Guide — suite/resource/library lifecycle, variable/result behavior, and external-library boundary.
• SeleniumLibrary documentation and SeleniumLibrary 6.9.0 on PyPI — Selenium 4 integration, WebDriver lifecycle, waits, screenshots, and current compatibility.
• Robot Framework Browser documentation, installation, waiting concepts, and logging/tracing — Browser 20.4.0 / Playwright integration.
• Browser 20.4.0 on PyPI — Python and package release anchor.
• DevOps Academy Selenium course — prerequisite browser-testing principles; this chapter focuses on the Robot Framework integration layer.