Preparation for the 1.1.0 release

README.rst

@@ -84,6 +84,28 @@ easy-to-understand tests as possible.
         Take Screenshot    name=screenshot  format=jpg  quality=0
         File Should Exist  screenshot_1.jpg
 
+
+Using with VNC
+--------------
+
+At the time of this release ``mss``, does not work on GNU/Linux with VNC virtual desktop.
+As a workaround you can change the ``screenshot_module`` value at library import to ``PyGTK``.
+
+.. code:: robotframework
+
+    *** Settings ***
+    Library                ScreenCapLibrary  screenshot_module=PyGTK
+
+For this to work you need to have the following dependencies installed.
+
+- With Python 2::
+
+    sudo apt install python-gtk2
+
+- With Python 3::
+
+    sudo apt install python-gi python-gi-cairo python3-gi python3-gi-cairo gir1.2-gtk-3.0
+
 Support
 -------
 

docs/ScreenCapLibrary-1.1.0.rst

@@ -0,0 +1,36 @@
+======================
+ScreenCapLibrary 1.1.0
+======================
+
+
+.. default-role:: code
+
+
+ScreenCapLibrary_ is a `Robot Framework`_ test library for taking screenshots.
+ScreencapLibrary 1.1.0 is a new release adding PyGTK screenshot module, to be
+able to take screenshots when using a virtual display like VNC (`#1`_).
+
+If you have pip_ installed, just run
+
+::
+
+   pip install robotframework-screencaplibrary
+
+to install the latest release or use
+
+::
+
+   pip install robotframework-screencaplibrary==1.1.0
+
+to install exactly this version. Alternatively you can download the source
+distribution from PyPI_ and install it manually.
+
+ScreenCapLibrary 1.1.0 was released on Tuesday September 11, 2018.
+
+.. _Robot Framework: http://robotframework.org
+.. _screencaplibrary: https://github.com/mihaiparvu/screencaplibrary
+.. _Screenshot: http://robotframework.org/robotframework/latest/libraries/Screenshot.html
+.. _pip: http://pip-installer.org
+.. _PyPI: https://pypi.python.org/pypi/robotframework-screencaplibrary
+.. _issue tracker: https://github.com/robotframework/screencaplibrary/issues
+.. _#1: https://github.com/mihaiparvu/ScreenCapLibrary/issues/1

docs/ScreenCapLibrary.html

@@ -5,7 +5,7 @@
 <meta http-equiv="Pragma" content="no-cache">
 <meta http-equiv="Expires" content="-1">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
