Implementation:MarketSquare Robotframework browser Close Browser Run On Failure

Property	Value
Implementation Name	Close Browser, Run On Failure
Type	API Doc
Domains	Test_Automation, Resource_Management
Workflow	Browser_Test_Authoring
Repository	MarketSquare/robotframework-browser

Overview

Concrete tools for closing browser resources and configuring automatic failure handling provided by robotframework-browser.

Description

These keywords manage browser resource cleanup and failure recovery:

• Close Browser: Closes the specified browser process along with all its contexts and pages. Accepts a browser parameter that can be CURRENT (default, closes the active browser), ALL (closes every open browser), or a specific browser ID string. When a browser is closed, the previously active browser becomes the new active browser. This keyword communicates with the Playwright Node.js process via gRPC to shut down the browser instance.
• Register Keyword To Run On Failure: Sets or changes the keyword that is automatically executed when any Browser library keyword fails. The registered keyword can be any available Robot Framework keyword, including user keywords and keywords from other libraries. Supports scoped registration:
  • Global: The default scope. The setting persists for the entire test execution unless overridden.
  • Suite: The setting applies for the current suite and is automatically reverted when the suite ends.
  • Test: The setting applies for the current test and is automatically reverted when the test ends.

The keyword returns a DelayedKeyword object representing the previously registered failure keyword. This object can be passed back to Register Keyword To Run On Failure to restore the original behavior.

When Take Screenshot is registered as the failure keyword without arguments, the library uses ${TEST NAME}_FAILURE_SCREENSHOT_{index} as the filename instead of the default filename pattern.

Usage

Use Close Browser in test teardown or when you need to explicitly close browsers during test execution. Use Register Keyword To Run On Failure to customize diagnostic capture on failure, disable it temporarily during expected-failure scenarios, or set different failure handling strategies at different scopes.

Code Reference

Source Location

• Repository: robotframework-browser
• Files:
  • Browser/keywords/playwright_state.py Lines 117-154 (close_browser)
  • Browser/keywords/runonfailure.py Lines 29-78 (register_keyword_to_run_on_failure)

Signature

# Close Browser
def close_browser(
    self,
    browser: SelectionType | str = SelectionType.CURRENT,
) -> None

# Register Keyword To Run On Failure
def register_keyword_to_run_on_failure(
    self,
    keyword: str | None,
    *args: str,
    scope: Scope = Scope.Global,
) -> DelayedKeyword

Import

# These are Robot Framework keywords exposed by the Browser library.
# No direct Python import is needed for typical usage.

# Robot Framework usage (in *** Settings ***):
# Library    Browser

I/O Contract

Close Browser

Parameter	Type	Default	Description
browser	SelectionType or str	CURRENT	Which browser to close. CURRENT closes the active browser. ALL closes all browsers. A string browser ID closes that specific browser.

Returns	Description
None	No return value. The browser process and all its resources are terminated.

Register Keyword To Run On Failure

Parameter	Type	Default	Description
keyword	str or None	(required)	Name of the keyword to execute on failure. Use NONE to disable.
*args	str	(variadic)	Arguments to pass to the failure keyword.
scope	Scope	Global	Scope of the registration: Global, Suite, or Test/Task.

Returns	Description
DelayedKeyword	Object representing the previously registered failure keyword. Contains keyword name and arguments. Can be passed back to restore the previous setting.

Usage Examples

*** Settings ***
Library    Browser    run_on_failure=Take Screenshot  fail-screenshot-{index}

*** Test Cases ***
Close Current Browser After Test
    New Browser    chromium
    New Page       https://example.com
    # ... test steps ...
    [Teardown]    Close Browser

Close All Browsers In Suite Teardown
    New Browser    chromium
    New Page       https://example.com
    New Browser    firefox
    New Page       https://example.com
    [Teardown]    Close Browser    ALL

Close A Specific Browser By ID
    ${browser1}=    New Browser    chromium
    New Page        https://example.com
    ${browser2}=    New Browser    firefox
    New Page        https://example.com
    Close Browser   ${browser1}
    # browser2 is still open and now active

Register Custom Screenshot On Failure
    Register Keyword To Run On Failure    Take Screenshot    fullPage=True

Register Full Page Screenshot At Suite Scope
    Register Keyword To Run On Failure    Take Screenshot    failure-{index}    fullPage=True    scope=Suite

Disable Run On Failure Temporarily
    ${previous}=    Register Keyword To Run On Failure    NONE
    # This section intentionally tests error scenarios
    TRY
        Click    id=nonexistent    # Will fail but no screenshot taken
    EXCEPT
        Log    Expected failure occurred
    END
    # Restore previous failure handler
    Register Keyword To Run On Failure    ${previous}

Register Custom Keyword On Failure
    Register Keyword To Run On Failure    My Custom Failure Handler    arg1    arg2

Scoped Failure Handler Per Test
    [Setup]    Register Keyword To Run On Failure    Take Screenshot    test-specific-{index}    scope=Test
    New Page    https://example.com
    # If any keyword fails here, "Take Screenshot test-specific-{index}" runs
    Get Text    id=heading    ==    Expected Heading
    # The Test-scoped registration is automatically reverted when this test ends

*** Keywords ***
My Custom Failure Handler
    [Arguments]    ${arg1}    ${arg2}
    Take Screenshot    custom-failure-{index}
    Log    Failure occurred with args: ${arg1} ${arg2}

Related Pages

Implements Principle

• Principle:MarketSquare_Robotframework_browser_Test_Cleanup_and_Failure_Handling