Sahi Pro - Screenshot APIs

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

_takeScreenShot

Since Sahi Pro: 4.5
Since Sahi OS: NA

_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

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
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 Pro: 5.0
Since Sahi OS: NA

_takeScreenShots($enable[, $directory])

Arguments
$enableboolean true for enabling screenshots, false to disable
$directorystring optionalfile path directory to copy screenshot in file system

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 Pro: 6.0.0
Since Sahi OS: NA

_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.

Details

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});
warning If _sahi.SKIP_SCREENSHOTS is specified as true, this API will be skipped.

_assertSnapShot

Since Sahi Pro: 6.0.0
Since Sahi OS: NA

_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.

Details

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", 20, true);
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, please refer Configuring GraphicsMagick
warning If _sahi.SKIP_ASSERT_SNAPSHOTS is specified as true, this API will be skipped.

_compareImages

Since Sahi Pro: 6.0.0
Since Sahi OS: NA

_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.

Details

Takes the path of the 2 images and checks if both images are same or not.
Returns true, if both images are same.
Returns false, if both images are not same.

_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, please 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/Mac

  • 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)
  • Edit sahi_pro/ext/imagetools/set_graphicsmagick.sh and modify the contents to look like this:
    export GM=/usr/bin/gm

  • Skip the Screenshot APIs

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

    Notes

    If you use phantomjs browser to execute screenshot related API's scripts. Please use only "png" format to save the screenshots.