-<meta content="Robot Framework 3.0.4 (Python 3.6.4 on win32)" name="Generator">
+<meta content="Robot Framework 3.0.4 (Python 3.6.5 on win32)" name="Generator">
 <link rel="icon" type="image/x-icon" href="data:image/x-icon;base64,AAABAAEAEBAAAAEAIABoBAAAFgAAACgAAAAQAAAAIAAAAAEAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKcAAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAAqAAAAAAAAAAAAAAAAAAAALIAAAD/AAAA4AAAANwAAADcAAAA3AAAANwAAADcAAAA3AAAANwAAADcAAAA4AAAAP8AAACxAAAAAAAAAKYAAAD/AAAAuwAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAC/AAAA/wAAAKkAAAD6AAAAzAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN8AAAD/AAAA+gAAAMMAAAAAAAAAAgAAAGsAAABrAAAAawAAAGsAAABrAAAAawAAAGsAAABrAAAADAAAAAAAAADaAAAA/wAAAPoAAADDAAAAAAAAAIsAAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAANEAAAAAAAAA2gAAAP8AAAD6AAAAwwAAAAAAAAAAAAAAMgAAADIAAAAyAAAAMgAAADIAAAAyAAAAMgAAADIAAAAFAAAAAAAAANoAAAD/AAAA+gAAAMMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADaAAAA/wAAAPoAAADDAAAAAAAAADwAAAB8AAAAAAAAAGAAAABcAAAAAAAAAH8AAABKAAAAAAAAAAAAAAAAAAAA2gAAAP8AAAD6AAAAwwAAAAAAAADCAAAA/wAAACkAAADqAAAA4QAAAAAAAAD7AAAA/wAAALAAAAAGAAAAAAAAANoAAAD/AAAA+gAAAMMAAAAAAAAAIwAAAP4AAAD/AAAA/wAAAGAAAAAAAAAAAAAAAMkAAAD/AAAAigAAAAAAAADaAAAA/wAAAPoAAADDAAAAAAAAAAAAAAAIAAAAcAAAABkAAAAAAAAAAAAAAAAAAAAAAAAAEgAAAAAAAAAAAAAA2gAAAP8AAAD7AAAAywAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAN4AAAD/AAAAqwAAAP8AAACvAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALIAAAD/AAAAsgAAAAAAAAC5AAAA/wAAAMoAAADAAAAAwAAAAMAAAADAAAAAwAAAAMAAAADAAAAAwAAAAMkAAAD/AAAAvAAAAAAAAAAAAAAAAAAAAKwAAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAA/wAAAP8AAAD/AAAArQAAAAAAAAAAwAMAAIABAAAf+AAAP/wAAD/8AAAgBAAAP/wAAD/8AAA//AAAJIwAADHEAAA//AAAP/wAAB/4AACAAQAAwAMAAA==">
 <style media="all" type="text/css">
 body {
@@ -547,7 +547,7 @@
 jQuery.extend({highlight:function(e,t,n,r){if(e.nodeType===3){var i=e.data.match(t);if(i){var s=document.createElement(n||"span");s.className=r||"highlight";var o=e.splitText(i.index);o.splitText(i[0].length);var u=o.cloneNode(true);s.appendChild(u);o.parentNode.replaceChild(s,o);return 1}}else if(e.nodeType===1&&e.childNodes&&!/(script|style)/i.test(e.tagName)&&!(e.tagName===n.toUpperCase()&&e.className===r)){for(var a=0;a<e.childNodes.length;a++){a+=jQuery.highlight(e.childNodes[a],t,n,r)}}return 0}});jQuery.fn.unhighlight=function(e){var t={className:"highlight",element:"span"};jQuery.extend(t,e);return this.find(t.element+"."+t.className).each(function(){var e=this.parentNode;e.replaceChild(this.firstChild,this);e.normalize()}).end()};jQuery.fn.highlight=function(e,t){var n={className:"highlight",element:"span",caseSensitive:false,wordsOnly:false};jQuery.extend(n,t);if(e.constructor===String){e=[e]}e=jQuery.grep(e,function(e,t){return e!=""});e=jQuery.map(e,function(e,t){return e.replace(/[-[\]{}()*+?.,\\^$|#\s]/g,"\\$&")});if(e.length==0){return this}var r=n.caseSensitive?"":"i";var i="("+e.join("|")+")";if(n.wordsOnly){i="\\b"+i+"\\b"}var s=new RegExp(i,r);return this.each(function(){jQuery.highlight(this,s,n.element,n.className)})}
 </script>
 <script type="text/javascript">
-libdoc = {"all_tags":[],"contains_tags":false,"doc":"<p>Test Library for taking screenshots on the machine where tests are run.\x3c/p>\n<p>Note that successfully taking screenshots requires tests to be run with a physical or virtual display.\x3c/p>\n<h2 id=\"Usage\">Usage\x3c/h2>\n<p>How screenshots are taken when using Python depends on the chosen format. There are two formats supported: PNG and JPG/JPEG. If no format is specified the screenshots will have the PNG format.\x3c/p>\n<p>For taking screenshots the following modules are used:\x3c/p>\n<ul>\n<li><a href=\"https://python-mss.readthedocs.io\">mss\x3c/a> a fast cross-platform module used for taking screenshots and saving them in PNG format.\x3c/li>\n\x3c/ul>\n<ul>\n<li><a href=\"https://pillow.readthedocs.io\">Pillow\x3c/a> used on top of <code>mss\x3c/code> in order to save the screenshots in JPG/JPEG format.\x3c/li>\n\x3c/ul>\n<h2 id=\"Where screenshots are saved\">Where screenshots are saved\x3c/h2>\n<p>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.\x3c/p>\n<p>It is possible to specify a custom location for screenshots using <code>screenshot_directory\x3c/code> argument when <a href=\"#Importing\" class=\"name\">importing\x3c/a> the library and using <a href=\"#Set%20Screenshot%20Directory\" class=\"name\">Set Screenshot Directory\x3c/a> keyword during execution. It is also possible to save screenshots using an absolute path.\x3c/p>","generated":"2018-08-23 15:29:10","inits":[{"args":["screenshot_directory=None","format=png","quality=50"],"doc":"<p>Configure where screenshots are saved.\x3c/p>\n<p>If <code>screenshot_directory\x3c/code> is not given, screenshots are saved into same directory as the log file. The directory can also be set using <a href=\"#Set%20Screenshot%20Directory\" class=\"name\">Set Screenshot Directory\x3c/a> keyword.\x3c/p>\n<p><code>format\x3c/code> specifies the format in which the screenshots will be saved. Possible values are <code>png\x3c/code>,  <code>jpeg\x3c/code> and <code>jpg\x3c/code>, case-insensitively. If no value is given the format is set by default to <code>png\x3c/code>.\x3c/p>\n<p><code>quality\x3c/code> can take values in range [0, 100]. Value 0 is lowest quality, while value 100 is maximum quality. The quality is directly proportional with file size. Because PNG uses lossless compression its size may be larger than the size of the JPG file. The default value is 50.\x3c/p>\n<p>Examples (use only one of these):\x3c/p>\n<table border=\"1\">\n<tr>\n<th>Setting\x3c/th>\n<th>Value\x3c/th>\n<th>Value\x3c/th>\n\x3c/tr>\n<tr>\n<td>Library\x3c/td>\n<td>Screenshot\x3c/td>\n<td>\x3c/td>\n\x3c/tr>\n<tr>\n<td>Library\x3c/td>\n<td>Screenshot\x3c/td>\n<td>${TEMPDIR}\x3c/td>\n\x3c/tr>\n<tr>\n<td>Library\x3c/td>\n<td>Screenshot\x3c/td>\n<td>format=jpg\x3c/td>\n\x3c/tr>\n<tr>\n<td>Library\x3c/td>\n<td>Screenshot\x3c/td>\n<td>quality=0\x3c/td>\n\x3c/tr>\n\x3c/table>","matched":true,"name":"Init","shortdoc":"Configure where screenshots are saved.","tags":[]}],"keywords":[{"args":["path"],"doc":"<p>Sets the directory where screenshots are saved.\x3c/p>\n<p>It is possible to use <code>/\x3c/code> as a path separator in all operating systems. Path to the old directory is returned.\x3c/p>\n<p>The directory can also be set in <a href=\"#Importing\" class=\"name\">importing\x3c/a>.\x3c/p>","matched":true,"name":"Set Screenshot Directory","shortdoc":"Sets the directory where screenshots are saved.","tags":[]},{"args":["name=screenshot","format=None","quality=None","width=800px"],"doc":"<p>Takes a screenshot in the specified format at library import and embeds it into the log file (PNG by default).\x3c/p>\n<p>Name of the file where the screenshot is stored is derived from the given <code>name\x3c/code>. If the <code>name\x3c/code> ends with extension <code>.jpg\x3c/code>, <code>.jpeg\x3c/code> or <code>.png\x3c/code>, 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 <code>name\x3c/code>.\x3c/p>\n<p>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 <code>/\x3c/code> as a path separator works in all operating systems.\x3c/p>\n<p><code>format\x3c/code> specifies the format in which the screenshot is saved. If no format is provided the library import value will be used which is <code>png\x3c/code> by default. Can be either <code>jpg\x3c/code>, <code>jpeg\x3c/code> or <code>png\x3c/code>, case insensitive.\x3c/p>\n<p><code>quality\x3c/code> can take values in range [0, 100]. In case of JPEG format it can drastically reduce the file size of the image.\x3c/p>\n<p><code>width\x3c/code> specifies the size of the screenshot in the log file.\x3c/p>\n<p>Examples: (LOGDIR is determined automatically by the library)\x3c/p>\n<table border=\"1\">\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>\x3c/td>\n<td>\x3c/td>\n<td># LOGDIR/screenshot_1.png (index automatically incremented)\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>mypic\x3c/td>\n<td>\x3c/td>\n<td># LOGDIR/mypic_1.png (index automatically incremented)\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>${TEMPDIR}/mypic\x3c/td>\n<td>\x3c/td>\n<td># /tmp/mypic_1.png (index automatically incremented)\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>pic.jpg\x3c/td>\n<td>\x3c/td>\n<td># LOGDIR/pic.jpg (always uses this file)\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>images/login.jpg\x3c/td>\n<td>300px\x3c/td>\n<td># Specify both name and width.\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>width=550px\x3c/td>\n<td>\x3c/td>\n<td># Specify only width.\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>format=jpg\x3c/td>\n<td>quality=15\x3c/td>\n<td># Specify both image format and quality\x3c/td>\n\x3c/tr>\n\x3c/table>\n<p>The path where the screenshot is saved is returned.\x3c/p>","matched":true,"name":"Take Screenshot","shortdoc":"Takes a screenshot in the specified format at library import and","tags":[]},{"args":["name=screenshot","format=None","quality=None"],"doc":"<p>Takes a screenshot and links it from the log file. This keyword is otherwise identical to <a href=\"#Take%20Screenshot\" class=\"name\">Take Screenshot\x3c/a> but the saved screenshot is not embedded into the log file. The screenshot is linked so it is nevertheless easily available.\x3c/p>","matched":true,"name":"Take Screenshot Without Embedding","shortdoc":"Takes a screenshot and links it from the log file.","tags":[]}],"name":"ScreenCapLibrary","named_args":true,"scope":"test case","version":"1.0.0"};
+libdoc = {"all_tags":[],"contains_tags":false,"doc":"<p>Test Library for taking screenshots on the machine where tests are run.\x3c/p>\n<p>Note that successfully taking screenshots requires tests to be run with a physical or virtual display.\x3c/p>\n<h2 id=\"Usage\">Usage\x3c/h2>\n<p>How screenshots are taken when using Python depends on the chosen format. There are two formats supported: PNG and JPG/JPEG. If no format is specified the screenshots will have the PNG format.\x3c/p>\n<p>For taking screenshots the following modules are used:\x3c/p>\n<ul>\n<li><a href=\"https://python-mss.readthedocs.io\">mss\x3c/a> a fast cross-platform module used for taking screenshots and saving them in PNG format.\x3c/li>\n\x3c/ul>\n<ul>\n<li><a href=\"https://pillow.readthedocs.io\">Pillow\x3c/a> used on top of <code>mss\x3c/code> in order to save the screenshots in JPG/JPEG format.\x3c/li>\n\x3c/ul>\n<ul>\n<li><a href=\"http://pygtk.org/\">PyGTK\x3c/a> is an alternative to <code>mss\x3c/code> for taking screenshots when using VNC.\x3c/li>\n\x3c/ul>\n<h2 id=\"Where screenshots are saved\">Where screenshots are saved\x3c/h2>\n<p>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.\x3c/p>\n<p>It is possible to specify a custom location for screenshots using <code>screenshot_directory\x3c/code> argument when <a href=\"#Importing\" class=\"name\">importing\x3c/a> the library and using <a href=\"#Set%20Screenshot%20Directory\" class=\"name\">Set Screenshot Directory\x3c/a> keyword during execution. It is also possible to save screenshots using an absolute path.\x3c/p>","generated":"2018-09-11 10:30:51","inits":[{"args":["screenshot_module=None","screenshot_directory=None","format=png","quality=50"],"doc":"<p><code>screenshot_module\x3c/code> specifies the module or tool to use when taking screenshots using this library. If no tool or module is specified, <code>mss\x3c/code> will be used by default. For running on Linux with VNC, use <code>PyGTK\x3c/code>.\x3c/p>\n<p>To configure where screenshots are saved use <code>screenshot_directory\x3c/code>. If no value is given, screenshots are saved into same directory as the log file. The directory can also be set using <a href=\"#Set%20Screenshot%20Directory\" class=\"name\">Set Screenshot Directory\x3c/a> keyword.\x3c/p>\n<p><code>format\x3c/code> specifies the format in which the screenshots will be saved. Possible values are <code>png\x3c/code>,  <code>jpeg\x3c/code> and <code>jpg\x3c/code>, case-insensitively. If no value is given the format is set by default to <code>png\x3c/code>.\x3c/p>\n<p><code>quality\x3c/code> can take values in range [0, 100]. Value 0 is lowest quality, while value 100 is maximum quality. The quality is directly proportional with file size. Because PNG uses lossless compression its size may be larger than the size of the JPG file. The default value is 50.\x3c/p>\n<p>Examples (use only one of these):\x3c/p>\n<table border=\"1\">\n<tr>\n<th>Setting\x3c/th>\n<th>Value\x3c/th>\n<th>Value\x3c/th>\n\x3c/tr>\n<tr>\n<td>Library\x3c/td>\n<td>Screenshot\x3c/td>\n<td>\x3c/td>\n\x3c/tr>\n<tr>\n<td>Library\x3c/td>\n<td>Screenshot\x3c/td>\n<td>PyGTK\x3c/td>\n\x3c/tr>\n<tr>\n<td>Library\x3c/td>\n<td>Screenshot\x3c/td>\n<td>screenshot_directory=${TEMPDIR}\x3c/td>\n\x3c/tr>\n<tr>\n<td>Library\x3c/td>\n<td>Screenshot\x3c/td>\n<td>format=jpg\x3c/td>\n\x3c/tr>\n<tr>\n<td>Library\x3c/td>\n<td>Screenshot\x3c/td>\n<td>quality=0\x3c/td>\n\x3c/tr>\n\x3c/table>","matched":true,"name":"Init","shortdoc":"``screenshot_module`` specifies the module or tool to use when taking screenshots using this library.","tags":[]}],"keywords":[{"args":["path"],"doc":"<p>Sets the directory where screenshots are saved.\x3c/p>\n<p>It is possible to use <code>/\x3c/code> as a path separator in all operating systems. Path to the old directory is returned.\x3c/p>\n<p>The directory can also be set in <a href=\"#Importing\" class=\"name\">importing\x3c/a>.\x3c/p>","matched":true,"name":"Set Screenshot Directory","shortdoc":"Sets the directory where screenshots are saved.","tags":[]},{"args":["name=screenshot","format=None","quality=None","width=800px"],"doc":"<p>Takes a screenshot in the specified format at library import and embeds it into the log file (PNG by default).\x3c/p>\n<p>Name of the file where the screenshot is stored is derived from the given <code>name\x3c/code>. If the <code>name\x3c/code> ends with extension <code>.jpg\x3c/code>, <code>.jpeg\x3c/code> or <code>.png\x3c/code>, 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 <code>name\x3c/code>.\x3c/p>\n<p>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 <code>/\x3c/code> as a path separator works in all operating systems.\x3c/p>\n<p><code>format\x3c/code> specifies the format in which the screenshot is saved. If no format is provided the library import value will be used which is <code>png\x3c/code> by default. Can be either <code>jpg\x3c/code>, <code>jpeg\x3c/code> or <code>png\x3c/code>, case insensitive.\x3c/p>\n<p><code>quality\x3c/code> can take values in range [0, 100]. In case of JPEG format it can drastically reduce the file size of the image.\x3c/p>\n<p><code>width\x3c/code> specifies the size of the screenshot in the log file.\x3c/p>\n<p>Examples: (LOGDIR is determined automatically by the library)\x3c/p>\n<table border=\"1\">\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>\x3c/td>\n<td>\x3c/td>\n<td># LOGDIR/screenshot_1.png (index automatically incremented)\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>mypic\x3c/td>\n<td>\x3c/td>\n<td># LOGDIR/mypic_1.png (index automatically incremented)\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>${TEMPDIR}/mypic\x3c/td>\n<td>\x3c/td>\n<td># /tmp/mypic_1.png (index automatically incremented)\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>pic.jpg\x3c/td>\n<td>\x3c/td>\n<td># LOGDIR/pic.jpg (always uses this file)\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>images/login.jpg\x3c/td>\n<td>300px\x3c/td>\n<td># Specify both name and width.\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>width=550px\x3c/td>\n<td>\x3c/td>\n<td># Specify only width.\x3c/td>\n\x3c/tr>\n<tr>\n<td>Take Screenshot\x3c/td>\n<td>format=jpg\x3c/td>\n<td>quality=15\x3c/td>\n<td># Specify both image format and quality\x3c/td>\n\x3c/tr>\n\x3c/table>\n<p>The path where the screenshot is saved is returned.\x3c/p>","matched":true,"name":"Take Screenshot","shortdoc":"Takes a screenshot in the specified format at library import and","tags":[]},{"args":["name=screenshot","format=None","quality=None"],"doc":"<p>Takes a screenshot and links it from the log file. This keyword is otherwise identical to <a href=\"#Take%20Screenshot\" class=\"name\">Take Screenshot\x3c/a> but the saved screenshot is not embedded into the log file. The screenshot is linked so it is nevertheless easily available.\x3c/p>","matched":true,"name":"Take Screenshot Without Embedding","shortdoc":"Takes a screenshot and links it from the log file.","tags":[]}],"name":"ScreenCapLibrary","named_args":true,"scope":"test case","version":"1.1.0"};
 </script>
 <title></title>
 </head>