Principle:MarketSquare Robotframework browser Browser Context Lifecycle

Property	Value
Principle Name	Browser Context Lifecycle
Domains	Browser_Automation, Test_Isolation
Workflow	Browser_Test_Authoring
Repository	MarketSquare/robotframework-browser
Type	Principle

Overview

The hierarchical Browser, Context, and Page management model provides structured isolation and resource lifecycle control for browser-based test automation.

Description

The Browser Context Lifecycle principle describes the three-level hierarchy that governs how browser resources are created, managed, and destroyed during test execution. This hierarchy mirrors the real-world structure of a modern web browser:

• Browser: The top-level process, analogous to launching Chrome or Firefox. A browser instance runs a specific engine (chromium, firefox, or webkit) and can host multiple isolated contexts.
• Context: A browser profile or session, analogous to an incognito window. Each context maintains its own cookies, local storage, session storage, permissions, and cache. Contexts within the same browser are fully isolated from each other.
• Page: An individual web page, analogous to a tab within a browser window. Pages belong to a context and share that context's storage and cookies.

The relationship is strictly hierarchical:

Browser
  +-- Context A
  |     +-- Page 1
  |     +-- Page 2
  +-- Context B
        +-- Page 3

Key behaviors:

1. Auto-creation: When a Page is opened without an existing Context or Browser, the library automatically creates the missing parent resources with default settings. Calling New Page when no browser is open will automatically trigger New Browser and New Context first.
2. Isolation: Contexts provide complete session isolation. Tests running in separate contexts cannot interfere with each other's cookies, authentication state, or local storage. This is critical for parallel test execution and for testing multi-user scenarios.
3. Auto-closing: The library can automatically close contexts and pages at configurable lifecycle boundaries:
   • TEST level: Contexts and pages are closed after each test (default).
   • SUITE level: Resources persist across tests within a suite and close when the suite finishes.
   • MANUAL level: Resources are never closed automatically; the test author must close them explicitly.
4. Switching: Active browser, context, and page can be switched using dedicated keywords, enabling tests that interact with multiple browser windows or tabs.

Usage

Use this principle when:

• You need test isolation between test cases that share a suite, ensuring one test's login state does not bleed into the next.
• You want to simulate multiple users interacting with the same application by creating separate contexts.
• You need to test cross-browser compatibility by creating browsers of different types.
• You want fine-grained control over when browser resources are created and destroyed.
• You need to manage multiple tabs or windows within a single test.

Theoretical Basis

HIERARCHY:
    Browser -> Context -> Page
    (process)  (profile)  (tab)

AUTO_CREATION(requested_level):
    IF requested_level == PAGE:
        IF no active Context:
            IF no active Browser:
                CREATE Browser with defaults
            CREATE Context with defaults
        CREATE Page
    ELIF requested_level == CONTEXT:
        IF no active Browser:
            CREATE Browser with defaults
        CREATE Context

AUTO_CLOSING(closing_level, lifecycle_event):
    # closing_level is configured at library import (TEST, SUITE, MANUAL)
    IF lifecycle_event == TEST_END AND closing_level == TEST:
        CLOSE all contexts (and their pages) created during this test
    ELIF lifecycle_event == SUITE_END AND closing_level == SUITE:
        CLOSE all contexts (and their pages) created during this suite
    ELIF closing_level == MANUAL:
        # Do nothing; user must close explicitly

ISOLATION_MODEL:
    Context_A.cookies    IS INDEPENDENT OF    Context_B.cookies
    Context_A.storage    IS INDEPENDENT OF    Context_B.storage
    Context_A.sessions   IS INDEPENDENT OF    Context_B.sessions
    Page_1 IN Context_A  SHARES storage WITH  Page_2 IN Context_A

Related Pages

Implemented By

• Implementation:MarketSquare_Robotframework_browser_New_Browser_New_Context_New_Page