Skip to content

Screenshot

Screenshot

Library for taking screenshots on the machine where tests are executed.

Taking the actual screenshot requires a suitable tool or module that may need to be installed separately. Taking screenshots also requires tests to be run with a physical or virtual display.

== Table of contents ==

%TOC%

= Supported screenshot taking tools and modules =

How screenshots are taken depends on the operating system. On OSX screenshots are taken using the built-in screencapture utility. On other operating systems you need to have one of the following tools or Python modules installed. You can specify the tool/module to use when importing the library. If no tool or module is specified, the first one found will be used.

= Where screenshots are saved =

By default screenshots are saved into the same directory where the Robot Framework log file is written. If no log is created, screenshots are saved into the directory where the XML output file is written.

It is possible to specify a custom location for screenshots using screenshot_directory argument when importing the library and using Set Screenshot Directory keyword during execution. It is also possible to save screenshots using an absolute path.

= ScreenCapLibrary =

[mihaiparvu/ScreenCapLibrary|ScreenCapLibrary] is an external Robot Framework library that can be used as an alternative, which additionally provides support for multiple formats, adjusting the quality, using GIFs and video capturing.

Source code in src/robot/libraries/Screenshot.py 
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
class Screenshot:
    """Library for taking screenshots on the machine where tests are executed.

    Taking the actual screenshot requires a suitable tool or module that may
    need to be installed separately. Taking screenshots also requires tests
    to be run with a physical or virtual display.

    == Table of contents ==

    %TOC%

    = Supported screenshot taking tools and modules =

    How screenshots are taken depends on the operating system. On OSX
    screenshots are taken using the built-in ``screencapture`` utility. On
    other operating systems you need to have one of the following tools or
    Python modules installed. You can specify the tool/module to use when
    `importing` the library. If no tool or module is specified, the first
    one found will be used.

    - wxPython :: http://wxpython.org :: Generic Python GUI toolkit.
    - PyGTK :: http://pygtk.org :: This module is available by default on most
      Linux distributions.
    - Pillow :: http://python-pillow.github.io ::
      Only works on Windows. Also the original PIL package is supported.
    - Scrot :: http://en.wikipedia.org/wiki/Scrot :: Not used on Windows.
      Install with ``apt-get install scrot`` or similar.

    = Where screenshots are saved =

    By default screenshots are saved into the same directory where the Robot
    Framework log file is written. If no log is created, screenshots are saved
    into the directory where the XML output file is written.

    It is possible to specify a custom location for screenshots using
    ``screenshot_directory`` argument when `importing` the library and
    using `Set Screenshot Directory` keyword during execution. It is also
    possible to save screenshots using an absolute path.

    = ScreenCapLibrary =

    [https://github.com/mihaiparvu/ScreenCapLibrary|ScreenCapLibrary] is an
    external Robot Framework library that can be used as an alternative,
    which additionally provides support for multiple formats, adjusting the
    quality, using GIFs and video capturing.
    """

    ROBOT_LIBRARY_SCOPE = 'TEST SUITE'
    ROBOT_LIBRARY_VERSION = get_version()

    def __init__(self, screenshot_directory=None, screenshot_module=None):
        """Configure where screenshots are saved.

        If ``screenshot_directory`` is not given, screenshots are saved into
        same directory as the log file. The directory can also be set using
        `Set Screenshot Directory` keyword.

        ``screenshot_module`` specifies the module or tool to use when using
        this library outside OSX. Possible values are ``wxPython``,
        ``PyGTK``, ``PIL`` and ``scrot``, case-insensitively. If no value is
        given, the first module/tool found is used in that order.

        Examples:
        | =Setting= |  =Value=   |  =Value=   |
        | Library   | Screenshot |            |
        | Library   | Screenshot | ${TEMPDIR} |
        | Library   | Screenshot | screenshot_module=PyGTK |
        """
        self._given_screenshot_dir = self._norm_path(screenshot_directory)
        self._screenshot_taker = ScreenshotTaker(screenshot_module)

    def _norm_path(self, path):
        if not path:
            return path
        elif isinstance(path, os.PathLike):
            path = str(path)
        else:
            path = path.replace('/', os.sep)
        return os.path.normpath(path)

    @property
    def _screenshot_dir(self):
        return self._given_screenshot_dir or self._log_dir

    @property
    def _log_dir(self):
        variables = BuiltIn().get_variables()
        outdir = variables['${OUTPUTDIR}']
        log = variables['${LOGFILE}']
        log = os.path.dirname(log) if log != 'NONE' else '.'
        return self._norm_path(os.path.join(outdir, log))

    def set_screenshot_directory(self, path):
        """Sets the directory where screenshots are saved.

        It is possible to use ``/`` as a path separator in all operating
        systems. Path to the old directory is returned.

        The directory can also be set in `importing`.
        """
        path = self._norm_path(path)
        if not os.path.isdir(path):
            raise RuntimeError("Directory '%s' does not exist." % path)
        old = self._screenshot_dir
        self._given_screenshot_dir = path
        return old

    def take_screenshot(self, name="screenshot", width="800px"):
        """Takes a screenshot in JPEG format and embeds it into the log file.

        Name of the file where the screenshot is stored is derived from the
        given ``name``. If the ``name`` ends with extension ``.jpg`` or
        ``.jpeg``, the screenshot will be stored with that exact name.
        Otherwise a unique name is created by adding an underscore, a running
        index and an extension to the ``name``.

        The name will be interpreted to be relative to the directory where
        the log file is written. It is also possible to use absolute paths.
        Using ``/`` as a path separator works in all operating systems.

        ``width`` specifies the size of the screenshot in the log file.

        Examples: (LOGDIR is determined automatically by the library)
        | Take Screenshot |                  |     | # LOGDIR/screenshot_1.jpg (index automatically incremented) |
        | Take Screenshot | mypic            |     | # LOGDIR/mypic_1.jpg (index automatically incremented) |
        | Take Screenshot | ${TEMPDIR}/mypic |     | # /tmp/mypic_1.jpg (index automatically incremented) |
        | Take Screenshot | pic.jpg          |     | # LOGDIR/pic.jpg (always uses this file) |
        | Take Screenshot | images/login.jpg | 80% | # Specify both name and width. |
        | Take Screenshot | width=550px      |     | # Specify only width. |

        The path where the screenshot is saved is returned.
        """
        path = self._save_screenshot(name)
        self._embed_screenshot(path, width)
        return path

    def take_screenshot_without_embedding(self, name="screenshot"):
        """Takes a screenshot and links it from the log file.

        This keyword is otherwise identical to `Take Screenshot` but the saved
        screenshot is not embedded into the log file. The screenshot is linked
        so it is nevertheless easily available.
        """
        path = self._save_screenshot(name)
        self._link_screenshot(path)
        return path

    def _save_screenshot(self, name):
        name = str(name) if isinstance(name, os.PathLike) else name.replace('/', os.sep)
        path = self._get_screenshot_path(name)
        return self._screenshot_to_file(path)

    def _screenshot_to_file(self, path):
        path = self._validate_screenshot_path(path)
        logger.debug('Using %s module/tool for taking screenshot.'
                     % self._screenshot_taker.module)
        try:
            self._screenshot_taker(path)
        except:
            logger.warn('Taking screenshot failed: %s\n'
                        'Make sure tests are run with a physical or virtual '
                        'display.' % get_error_message())
        return path

    def _validate_screenshot_path(self, path):
        path = abspath(self._norm_path(path))
        if not os.path.exists(os.path.dirname(path)):
            raise RuntimeError("Directory '%s' where to save the screenshot "
                               "does not exist" % os.path.dirname(path))
        return path

    def _get_screenshot_path(self, basename):
        if basename.lower().endswith(('.jpg', '.jpeg')):
            return os.path.join(self._screenshot_dir, basename)
        index = 0
        while True:
            index += 1
            path = os.path.join(self._screenshot_dir, "%s_%d.jpg" % (basename, index))
            if not os.path.exists(path):
                return path

    def _embed_screenshot(self, path, width):
        link = get_link_path(path, self._log_dir)
        logger.info('<a href="%s"><img src="%s" width="%s"></a>'
                    % (link, link, width), html=True)

    def _link_screenshot(self, path):
        link = get_link_path(path, self._log_dir)
        logger.info("Screenshot saved to '<a href=\"%s\">%s</a>'."
                    % (link, path), html=True)

