Screenshot APIs

Sahi's Screenshot APIs takes the screen/browser screen-shot while running the sahi scripts.

_takeScreenShot

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
4.5NANA7.0.07.5.09.0.0

Available for modes: Browser | Windows | Java | Android | iOS | SAP

_takeScreenShot([$fileSysPath[, $noLog[, $props]]])

Arguments
$fileSysPathstring optionalfile path to copy screenshot in file system
$noLogboolean optionaltrue to prevent embedding the image in the playback log.
Default is false.
$propsobject optionalproperties for image format(format) and image compression in precentage(resizePercentage)

1. format, string, optional, can be GIf, JPG or PNG
Default is "sahi.takeScreenShot_image.format" property defines in config/sahi.properties, this can be overridden in userdata/config/userdata.properties

2. resizePercentage, integer, optional
Default is "sahi.takeScreenShot_image.resize_percentage" property defines in config/sahi.properties, this can be override in userdata/config/userdata.properties
100 means no compression

Returns
null

Details

Takes a screen shot and embeds the image in the playback log.
Since Sahi works without bringing the window into focus, we first need to call _focusWindow to bring the window into focus.
info Sahi currently takes the full window (desktop) screenshot, not just the browser window
info NOTE: For Desktop Applications only format and resizePercentage properties($props) are supported.
warning If _sahi.SKIP_SCREENSHOTS is specified as true, this API will be skipped.
danger In 6.0.0, $format and $resizePercentage have been moved into the $props parameter. Scripts written before 6.0.0 will need changes.
_focusWindow(); // bring window into focus
_takeScreenShot();
// captures screenshot in D:\dev\capture.jpg(compresses file size to 75% of the full size with jpg format)
// without embedding image in the playback log
_takeScreenShot("D:\\dev\\capture.jpg", true, {format:'jpg', resizePercentage:75});


_takeScreenShots

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
5.0NANA7.0.07.5.09.0.0

Available for modes: Browser | Windows | Java | Android | iOS | SAP

_takeScreenShots($enable[, $directory[, $noLog]])

Arguments
$enableboolean true for enabling screenshots, false to disable
$directorystring optionalfile path directory to copy screenshot in file system
$noLogboolean optionaltrue to prevent embedding the image in the playback log.

Returns
null

Details

Takes a screen shot after every step and embeds the image in the playback log.
_focusWindow(); // bring window into focus
// Enable screenshots
_takeScreenShots(true);
// perform actions
// screenshot will be taken after each step
// disable screenshots
_takeScreenShots(false);
// screenshots will not be taken now.
warning If _sahi.SKIP_SCREENSHOTS is specified as true, this API will be skipped.


_takePageScreenShot

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.0.0NANA8.0.08.0.09.0.0

Available for modes: Browser | Windows | Java | Android | iOS | SAP

_takePageScreenShot([$element[, $fileSysPath[, $noLog[, $props]]]])

Arguments
$elementHTML DOM element optionalIf specified, a full page screenshot of the element would be taken
$fileSysPathstring optionalFile system path to save a copy of the screenshot, additionally to. Relative paths will be resolved relative to current executing script.
Default is null.
$noLogboolean optionalPass true to prevent embedding the image in the playback log.
Default is false.
$propsobject optionalProperties to specify for image delay, scrollLimit, trim, format and image compression in percentage(resizePercentage).

1. delay, integer, optional, time delay between scroll and screenshot in milliseconds.
For long pages, the page is scrolled, individual screenshots are taken and then stitched.
Sometimes images on the page may load slowly on scroll and a wait may be needed between scroll and screenshot.
Default is 100 ms.

2. scrollLimit, integer, optional, height in pixels. Maximum scroll size in pixels for a page/element. Default is 200000.

3. trim, boolean, optional, Trim the image for blank space. Default is true. This works only if Graphics Magick is installed and configured correctly. Fails silently if not installed.

4. format, string, optional, can be GIF, JPG or PNG
Default is "sahi.takeScreenShot_image.format" property defined in config/sahi.properties. This can be overridden in userdata/config/userdata.properties

5. resizePercentage, integer, optional
Default is "sahi.takeScreenShot_image.resize_percentage" property defined in config/sahi.properties. This can be overridden in userdata/config/userdata.properties. 100 means no compression.

6. mode, integer, optional
Default is 1.
Set to 2 only if element parameter is specified and element has scrollbar or element is inside a scrolled element.

Returns
null

Details

    infoNOTE: Point number '6' in $props was added Since Sahi Pro: 6.2.1. For old document Refer here
    info NOTE: For Desktop Applications only format and resizePercentage properties($props) are supported.
Takes a full page screenshot of a web page by scrolling to the end of the page and embeds the image in the playback log. If the element attribute is specified, a full page screenshot of the browser element is taken, instead of the web page. Since Sahi works without bringing the window into focus, we first need to call _focusWindow to bring the window into focus.

_focusWindow(); // Brings window into focus
_takePageScreenShot(); // Captures the full browser page screenshot
_takePageScreenShot(_table("t4")); // Captures the table screenshot

// Captures table screenshot with jpg format, compresses file size to 75% of the full size, saves it to D:\dev\capture.jpg
// without embedding image in the playback log
_takePageScreenShot(_table("t4"), "D:/dev/capture.jpg", true, {format:'jpg', resizePercentage:75});

