Screenshot Functions
Sahi's Screenshot functions takes the screen/browser screen-shot while running the sahi scripts.
_takeScreenShot
Section titled “_takeScreenShot”- Since
- Sahi Pro 4.5
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_takeScreenShot([$fileSysPath[, $noLog[, $props]]])Arguments
| Name | Type | Description |
|---|---|---|
$fileSysPath | stringoptional | file path to copy screenshot in file system. |
$noLog | booleanoptional | true to prevent embedding the image in the playback log. Default is false. |
$props | objectoptional | properties for image format(format) and image compression in precentage(resizePercentage) 1. format, string, optional, can be GIf, JPG or PNG Default is "sahi.screenshot.image.format" property defined in config/sahi.properties, this can be overridden in userdata/config/userdata.properties 2. resizePercentage, integer, optional Default is "sahi.screenshot.image.resize_percentage" property defined in config/sahi.properties, this can be override in userdata/config/userdata.properties 100 means no compression |
Returns
null |
Takes a screen shot and embeds the image in the test run report.
Since Sahi works without bringing the window into focus, we first need to call _focusWindow to bring the window into focus.
_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
Section titled “_takeScreenShots”- Since
- Sahi Pro 5.0
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_takeScreenShots($enable[, $directory[, $noLog]])Arguments
| Name | Type | Description |
|---|---|---|
$enable | boolean | true for enabling screenshots, false to disable |
$directory | stringoptional | file path directory to copy screenshot in file system |
$noLog | booleanoptional | true to prevent embedding the image in the playback log. |
Returns
null |
Takes a screen shot after every step and embeds the image in the test run report.
_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._takePageScreenShot
Section titled “_takePageScreenShot”- Since
- Sahi Pro 6.0.0
- Desktop Engine 8.0.0
- Mobile Engine 8.0.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_takePageScreenShot([$element[, $fileSysPath[, $noLog[, $props]]]])Arguments
| Name | Type | Description |
|---|---|---|
$element | HTML DOM elementoptional | If specified, a full page screenshot of the element would be taken |
$fileSysPath | stringoptional | File system path to save a copy of the screenshot, additionally to. Relative paths will be resolved relative to current executing script. Default is null. |
$noLog | booleanoptional | Pass true to prevent embedding the image in the playback log. Default is false. |
$props | objectoptional | Properties 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 false. 4. format, string, optional, can be GIF, JPG or PNG Default is "sahi.screenshot.image.format" property defined in config/sahi.properties. This can be overridden in userdata/config/userdata.properties 5. resizePercentage, integer, optional Default is "sahi.screenshot.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. For Desktop Applications, only format and resizePercentage properties($props) are supported, other properties($props) are not. |
Returns
null |
Takes a full page screenshot of a web page by scrolling to the end of the page and embeds the image in the test run report. 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_skipScreenShots
Section titled “_skipScreenShots”- Since
- Sahi Pro 11.2.0
- Desktop Engine 11.2.0
- Mobile Engine 11.2.0
- SAP Engine 11.2.0
Modes Browser
_skipScreenShots($enable)Arguments
| Name | Type | Description |
|---|---|---|
$enable | boolean | True to skip screenshots, false to disable. |
Returns
null |
When enabled, Screenshot functions namely _takeScreenShot, _takeScreenShots and _takePageScreenShot will be skipped. Capturing screenshot from Callback functions will also be skipped.
// Skip capturing screenshots_skipScreenShots(true);
_focusWindow();_takeScreenShot(); // This will be skipped
// Enable capturing screenshots_skipScreenShots(false);// Now, screenshot APIs will not be skipped._skipScreenShotsComparison
Section titled “_skipScreenShotsComparison”- Since
- Sahi Pro 11.2.0
- Desktop Engine 11.2.0
- Mobile Engine 11.2.0
- SAP Engine 11.2.0
Modes Browser
_skipScreenShotsComparison($enable)Arguments
| Name | Type | Description |
|---|---|---|
$enable | boolean | True to skip comparing screenshots, false to disable. |
Returns
null |
When enabled, functions that compare screenshots will be skipped. Thus, functions namely _assertSnapShot, _assertEqualImages and _compareImages will be skipped.
// Skip comparing screenshots_skipScreenShotsComparison(true);
_focusWindow();_takePageScreenShot(null, "D:/dev/images/login.png")
// Below line will be skippedvar $same = _compareImages("snapshot_login_page.png", "D:/dev/images/login.png");
// Enable comparing screenshots_skipScreenShotsComparison(false);_assertSnapShot
Section titled “_assertSnapShot”- Since
- Sahi Pro 6.0.0
- Desktop Engine 8.0.0
- Mobile Engine 8.0.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_assertSnapShot($refPath[, $element[, $differenceThreshold[, $displayOnSuccess[, $props]]]])Arguments
| Name | Type | Description |
|---|---|---|
$refPath | string | File path of the reference image to compare the page screenshot with. Relative paths will be resolved relative to current executing script. |
$element | HTML DOM elementoptional | If 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. |
$differenceThreshold | floatoptional | If 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. |
$displayOnSuccess | booleanoptional | When 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. |
$props | objectoptional | Properties 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 false. 4. format, string, optional, can be GIF, JPG or PNG Default is "sahi.screenshot.image.format" property defined in config/sahi.properties. This can be overridden in userdata/config/userdata.properties 5. resizePercentage, integer, optional Default is "sahi.screenshot.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 |
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 test run report.
If the assertion is a failure, _assertSnapShot will log failures to the test run report. The page screenshot, reference image and the differential image will be embedded in the test run report.
_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_compareImages
Section titled “_compareImages”- Since
- Sahi Pro 6.0.0
- Desktop Engine 7.0.0
- Mobile Engine 7.5.0
- SAP Engine 9.0.0
Modes BrowserWindowsJavaAndroidiOSSAP
_compareImages($f1, $f2[, $differenceThreshold])Arguments
| Name | Type | Description |
|---|---|---|
$f1 | string | File path of the first image. Relative paths will be resolved relative to current executing script. |
$f2 | string | File path of the second image. Relative paths will be resolved relative to current executing script. |
$differenceThreshold | floatoptional | If 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
boolean | true if both images are same, else false |
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);Configuring GraphicsMagick
Section titled “Configuring GraphicsMagick”To configure GraphicsMagick, follow the following steps.
Configure GM on Windows
Section titled “Configure GM on Windows”-
Download GraphicsMagick “GraphicsMagick-x.x.x-Qx-winxx-dll.exe” from GraphicsMagick windows
-
Install GraphicsMagick on your machine, say in
C:\GraphicsMagick\ -
Edit
sahi_pro\ext\imagetools\set_graphicsmagick.batand modify the contents to look like this:Terminal window set GM=C:\GraphicsMagick\gm
Configure GM on Linux
Section titled “Configure GM on Linux”-
Download GraphicsMagick “GraphicsMagick-x.x.xx-x.src.rpm” from GraphicsMagick linux
-
Install GraphicsMagick on your machine using apt/yum or your package manager. It would mostly install gm in
/usr/bin/(You can find the installed path by runningwhich gm) for more details Refer here. -
Edit
sahi_pro/ext/imagetools/set_graphicsmagick.shand modify the contents to look like this:Terminal window export GM=/usr/bin/gm
Configure GM on Mac
Section titled “Configure GM on Mac”-
Download GraphicsMagick “GraphicsMagick-x.x.xx-x.tar.gz” from GraphicsMagick Mac
-
Install GraphicsMagick on your machine using brew install graphicsmagick or your package manager. It would mostly install gm in
/usr/bin/(You can find the installed path by runningwhich gm) for more details Refer here. -
Edit
sahi_pro/ext/imagetools/set_graphicsmagick.shand modify the contents to look like this:Terminal window export GM=/usr/bin/gm
Skip Screenshots
Section titled “Skip Screenshots”Screenshot capturing can be skipped using _skipScreenShots API. With this, Screenshot functions namely _takeScreenShot, _takeScreenShots and _takePageScreenShot will be skipped. Capturing screenshot from Callback functions will also be skipped.
Screenshot comparison can be skipped using _skipScreenShotsComparison API. With this, functions that compare screenshots will be skipped. Thus, functions namely _assertSnapShot, _assertEqualImages and _compareImages will be skipped.
To skip screenshots in report on aborted, set property reports.skip_screenshots_on_aborted as true in userdata.properties file.
To skip screenshots in report on healed, set property reports.skip_screenshots_on_healed as true in userdata.properties file.

