Screenshot Command
3.3.3 Screenshot
DESCRIPTION
Screenshot - Take a screenshot of the current remote desktop and save it to a file.
The Screenshot command has been closely integrated with the Compareto command. Comparison is performed when a corresponding template image is found in the template directory (see the _TEMPLATE_DIR variable) and at least one of the following conditions is met:
- The Screenshot command contains at least one parameter originating from the Compareto command - 'template', 'passrate','onpass','onfail'.
- The option 'Perform auto comparison when the template is available' in the Screenshot command preferences is switched on.
Unless you specify a template image explicitly through the 'template' parameter, the command will search the template directory for a template with matching name and extension PNG, GIF, BMP and JPG (in this order). You can switch this feature off in the Screenshot preferences to force the command to search for templates with exactly the same file name as the screenshot images.
If the command performs image comparison it populates the image comparison specific variables.
SYNOPSIS
screenshot <file> [desc=<description>] [area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]][attach=<list_of_files>] [template=<image_collection>] [passrate=<pass_rate>%] [onpass=<command>] [onfail=<command>] [method=<comparison_method>] [methodparams=<custom_params>] [cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]] [drawresults=<true|false>] [drawdiff=<true|false>] [<method_specific_params>]
* Red colour indicates obligatory parameters
OPTIONS
file
- File name to save the image to. It MUST have a supported extension, for example "png" or "jpg". Supported image formats are subject to the Java version. Java 1.6 supports at least PNG, JPG, GIF and BMP. File name can be either relative (e.g. img.jpg) or absolute (e.g. /root/report/img.jpg). If the path doesn't exist, it is created. If you use relative path or just a file name, the image will be saved to a directory defined by the [_REPORT_DIR variable|#_report_dir].
desc=<description>
- Image description. It will be displayed in the report.
area=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
- This parameter can be used to specify which part (sub image) of the remote desktop will be saved. If you omit this parameter the whole remote desktop will be processed. The area coordinates have format of 'x:,y:,w:,h:', where each coordinate can be specified in pixels (e.g. 'x:225') or as a percentage (e.g. 'x:23%'). If any of x, y, width or height is omitted, T-Plan Robot will use the full screen values to determine the missing parameters, i.e. 'x:0, y:0, w:, h:'. You may also define the comparison area using the Screenshot window.
attach=<list_of_files>
- A file or a list of semicolon (';') separated files to be attached to a report. It provides a way to link for example log files and documents to the screenshot entry in the report. The report generator will list the attachments in the screenshot title in the HTML report and creates a hyperlink for each attached file. Please note that you have to copy the files to the target location on your own as T-Plan Robot neither copies the attached files to the report directory nor validates whether they exist there.
This parameter is obsoleted as it maintained compatibility with the previous versions. It is not supported in the Java script API.
template=<image_collection>
- An image collection - one or more image file names or folders with images separated by a semicolon (';') to be compared to the remote desktop image. On Linux/Unix make sure the file name doesn't contain semicolon because the list would be incorrectly parsed. File names can be either relative (e.g. img.png) or absolute (e.g. /root/report/img.png). If you use a relative path, the image will be searched in the directory defined by the _TEMPLATE_DIR variable. Supported image formats are subject to the Java version and installed extensions (such as the Java Advanced Imaging library, JAI). Java 1.6 supports at least PNG, JPG, GIF and BMP.
Template images will be compared with the remote desktop image in the specified list order. If a template comparison produces a positive result (either match or mismatch depending on the specified event), the condition is considered to be met and the command finishes with an exit code of 0. The predefined variable _COMPARETO_TEMPLATE_INDEX may be used to determine the index of the matching template in the list. See image comparison specific variables for more.
Image comparison should not be performed against images with lossy compression such as JPEG. Use PNG or BMP instead. They preserve 100% of the image information and guarantee reliable and stable comparison results. Image comparison is discussed in the Compareto command specification.
passrate=<pass_rate>[%]
- The pass rate for image comparison. It must be a number between 0 and 100 which may optionally be followed by the percentage character (for example "passrate=95" or "passrate=95%"). If this parameter is omitted, the default pass rate defined by the method or in the Robot preferences will be used (default values are 95% for the "default" and 100% for the "search" and "search2" methods).
method=<comparison_method>
- - The method (algorithm) to be used for image comparison. It must be one of the supported method names (codes) described in the Image Comparison Capabilities chapter or the name of a third party method enabled through the plugin interface. If omitted the command will use the default one.
methodparams=<custom_params>
- Custom parameters to be passed to the image comparison algorithm. As T-Plan Robot 2.0 default image comparison algorithms don't support any custom parameters, you don't need to specify this parameter unless you write your own algorithm.
cmparea=[x:<x>][,y:<y>][,w:<width>][,h:<height>]
- The rectangular area of the desktop to be limit the comparison to. If you omit this parameter the whole remote desktop will be used. The area coordinates have the format of 'x:,y:,w:,h:', where each coordinate can be specified in pixels (for example. "x:225") or as a percentage ("x:23%"). If any of x, y, width or height are omitted, T-Plan Robot will use the full-screen values to determine the missing parameters (x:0, y:0, w:, h:).
onfail=<command>
- A command to be executed when the image comparison fails. It must be one single command. If you need to define a sequence of command to be executed, use a procedure.
onpass=<command>
- A command to be executed when the image comparison succeeds. It must be a single command. To call a sequence of commands, use either a procedure or a subsequent if/else construction testing the command exit code.
drawresults=<true|false>
- This flag controls whether results of image comparison should be painted into the captured screenshot. The default value is false (meaning "do not paint any results"). If the command doesn't employ image comparison or the specified comparison method doesn't support result painting the parameter is ignored. In the default T-Plan Robot configuration, the "default" image comparison method doesn't support result painting because it doesn't make sense with regard to the algorithm nature. The "search" method does support result painting and draws rectangles corresponding to the match locations in the colour specified in command configuration.
drawdiff=<true|false>
- This flag controls whether the pixels differing from the template image should be painted in the configured colour (green by default). The parameter was introduced in v3.4 to support image difference tracking in reports. The default value is false (meaning "do not paint the difference"). If the command doesn't employ image comparison or the specified comparison method doesn't support pixel difference tracking the parameter is ignored. This feature is supported only by the "search" and "search2" algorithms.
method_specific_params
- See the documentation of individual image comparison methods for the list of supported specific parameters.
RETURNS
The command returns 0 (zero) if the screenshot is successfully saved and eventual image comparison passes. If image comparison takes place and fails, a value of 1 is returned. If the screenshot cannot be saved (e.g. not enough space), the command returns 2.
EXAMPLES
Screenshot image.jpg
- Take a screenshot of the current remote desktop and save it as a JPEG image into a file called image.jpg in a directory defined by the value of the _REPORT_DIR variable.
Screenshot /root/images/image2.png desc="This image shows what happened after I had clicked the Start button."
- Take a screenshot of the current remote desktop and save it as a PNG image into a file called image.png to the /root/images/ directory. If the executed script generates a report, the provided description will be displayed there.