__init__(screenshot_directory=None, screenshot_module=None)

Configure where screenshots are saved.

If screenshot_directory is not given, screenshots are saved into same directory as the log file. The directory can also be set using Set Screenshot Directory keyword.

screenshot_module specifies the module or tool to use when using this library outside OSX. Possible values are wxPython, PyGTK, PIL and scrot, case-insensitively. If no value is given, the first module/tool found is used in that order.

Examples: | =Setting= | =Value= | =Value= | | Library | Screenshot | | | Library | Screenshot | ${TEMPDIR} | | Library | Screenshot | screenshot_module=PyGTK |

Source code in src/robot/libraries/Screenshot.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
def __init__(self, screenshot_directory=None, screenshot_module=None):
    """Configure where screenshots are saved.

    If ``screenshot_directory`` is not given, screenshots are saved into
    same directory as the log file. The directory can also be set using
    `Set Screenshot Directory` keyword.

    ``screenshot_module`` specifies the module or tool to use when using
    this library outside OSX. Possible values are ``wxPython``,
    ``PyGTK``, ``PIL`` and ``scrot``, case-insensitively. If no value is
    given, the first module/tool found is used in that order.

    Examples:
    | =Setting= |  =Value=   |  =Value=   |
    | Library   | Screenshot |            |
    | Library   | Screenshot | ${TEMPDIR} |
    | Library   | Screenshot | screenshot_module=PyGTK |
    """
    self._given_screenshot_dir = self._norm_path(screenshot_directory)
    self._screenshot_taker = ScreenshotTaker(screenshot_module)

