Introduction to SeleniumScreenshots

SeleniumScreenshots library for Robot Framework provides keywords for annotating and cropping screenshots taken with SeleniumLibrary. It is useful for scripting automatically updated screenshots for documentation or visual regression testing purposes.

SeleniumScreenshots is the maintained version of Selenium2Screenshots.

See also: full keyword documentation.

Importing

The library is imported and used with SeleniumLibrary with its name SeleniumScreenshots.

*** Settings ***

Library  SeleniumLibrary
Library  SeleniumScreenshots

*** Variables ***

${BROWSER}  firefox

*** Keywords ***

Open robotframework.org
    Set window size  800  600
    Go to  https://robotframework.org

*** Test Cases ***

Open browser
    Open browser  about:blank  browser=${BROWSER}

Capture and crop page screenshot

Keyword Capture and crop page screenshot takes, at first, a screenshot of the current page using Capture page screenshot keyword from SeleniumLibrary, and then, crops that screenshot down to the combined bounding box of the elements matching the given locators.

For its argument the keyword requires filename of the resulting screenshot file and one ore more locators.

*** Test Cases ***

Capture and crop page screenshot
    Open robotframework.org
    Capture and crop page screenshot
    ...  screenshot.png
    ...  css:H1.main-header
    ...  css:NAV[id='navigation'] > DIV > IMG

Highlight

Keywords Highlight and Clear highlighting are simple wrappers around Update element style keyword to highlight an element by updating its outline style.

*** Test Cases ***

Highlighting an area
    Open robotframework.org
    Highlight
    ...  link:INTRODUCTION  # locator (id, css, name or link)
    Capture and crop page screenshot
    ...  screenshot.png     # filename
    ...  link:INTRODUCTION  # locator

*** Test Cases ***

Clear highlighting
    Clear highlight  link:INTRODUCTION
    Capture and crop page screenshot
    ...  screenshot.png
    ...  link:INTRODUCTION

Update element style

Keyword Update element style updates named style with given value for elements matching the given locator.

*** Test Cases ***

Update style
    Open robotframework.org
    Update element style
    ...  link:INTRODUCTION  # locator (id, css, name or link)
    ...  outline            # style
    ...  dotted yellow 3px  # value
    Capture and crop page screenshot
    ...  screenshot-1.png
    ...  link:INTRODUCTION
    Update element style
    ...  link:INTRODUCTION
    ...  outline
    ...  none
    Capture and crop page screenshot
    ...  screenshot-2.png
    ...  link:INTRODUCTION

Add dot

Keyword Add dot adds a dot at the element matching the given locator. By default it aligns to the center of the element, but alignment can be configured with optional left and top arguments.

*** Test Cases ***

Add dot
    Open robotframework.org
    Add dot
    ...  link:INTRODUCTION
    ...  left=8
    Capture and crop page screenshot
    ...  screenshot.png
    ...  link:INTRODUCTION

More importantly, Add dot keyword accepts optional text-argument, which is intended for annotating sequences.

*** Test Cases ***

Add numbered dots dots
    Open robotframework.org
    Add dot
    ...  link:INTRODUCTION
    ...  text=1
    ...  left=8
    Add dot
    ...  link:EXAMPLES
    ...  text=2
    ...  left=8
    Capture and crop page screenshot
    ...  screenshot.png
    ...  link:INTRODUCTION
    ...  link:EXAMPLES

Remove element

All SeleniumScreenshots keywords that add new elements onto the current page return the id of the created element. That id can be saved into a variable and used e.g. with Update element style-keyword or, as shown below, with Remove element keyword for removing the annotation.

*** Test Cases ***

Add and remove dot
    Open robotframework.org
    ${dot}=  Add dot
    ...  link:INTRODUCTION
    ...  left=8  background=red
    Capture and crop page screenshot
    ...  screenshot-1.png
    ...  link:INTRODUCTION
    Remove element  ${dot}
    Capture and crop page screenshot
    ...  screenshot-2.png
    ...  link:INTRODUCTION

Remove element has plural version Remove elements which accepts multiple locators.

Add note

Keyword Add note adds a yellow sticky onto the current page. Its main configuration arguments beyond the locator are text and position (accepting center, top, right, bottom and left). Multiline notes should define their width.

*** Test Cases ***

Add note
    Open robotframework.org
    ${note} =  Add note 
    ...  css:NAV[id='navigation'] > DIV > IMG
    ...  text=I am a robot. With opinions.
    ...  width=160
    ...  position=right
    Capture and crop page screenshot
    ...  screenshot.png
    ...  css:NAV[id='navigation'] > DIV > IMG
    ...  ${note}

Add pointy note

Keyword Add pointy note is similar to Add note with the difference that its notes come with a pointer triangle targeting the element.

*** Test Cases ***

Add pointy note
    Open robotframework.org
    ${note} =  Add pointy note
    ...  link:INTRODUCTION
    ...  text=Start here.
    ...  position=right
    Capture and crop page screenshot
    ...  screenshot.png
    ...  link:INTRODUCTION
    ...  ${note}

Notes

This introduction has been created as executable Jupyter notebook with robotkernel. Interactive version of this notebook is available for download downloaded from GitHub.

When this notebook is exported into robot file to be run with robot (or runned as such with nbrobot from robotkernel), test browser windows must be explicitly closed, requiring the following setting:

*** Settings ***

Suite Teardown  Close all browsers