Skip to main content

1.3 Browser, Context, Page

1.3.1 Browsers installation​

By default, we install browser binaries shipped with Playwright: Chrome for testing, Firefox, and WebKit. The rfbrowser install or rfbrowser init command installs all three. It is also possible to install only selected browsers; for example, rfbrowser install firefox installs only Firefox. These three browser binaries are installed in the Browser library installation directory and are isolated from browser binaries installed in the system.

It is also possible to install chrome, chrome-beta, msedge, msedge-beta and msedge-dev to your system with rfbrowser install or rfbrowser init. But please note that these are not isolated in the same way as Chrome for testing, Firefox, and WebKit. Instead, installing for example Chrome will replace the Chrome browser on your system. So be careful if you decide to go this route.

It is possible to skip browser binary installation and use your preferred way to manage browser binaries. For example, in a Docker container you may have browser binaries preinstalled, and you may want to install only the Browser library and its Python and NodeJS dependencies.

examples

reuse_existing.robot

1.3.1.1 Using system Chrome or Edge​

Regardless of how you installed Chrome or Edge, you can use these Chromium-based browsers in your tests.

If you have Edge or Chrome installed on your system, write a test that launches Edge or Chrome for testing.

*** Settings ***
Library    Browser

*** Test Cases ***
Test With Chrome
    New Browser    headless=False    channel=chrome
    New Page    http://localhost:7272/prefilled_email_form.html
    Type Text    [name=comment]    This is comment

And run the test with:

robot --outputdir output examples/1/1.3/chrome_channel.robot

1.3.2 Browser, Context, Page​

Browser/Context/Page are the three pillars of Playwright. These pillars define how the browser binaries are controlled and how pages are opened.

1.3.2.1 Browser​

Browser defines which browser engine is used (chromium, firefox, and webkit, or one of the system-installed Chromium-based browsers) and a few other environment-related options, like timeout or the location of an external browser binary. Browser is the highest level in the hierarchy and there can be many browsers open at the same time.

Browsers are by default reused as long as they have the same options.

1.3.2.2 Context​

Context defines how the browser engine is opened; you can think of it as the definition of how the browser profile is created. For example, the context defines whether offline mode is enabled, what geolocation is set, or whether browser headers are modified. It also controls a few debugging options, like trace or video creation.

Each context is opened under a specific browser, and one browser can have multiple contexts open at the same time.

1.3.2.3 Page​

Page is like a tab in the browser; it renders the opened URL. A page is always opened under a specific context. One context can have multiple pages open.

An example browsers/contexts/pages structure could look like this:

Browser 1
    -> Context 1.1
        -> Page 1.1.1
        -> Page 1.1.2
    -> Context 1.2
        -> Page 1.2.1
        -> Page 1.2.2
        -> Page 1.2.3
Browser 2
    -> Context 2.1
        -> Page 2.1.1
        -> Page 2.1.2
Loading examples...

1.3.2.4 Persistent context​

Persistent context is a special type of context. It automatically creates a new browser, and the main difference to a "normal" context is that the user can pass in a user data dir and provide arguments to launch the browser binary. Use custom browser args at your own risk, as some of them may break Playwright functionality.

1.3.3 Mobile​

You can test mobile views easily with Browser library. The Browser library provides the Get Device keyword, which allows you to set the correct form factor and mobile settings for different models.

Your task is to use Get Device keyword in your tests and experiment with different mobile models. See how it affects the underlying page. Different mobiles can be found from Playwright deviceDescriptorsSource.json file. In your test, use a public page that is responsive to mobile form factor.

*** Settings ***
Library    Browser

*** Test Cases ***
Mobile testing
    &{device}=    Get Device    iPhone 15
    New Context    &{device}
    New Page    https://marketsquare.github.io/robotframework-browser/Browser.html
    Take Screenshot    mobile.png

1.3.4 Connect over CDP​

The Connect To Browser keyword allows users to connect to a Playwright browser server via playwright websocket or Chrome DevTools Protocol. The Connect keyword is useful if your browser binaries are hosted in a different container/VM and you need to connect from the container/VM where your tests are running. For example, BrowserStack supports connecting this way.

*** Settings ***
Library    Browser

*** Test Cases ***
Launch Browser Server Generated wsEndpoint
    ${wsEndpoint} =    Launch Browser Server    chromium    headless=${HEADLESS}
    ${browser} =    Connect To Browser    ${wsEndpoint}
    New Page    ${LOGIN_URL}
    Get Title    ==    Login Page
    [Teardown]    Close Browser Server    ${wsEndpoint}

There is also an entry point to create wsEndpoint. Run rfbrowser launch-browser-server --help for instructions on how to use the entry point.

Create a new test to use the wsEndpoint created by the rfbrowser launch-browser-server entry point.

*** Settings ***
Library    Browser

*** Test Cases ***
Connect To wsEndpoint
    VAR    ${wsEndpoint}    ws://localhost:61097/c2a09d1d363fb4ee8d1577c0d3761e32    # This is an example wsEndpoint
    ${browser} =    Connect To Browser    ${wsEndpoint}
    New Page    http://localhost:7272/prefilled_email_form.html
    Get Title    ==    prefilled_email_form.html

