<?xml version="1.0" encoding="UTF-8"?>
<keywordspec name="Screenshot" type="library" format="ROBOT" generated="20200529 10:52:03">
<version>3.1</version>
<scope>test suite</scope>
<namedargs>yes</namedargs>
<doc>Test library for taking screenshots on the machine where tests are run.

Notice that successfully taking screenshots requires tests to be run with
a physical or virtual display.

= Using with Python =

How screenshots are taken when using Python 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 :: Required also by RIDE so many Robot
  Framework users already have this module installed.
- 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.

Using ``screencapture`` on OSX and specifying explicit screenshot module
are new in Robot Framework 2.9.2. The support for using ``scrot`` is new
in Robot Framework 3.0.

= Using with Jython and IronPython =

With Jython and IronPython this library uses APIs provided by JVM and .NET
platforms, respectively. These APIs are always available and thus no
external modules are needed.

= 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.</doc>
<init>
<arguments>
<arg>screenshot_directory=None</arg>
<arg>screenshot_module=None</arg>
</arguments>
<doc>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 on Python 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. See `Using
with Python` for more information.

Examples (use only one of these):
| =Setting= |  =Value=   |  =Value=   |
| Library   | Screenshot |            |
| Library   | Screenshot | ${TEMPDIR} |
| Library   | Screenshot | screenshot_module=PyGTK |

Specifying explicit screenshot module is new in Robot Framework 2.9.2.</doc>
<tags>
</tags>
</init>
<kw name="Set Screenshot Directory">
<arguments>
<arg>path</arg>
</arguments>
<doc>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`.</doc>
<tags>
</tags>
</kw>
<kw name="Take Screenshot">
<arguments>
<arg>name=screenshot</arg>
<arg>width=800px</arg>
</arguments>
<doc>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.</doc>
<tags>
</tags>
</kw>
<kw name="Take Screenshot Without Embedding">
<arguments>
<arg>name=screenshot</arg>
</arguments>
<doc>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.</doc>
<tags>
</tags>
</kw>
</keywordspec>