// Captures full div screenshot by scrolling to the end of the div.
// Use it in cases where a div has its own scrollbar.
_call(_div("myDIV").scrollIntoView()); // scroll the div into view first
_takePageScreenShot(_div("myDIV"), null, null, {mode:2}); // the div itself will be scrolled and screen shots taken
warning If _sahi.SKIP_SCREENSHOTS is specified as true, this API will be skipped.


_assertSnapShot

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.0.0NANA8.0.08.0.09.0.0

Available for modes: Browser | Windows | Java | Android | iOS | SAP

_assertSnapShot($refPath[, $element[, $differenceThreshold[, $displayOnSuccess[, $props]]]])

Arguments
$refPathstring File path of the reference image to compare the page screenshot with. Relative paths will be resolved relative to current executing script.
$elementHTML DOM element optionalIf specified, a full page screenshot of the element would be compared with the reference image. If not, a full page screenshot of the webpage would be compared with the reference image.
$differenceThresholdfloat optionalIf the difference between the reference image and the page screenshot is lesser than or equal to the differenceThreshold number, they are considered same.
If not specified, a value of 20 is assumed.
$displayOnSuccessboolean optionalWhen true, the page screenshot, reference image and the differential image will be embedded in the playback log, if the assertion succeeds.
Default is false.
Note that these images will always be embedded in case of assertion failure.
$propsobject optionalProperties to specify for image delay, scrollLimit, trim, format and image compression in percentage(resizePercentage).
1. delay, integer, optional, time delay between scroll and screenshot in milliseconds.
For long pages, the page is scrolled, individual screenshots are taken and then stitched.
Sometimes images on the page may load slowly on scroll and a wait may be needed between scroll and screenshot.
Default is 100 ms.

2. scrollLimit, integer, optional, height in pixels. Maximum scroll size in pixels for a page/element. Default is 200000.

3. trim, boolean, optional, Trim the image for blank space. Default is true. This works only if Graphics Magick is installed and configured correctly. Fails silently if not installed.

4. format, string, optional, can be GIF, JPG or PNG
Default is "sahi.takeScreenShot_image.format" property defined in config/sahi.properties. This can be overridden in userdata/config/userdata.properties

5. resizePercentage, integer, optional
Default is "sahi.takeScreenShot_image.resize_percentage" property defined in config/sahi.properties. This can be overridden in userdata/config/userdata.properties. 100 means no compression.

6. mode, integer, optional
Default is 1.
Set to 2 only if element attribute is specified and element has scrollbar.

Returns
null

Details

    infoNOTE: Point number '6' in $props was added Since Sahi Pro: 7.0.0. For old document Refer here
Takes the full page screen shot of the webpage or the browser element if specified, and compares with the reference image.
If the difference between the page screenshot and the reference image is lesser than or equal to the differenceThreshold, the images will be treated as same and the assertion is successful. Else the assertion is treated as a failure.
If the assertion is successful and displayOnSuccess is true, the page screenshot, reference image and the differential image will be embedded in the playback log.
If the assertion is a failure, _assertSnapShot will log failures to the playback log. The page screenshot, reference image and the differential image will be embedded in the playback log.

_navigateTo("http://sahi.co.in/demo/training");
_assertSnapShot("snapshot_login_page.png", _div(0), 20, true); // only _div(0) content would be compared with reference image.
// OR
_assertSnapShot("snapshot_login_page.png", null, 20, true); // passing null to compare with entire window screenshot
// OR
_assertSnapShot("snapshot_login_page.png",_div("myDIV"), 20, true, {mode:2}); // the div itself will be scrolled and screen shots taken
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails Use _compareImages instead.
infoThis api is dependent on GraphicsMagick software. To configure the GraphicsMagick on the system, refer Configuring GraphicsMagick
warning If _sahi.SKIP_ASSERT_SNAPSHOTS is specified as true, this API will be skipped.


_compareImages

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.0.0NANA7.0.07.5.09.0.0

Available for modes: Browser | Windows | Java | Android | iOS | SAP

_compareImages($f1, $f2[, $differenceThreshold])

Arguments
$f1string File path of the first image. Relative paths will be resolved relative to current executing script.
$f2string File path of the second image. Relative paths will be resolved relative to current executing script.
$differenceThresholdfloat optionalIf the difference between first and second image is lesser than or equal to the differenceThreshold number, they are considered to be same images.
Default is 20.

Returns
booleantrue if both images are same, else false

Details

Takes the path of the 2 images and checks if both images are same or not.

_navigateTo("http://sahi.co.in/demo/training");
_takePageScreenShot(null, "D:/dev/images/login.png")
var $same = _compareImages("snapshot_login_page.png", "D:/dev/images/login.png");
_assert($same);
infoThis api is dependent on GraphicsMagick software.
To configure the GraphicsMagick on the system, refer Configuring GraphicsMagick
warning If _sahi.SKIP_ASSERT_SNAPSHOTS is specified as true, this API will be skipped.


Configuring GraphicsMagick

To configure GraphicsMagick, follow the following steps.

Configure GM on Windows

Configure GM on Linux

Configure GM on Mac

Skip the Screenshot APIs

By using the boolean variables _sahi.SKIP_SCREENSHOTS and _sahi.SKIP_ASSERT_SNAPSHOTS, screenshot apis can be skipped.

Notes