Principle:MarketSquare Robotframework browser Library Import and Configuration
| Property | Value |
|---|---|
| Principle Name | Library Import and Configuration |
| Domains | Test_Automation, Configuration |
| Workflow | Browser_Test_Authoring |
| Repository | MarketSquare/robotframework-browser |
| Type | Principle |
Overview
Configuring a Robot Framework test library with global settings at import time establishes default behavior for all keywords throughout test execution.
Description
The Library Import and Configuration principle describes the pattern of initializing a test automation library through constructor arguments that define default runtime behavior. When a Robot Framework library is imported via the Library setting in a suite file, keyword arguments passed at import time are forwarded to the library class constructor. These arguments configure cross-cutting concerns such as:
- Timeout: How long keywords wait for elements or operations to complete before raising an error.
- Strict mode: Whether selectors that match multiple elements should cause an immediate failure instead of acting on the first match.
- Retry policy: How long assertion-based keywords retry polling before reporting failure.
- Failure handlers: What diagnostic action to take automatically when any keyword fails (e.g., capturing a screenshot).
- Auto-closing level: At what test lifecycle boundary (test, suite, or manual) browser resources are automatically cleaned up.
These values become the global defaults for every keyword invocation during the test run. Individual keywords can override specific settings on a per-call basis (for example, passing an explicit timeout argument to a single keyword call), but the library-level defaults apply wherever an override is not provided.
This pattern provides several benefits:
- Consistency: All keywords behave uniformly without requiring repetitive per-call configuration.
- Centralized control: Changing a default (e.g., increasing timeout for a slow environment) requires editing a single import line.
- Layered overrides: Settings can be adjusted at different scopes (global, suite, test) using dedicated "Set" keywords during execution.
The library maintains an internal settings stack for each configurable parameter. The stack starts with the import-time value at its base and allows scoped overrides to be pushed and popped as tests run.
Usage
Use this principle when:
- You need to establish consistent default behavior across an entire test suite or project.
- You want to avoid repeating the same configuration arguments on every keyword call.
- You need environment-specific configuration (e.g., longer timeouts in CI, headless mode in pipelines) that can be set once at import time.
- You want automatic failure diagnostics (such as screenshots) without adding explicit teardown logic to every test.
Theoretical Basis
The library initialization pattern follows a constructor injection model:
LIBRARY_IMPORT(settings):
# At import time, the library constructor receives all configuration
global_defaults = {}
global_defaults["timeout"] = settings.get("timeout", DEFAULT_TIMEOUT)
global_defaults["retry_assertions_for"] = settings.get("retry_assertions_for", DEFAULT_RETRY)
global_defaults["strict"] = settings.get("strict", DEFAULT_STRICT)
global_defaults["run_on_failure"] = settings.get("run_on_failure", DEFAULT_RUN_ON_FAILURE)
global_defaults["auto_closing_level"] = settings.get("auto_closing_level", DEFAULT_AUTO_CLOSE)
# Each setting is stored in a SettingsStack for scoped overrides
FOR EACH setting IN global_defaults:
scope_stack[setting] = SettingsStack(initial_value=global_defaults[setting])
KEYWORD_EXECUTION(keyword, explicit_args):
# When a keyword runs, it checks for an explicit override first
effective_timeout = explicit_args.get("timeout") OR scope_stack["timeout"].current()
effective_strict = scope_stack["strict"].current()
# The keyword operates using the effective settings
EXECUTE keyword WITH effective_timeout, effective_strict, ...
IF keyword FAILS:
run_on_failure_keyword = scope_stack["run_on_failure"].current()
IF run_on_failure_keyword IS NOT NONE:
EXECUTE run_on_failure_keyword
The settings stack supports three scopes:
SettingsStack:
base_value <- set at import time
suite_value <- optionally set per suite
test_value <- optionally set per test
current():
RETURN test_value IF set
ELSE RETURN suite_value IF set
ELSE RETURN base_value