Run this from the shell before the test:

rfbrowser launch-browser-server chromium headless=True "timeout=10 sec"

1.3.5 Pabot Speed Run​

When using Pabot, each thread starts and stops Robot Framework instances. That means that, by default, the Browser library is initialized, a NodeJS process is started with Playwright, a browser process is started, and tests are executed. Then all of that is terminated again.

What if we could REUSE the node process of RF Browser and also start only one browser per thread and just connect to it???

See tasks.py for an example implementation.

Steps to execute:

  1. determine the number of physical cores on your machine
  2. start one Browser library instance with the NodeJS process and store the port number
  3. launch one Browser server for each Pabot-thread/physical core and store the websocket endpoints in a variable
  4. start Pabot and hand over the NodeJS port and the websocket endpoints as Robot Framework variables.
  5. use these wsEndpoints in your tests if Pabot is in use and connect to the Browser server

This script has some different modes.

  • --reuse-node When this is set, only one node process is started and its port is reused in all threads. That makes it possible to start the Browser in threads in parallel at the same time.
  • --reuse-browser When this is set, only one browser is started per thread and its wsEndpoint is reused in all threads.
  • --browser_start_mode This can either be serial or parallel and defines if the browsers are started after each other or in parallel. parallel only works with --reuse-node and --reuse-browser set.
  • --headful When this is set, the browser is started in headful mode.
  • --browser This can be chromium, firefox or webkit and defines which browser is used.
  • --processes This defines how many processes are started in parallel. If set to 0 the amount of physical cores is used.

See RF-Browser-Architecture.pptx for more information.

1.3.6 Scope for Browser, Context and Page​

Browser library has a scope (life cycle) for objects. For example, automatic closing of pages is controlled by the library import auto_closing_level import parameter. Possible values are:

  • TEST
  • SUITE
  • MANUAL
  • KEEP

When automatic closing level is TEST, contexts and pages that are created during a single test are automatically closed when the test ends. Contexts and pages that are created during suite setup are closed when the suite teardown ends.

When automatic closing level is SUITE, all contexts and pages that are created during the test suite are closed when the suite teardown ends.

When automatic closing level is MANUAL, nothing is closed automatically while the test execution is ongoing. All browsers, contexts, and pages are automatically closed when test execution ends.

When automatic closing level is KEEP, nothing is closed automatically while the test execution is ongoing. Also, nothing is closed when test execution ends,

1.3.6.1 Scope with other objects​

Several keywords that change library attributes also have a scope or lifetime. For example, Set Browser Timeout changes the timeout, and the set timeout can be valid for a certain duration. Possible values are:

  • Global
  • Suite
  • Test

A Global scope will live forever until it is overwritten by another Global scope, or temporarily overridden locally by a narrower scope. A Suite scope overrides the Global scope locally and lives until the end of the suite where it is set, unless it is overwritten by a later setting with Global or the same scope. A child suite inherits the setting from the parent suite, but it may also have its own local Suite setting that is then inherited by its child suites. A Test or Task scope is inherited from its parent suite but, when set, lives until the end of that particular test or task.

Keywords that change library attributes by a scope are: Register Keyword To Run On Failure, Set Assertion Formatters, Set Browser Timeout, Set Retry Assertions For, Set Selector Prefix, Set Strict Mode and Show Keyword Banner

Write a test that changes a scoped setting between tests and proves that the previous value is restored.

*** Settings ***
Library    Browser    timeout=5s
Suite Setup    New Page   http://localhost:7272/prefilled_email_form.html

*** Test Cases ***
Default Scope
    TRY
        Click     id=nothere
    EXCEPT
        Log To Console    With 5 seconds
    END

Page Scope
    Set Browser Timeout    1s    Test
    TRY
        Click     id=nothere
    EXCEPT
        Log To Console    With one second
    END

Back to default scope
    TRY
        Click     id=nothere
    EXCEPT
        Log To Console    With 5 seconds
    END

1.3.6.2 Automatic open browser and context​

If the default settings for the browser or context are good for this test case, then calling directly New Page automatically opens a browser and context.

These tests are logically the same:

*** Settings ***
Library     Browser


*** Test Cases ***
Automatic Opening Of Browser And Context
    New Page    https://marketsquare.github.io/robotframework-browser

Is Same As
    New Browser
    New Context
    New Page    https://marketsquare.github.io/robotframework-browser

1.3.6.2 Reusing same browser​

If you call New Browser multiple times with the same arguments, it does not, by default, create a new browser object. Instead, the same browser is reused. If you want to create a new browser, set the reuse_existing argument to false.

*** Settings ***
Library    Browser

*** Test Cases ***
Reuse
    New Browser
    New Browser
    ${catalog} =    Get Browser Catalog
    Length Should Be    ${catalog}    1
    New Browser    reuse_existing=False
    ${catalog} =    Get Browser Catalog
    Length Should Be    ${catalog}    2