Skip to content
Get Free Trial

Screenshot Functions

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

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

NameTypeDescription
$fileSysPathstringoptionalfile path to copy screenshot in file system.
$noLogbooleanoptionaltrue to prevent embedding the image in the playback log.
Default is false.
$propsobjectoptionalproperties 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});
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

NameTypeDescription
$enablebooleantrue for enabling screenshots, false to disable
$directorystringoptionalfile path directory to copy screenshot in file system
$noLogbooleanoptionaltrue 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.
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

NameTypeDescription
$elementHTML DOM elementoptionalIf specified, a full page screenshot of the element would be taken
$fileSysPathstringoptionalFile system path to save a copy of the screenshot, additionally to. Relative paths will be resolved relative to current executing script.
Default is null.
$noLogbooleanoptionalPass true to prevent embedding the image in the playback log.
Default is false.
$propsobjectoptionalProperties 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
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

NameTypeDescription
$enablebooleanTrue 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.
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

NameTypeDescription
$enablebooleanTrue 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 skipped
var $same = _compareImages("snapshot_login_page.png", "D:/dev/images/login.png");
// Enable comparing screenshots
_skipScreenShotsComparison(false);
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

NameTypeDescription
$refPathstringFile path of the reference image to compare the page screenshot with. Relative paths will be resolved relative to current executing script.
$elementHTML DOM elementoptionalIf 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.
$differenceThresholdfloatoptionalIf 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.
$displayOnSuccessbooleanoptionalWhen 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.
$propsobjectoptionalProperties 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
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

NameTypeDescription
$f1stringFile path of the first image. Relative paths will be resolved relative to current executing script.
$f2stringFile path of the second image. Relative paths will be resolved relative to current executing script.
$differenceThresholdfloatoptionalIf 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

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);

To configure GraphicsMagick, follow the following steps.

  • 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.bat and modify the contents to look like this:

    Terminal window
    set GM=C:\GraphicsMagick\gm
  • 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 running which gm) for more details Refer here.

  • Edit sahi_pro/ext/imagetools/set_graphicsmagick.sh and modify the contents to look like this:

    Terminal window
    export GM=/usr/bin/gm
  • 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 running which gm) for more details Refer here.

  • Edit sahi_pro/ext/imagetools/set_graphicsmagick.sh and modify the contents to look like this:

    Terminal window
    export GM=/usr/bin/gm

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.

  • If you use phantomjs browser to execute screenshot related function’s scripts, use only "png" format to save the screenshots.
  • Refer here for troubleshooting incorrect screenshot in Mac.
  • Refer here for troubleshooting incorrect screenshot with dual screen.