set_screenshot_directory(path)

Sets the directory where screenshots are saved.

It is possible to use / as a path separator in all operating systems. Path to the old directory is returned.

The directory can also be set in importing.

Source code in src/robot/libraries/Screenshot.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
def set_screenshot_directory(self, path):
    """Sets the directory where screenshots are saved.

    It is possible to use ``/`` as a path separator in all operating
    systems. Path to the old directory is returned.

    The directory can also be set in `importing`.
    """
    path = self._norm_path(path)
    if not os.path.isdir(path):
        raise RuntimeError("Directory '%s' does not exist." % path)
    old = self._screenshot_dir
    self._given_screenshot_dir = path
    return old

take_screenshot(name='screenshot', width='800px')

Takes a screenshot in JPEG format and embeds it into the log file.

Name of the file where the screenshot is stored is derived from the given name. If the name ends with extension .jpg or .jpeg, the screenshot will be stored with that exact name. Otherwise a unique name is created by adding an underscore, a running index and an extension to the name.

The name will be interpreted to be relative to the directory where the log file is written. It is also possible to use absolute paths. Using / as a path separator works in all operating systems.

width specifies the size of the screenshot in the log file.

Examples: (LOGDIR is determined automatically by the library) | Take Screenshot | | | # LOGDIR/screenshot_1.jpg (index automatically incremented) | | Take Screenshot | mypic | | # LOGDIR/mypic_1.jpg (index automatically incremented) | | Take Screenshot | ${TEMPDIR}/mypic | | # /tmp/mypic_1.jpg (index automatically incremented) | | Take Screenshot | pic.jpg | | # LOGDIR/pic.jpg (always uses this file) | | Take Screenshot | images/login.jpg | 80% | # Specify both name and width. | | Take Screenshot | width=550px | | # Specify only width. |

The path where the screenshot is saved is returned.

Source code in src/robot/libraries/Screenshot.py 
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
def take_screenshot(self, name="screenshot", width="800px"):
    """Takes a screenshot in JPEG format and embeds it into the log file.

    Name of the file where the screenshot is stored is derived from the
    given ``name``. If the ``name`` ends with extension ``.jpg`` or
    ``.jpeg``, the screenshot will be stored with that exact name.
    Otherwise a unique name is created by adding an underscore, a running
    index and an extension to the ``name``.

    The name will be interpreted to be relative to the directory where
    the log file is written. It is also possible to use absolute paths.
    Using ``/`` as a path separator works in all operating systems.

    ``width`` specifies the size of the screenshot in the log file.

    Examples: (LOGDIR is determined automatically by the library)
    | Take Screenshot |                  |     | # LOGDIR/screenshot_1.jpg (index automatically incremented) |
    | Take Screenshot | mypic            |     | # LOGDIR/mypic_1.jpg (index automatically incremented) |
    | Take Screenshot | ${TEMPDIR}/mypic |     | # /tmp/mypic_1.jpg (index automatically incremented) |
    | Take Screenshot | pic.jpg          |     | # LOGDIR/pic.jpg (always uses this file) |
    | Take Screenshot | images/login.jpg | 80% | # Specify both name and width. |
    | Take Screenshot | width=550px      |     | # Specify only width. |

    The path where the screenshot is saved is returned.
    """
    path = self._save_screenshot(name)
    self._embed_screenshot(path, width)
    return path

take_screenshot_without_embedding(name='screenshot')

Takes a screenshot and links it from the log file.

This keyword is otherwise identical to Take Screenshot but the saved screenshot is not embedded into the log file. The screenshot is linked so it is nevertheless easily available.

Source code in src/robot/libraries/Screenshot.py 
175
176
177
178
179
180
181
182
183
184
def take_screenshot_without_embedding(self, name="screenshot"):
    """Takes a screenshot and links it from the log file.

    This keyword is otherwise identical to `Take Screenshot` but the saved
    screenshot is not embedded into the log file. The screenshot is linked
    so it is nevertheless easily available.
    """
    path = self._save_screenshot(name)
    self._link_screenshot(path)
    return path