Assertions

Assertions compare runtime behaviour against expected behaviour. Assertions are used for "verification" or "checking" of functionality
Assertions are an integral part of Sahi scripts. A normal script would contain a series of actions followed by verification of functionality.

_assert

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assert($condition[, $message])

Arguments
$conditionboolean condition to verify
$messagestring optionalmessage to log if condition fails

Returns
null

Details

_assert will do nothing if the condition passed to it is true.
_assert will log failures to the playback logs if the condition evaluates to false.
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails

_assertTrue

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertTrue($condition[, $message])

Arguments
$conditionboolean condition to verify
$messagestring optionalmessage to log if condition fails

Returns
null

Details

Same as _assert


_assertNotTrue

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertNotTrue($condition[, $message])

Arguments
$conditionboolean condition which is expected to evaluate to false
$messagestring optionalmessage to log if condition evaluates to true

Returns
null

Details

_assertNotTrue will do nothing if the condition evaluates to false.
_assertNotTrue will log failures to the playback logs if the condition evaluates to 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


_assertFalse

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertFalse($condition[, $message])

Arguments
$conditionboolean condition which is expected to evaluate to false
$messagestring optionalmessage to log if condition evaluates to true

Returns
null

Details

_assertFalse will do nothing if the condition evaluates to false.
_assertFalse will log failures to the playback logs if the condition evaluates to 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


_assertNull

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertNull($value[, $message])

Arguments
$valueanything Anything to be checked for null
$messagestring optionalmessage to log if value is not null

Returns
null

Details

_assertNull will do nothing if the value passed is null.
_assertNull will log failures to the playback logs if the value is not null.
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertNotNull

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertNotNull($value[, $message])

Arguments
$valueanything Anything to be checked for not null
$messagestring optionalmessage to log if value is null

Returns
null

Details

_assertNotNull will do nothing if the value passed is not null.
_assertNotNull will log failures to the playback logs if the value is null.
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertExists

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertExists($element[, $message])

Arguments
$elementHTML DOM element element to be checked for existence
$messagestring optionalmessage to log if element does not exist on page

Returns
null

Details

_assertExists will do nothing if the element exists.
_assertExists will log failures to the playback logs if the element does not exist
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertVisible

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.0.0NA7.0.17.0.07.5.09.0.0

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

_assertVisible($element[, $message])

Arguments
$elementHTML DOM element element to be checked for visibility.
$messagestring optionalmessage to log if element is not visible.

Returns
null

Details

_assertVisible will do nothing if the element is visible.
_assertVisible will log failures to the playback logs if the element is not visible
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertNotVisible

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.0.0NA7.0.17.0.07.5.09.0.0

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

_assertNotVisible($element[, $message])

Arguments
$elementHTML DOM element element to be checked for not visible.
$messagestring optionalmessage to log if element is visible.

Returns
null

Details

_assertNotVisible will do nothing if the element is not visible.
_assertNotVisible will log failures to the playback logs if the element is visible
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertNotExists

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertNotExists($element[, $message])

Arguments
$elementHTML DOM element element to be checked for non existence
$messagestring optionalmessage to log if element exists on page

Returns
null

Details

_assertNotExists will do nothing if the element does not exist.
_assertNotExists will log failures to the playback logs if the element exists
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertEqual

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertEqual($expected, $actual[, $message])

Arguments
$expectedany Expected value. This value can be any normal javascript data type or an array Regular expressions can also be used. (eg. "/del/")
$actualany Actual value. This value can be any normal javascript data type or an array. It is mostly some attribute of a HTML DOM element.
$messagestring optional Message to be written to logs if the expected and actual values are not equal

Returns
null

Details

_assertEqual will do nothing if the expected and actual values match.
_assertEqual will log failures to the playback logs if the expected and actual values are not equal
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertEqualArrays

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.537.0.17.0.0NANA

Available for modes: Browser | Windows | Java

_assertEqualArrays($expected, $actual[, $message])

Arguments
$expectedarray Expected array.
$actualarray Actual array.
$messagestring optional Message to be written to logs if the expected and actual values are not equal

Returns
null

Details

Asserts that expected and actual arrays are equal, else logs the message.
dangerDEPRECATED: This is internally called by _assertEqual if expected and actual are arrays. Use _assertEqual instead


_assertNotEqual

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertNotEqual($expected, $actual[, $message])

Arguments
$expectedany Expected value. This value can be any normal javascript data type or an array Regular expressions can also be used. (eg. "/del/")
$actualany Actual value. This value can be any normal javascript data type or an array. It is mostly some attribute of a HTML DOM element.
$messagestring optional Message to be written to logs if the expected and actual values are equal

Returns
null

Details

_assertNotEqual will do nothing if the expected and actual values do not match.
_assertNotEqual will log failures to the playback logs if the expected and actual values are equal
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertContainsText

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.527.0.17.0.07.5.09.0.0

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

_assertContainsText($expected, $element[, $message])

Arguments
$expectedstring Expected string. Regular expressions can also be used. (eg. "/del/")
$elementHTML DOM element Element. We check if expected is a part of the text of this element.
$messagestring optional Message to be written to logs if the expected string is not part of the text of given element

Returns
null

Details

_assertContainsText will do nothing if the expected string/regex is part of the text content of given element.
_assertContainsText will log failures to the playback logs if the expected string/regex is not part of the text content of given element
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertNotContainsText

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
3.537.0.17.0.07.5.09.0.0

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

_assertNotContainsText($expected, $element[, $message])

Arguments
$expectedstring Expected string. Regular expressions can also be used. (eg. "/del/")
$elementHTML DOM element Element. We check if expected is not a part of the text of this element.
$messagestring optional Message to be written to logs if the expected string is part of the text of given element

Returns
null

Details

_assertNotContainsText will do nothing if the expected string/regex is not part of the text content of given element.
_assertNotContainsText will log failures to the playback logs if the expected string/regex is part of the text content of given element
danger DO NOT USE THIS IN AN IF CONDITION as it does not return any value, and throws an exception if the assertion fails


_assertEqualImages

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

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

_assertEqualImages($expectedImagePath, $actualImagePath[, $differenceThreshold[, $displayOnSuccess[, $failureMessage]]])

Arguments
$expectedImagePathstring Expected image path. Relative paths will be resolved relative to current executing script.
$actualImagePathstring Actual image path. Relative paths will be resolved relative to current executing script.
$differenceThresholdfloat optionalIf the difference between the two images is lesser than or equal to the differenceThreshold number, they are considered to be same.
$displayOnSuccessboolean optionalWhen true, the expected image, actual image and the differential image will be embedded in the playback log, if the assertion succeeds.
Default is false, which means only dissimilar images will be logged. Note that these images will always be embedded in case of assertion failure.
$failureMessagestring optional Message to be written to logs if the image comparison fails

Returns
null

Details

_assertEqualImages compares two images. If the images are similar, assertion passes. If the images are dissimilar, the images and the failure messasge will be displayed in logs as failure.
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.


_assertHorizontallyAligned

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.3.0NANA8.0.0NANA

Available for modes: Browser | Windows | Java

_assertHorizontallyAligned($leftElement, $rightElement[, $position[, $gap[, $offset[, $message]]]])

Arguments
$leftElementHTML DOM element Left element to be asserted.
$rightElementHTML DOM element Right element to be asserted.
$positionstring optionalPosition to be checked. By default position = "middle". Value of position can be either "top" or "bottom" or "both" or "middle".
$gapinteger array|integer optionalGap between right edge of left element and left edge of right element. If gap is an integer, it will take the exact value. And if gap is an array, Eg. gap = [10, 40], implies gap can range from 10 to 40. To force sahi to check for the gap between the two elements, use the gap. If nothing provided it wouldn't consider gap.
$offsetinteger array|integer optional Offset above and below within which to look for elements boundary for given position. If offset is an integer, both above and below offsets are set to this offset. rightElement may be slightly above or below leftElement. Sahi normally matches only elements whose bases match. To force it to look a little above or below while looking to the right, use the offset.
$messagestring optional Message to be written to logs if the assertion fails

Returns
null

Details

_assertHorizontallyAligned checks if two elements are horizontally aligned. If the elements are horizontally aligned, assertion passes. If the elements are not horizontally aligned, the failure messasge will be displayed in logs as failure.
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 _areHorizontallyAligned instead.
Example
_assertHorizontallyAligned(_div("item1"), _div("item2")) //by default middle position will be checked
_assertHorizontallyAligned(_div("item1"), _div("item2"), "top")
_assertHorizontallyAligned(_div("item1"), _div("item2"), "top", 20) //gap can take the values between [-20, 20]
_assertHorizontallyAligned(_div("item1"), _div("item2"), "top", [0, 20]) //gap is only positive i.e. no overlapping is allowed
_assertHorizontallyAligned(_div("item1"), _div("item2"), "top", [0, 20], 10) //gap is only positive i.e. no overlapping is allowed and offset for the top edge is 10


_assertVerticallyAligned

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.3.0NANA8.0.0NANA

Available for modes: Browser | Windows | Java

_assertVerticallyAligned($topElement, $bottomElement[, $position[, $gap[, $offset[, $message]]]])

Arguments
$topElementHTML DOM element Top element to be asserted.
$bottomElementHTML DOM element Bottom element to be asserted.
$positionstring optionalPosition to be checked. By default position = "center". Value of position can be either "left" or "right" or "both" or "center".
$gapinteger array|integer optionalGap between bottom edge of top element and top edge of bottom element. If gap is an integer, it will take the exact value. And if gap is an array, Eg. gap = [0, 40], implies gap can range from 0 to 40. To force sahi to check for the gap between the two elements, use the gap. If nothing provided it wouldn't consider gap.
$offsetinteger array|integer optional Offset left and right within which to look for elements boundary for given position. If offset is an integer, both left and right offsets are set to this offset. topElement may be slightly left or right to the bottomElement.
$messagestring optional Message to be written to logs if the assertion fails

Returns
null

Details

_assertVerticallyAligned checks if two elements are vertically aligned. If the elements are vertically aligned, assertion passes. If the elements are not vertically aligned, the failure messasge will be displayed in logs as failure.
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 _areVerticallyAligned instead.
Example
_assertVerticallyAligned(_div("item1"), _div("item2")) //by default center position will be checked
_assertVerticallyAligned(_div("item1"), _div("item2"), "left")
_assertVerticallyAligned(_div("item1"), _div("item2"), "left", 20) //gap can take the values between [-20, 20]
_assertVerticallyAligned(_div("item1"), _div("item2"), "left", [0, 20]) //gap is only positive i.e. no overlapping is allowed


_assertCentered

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.3.0NANA8.0.0NANA

Available for modes: Browser | Windows | Java

_assertCentered($element, $containerElement, $alignment[, $message])

Arguments
$elementHTML DOM element Inner element to be asserted.
$containerElementHTML DOM element Container element to be asserted.
$alignmentstring Can be "vertical" or "horizontal".
$messagestring optional Message to be written to logs if the assertion fails

Returns
null

Details

_assertCentered checks if inner element is vertically or horizontally centered to the container element. If the elements are vertically or horizontally aligned, assertion passes. If the elements are not vertically or horizontally aligned, the failure messasge will be displayed in logs as failure.
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 _isCentered instead.
Example
_assertCentered(_div("item1"), _div("item2"), "vertical")
_assertCentered(_div("item1"), _div("item2"), "horizontal")


_assertVisiblyInside

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.3.0NANA8.0.0NANA

Available for modes: Browser | Windows | Java

_assertVisiblyInside($element1, $element2[, $message])

Arguments
$element1HTML DOM element First element to be asserted.
$element2HTML DOM element Second element to be asserted.
$messagestring optional Message to be written to logs if the assertion fails

Returns
null

Details

_assertVisiblyInside checks if element1 is visibly inside element2. If element1 is visibly inside element2, assertion passes. If element1 is not visibly inside element2, the failure messasge will be displayed in logs as failure.
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 _isVisiblyInside instead.


_assertVisiblyOutside

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.3.0NANA8.0.0NANA

Available for modes: Browser | Windows | Java

_assertVisiblyOutside($element1, $element2[, $message])

Arguments
$element1HTML DOM element First element to be asserted.
$element2HTML DOM element Second element to be asserted.
$messagestring optional Message to be written to logs if the assertion fails

Returns
null

Details

_assertVisiblyOutside checks if element1 is visibly outside element2 i.e one is not contained within other. If element1 is visibly outside element2, assertion passes. If element1 is not visibly outside element2, the failure messasge will be displayed in logs as failure.
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 _isVisiblyOutside instead.


_assertVisiblyOn

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.3.0NANA8.0.0NANA

Available for modes: Browser | Windows | Java

_assertVisiblyOn($element1, $element2[, $topSpace[, $rightSpace[, $bottomSpace[, $leftSpace[, $message]]]]])

Arguments
$element1HTML DOM element First element to be asserted.
$element2HTML DOM element Second element to be asserted. Base Element.
$topSpaceinteger array|integer optionalSpace between top edges of the two elements. If topSpace is an integer, it will take the exact value. And if topSpace = [-20, 0], implies top edge of element2 lies above top edge of element1. To force sahi to check for the topSpace between the two elements, use the topSpace. If nothing provided it wouldn't consider topSpace.
$rightSpaceinteger array|integer optionalSpace between right edges of the two elements. If rightSpace is an integer, it will take the exact value. And if rightSpace = [0, 20], implies right edge of element2 lies to the right side of right edge of element1. To force sahi to check for the rightSpace between the two elements, use the rightSpace. If nothing provided it wouldn't consider rightSpace.
$bottomSpaceinteger array|integer optionalSpace between bottom edges of the two elements. If bottomSpace is an integer, it will take the exact value. And if bottomSpace = [0, 20], implies bottom edge of element2 lies below bottom edge of element1. To force sahi to check for the bottomSpace between the two elements, use the bottomSpace. If nothing provided it wouldn't consider bottomSpace.
$leftSpaceinteger array|integer optionalSpace between left edges of the two elements. If leftSpace is an integer, it will take the exact value. And if leftSpace = [0, 20], implies top edge of element2 lies to the right side of left edge of element1. To force sahi to check for the leftSpace between the two elements, use the leftSpace. If nothing provided it wouldn't consider leftSpace.
$messagestring optional Message to be written to logs if the assertion fails

Returns
null

Details

_assertVisiblyOn checks if element1 placed on element2. element1 may extend beyond element2 boundaries. If element1 is visibly placed on element2, assertion passes. If element1 is not visibly placed on element2, the failure messasge will be displayed in logs as failure.
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 _isVisiblyOn instead.
Example
_assertVisiblyOn(_div("item1"), _div("item2"), [0,25]); //implies _div("item1") is placed on _div("item2") where top edge of div("item1") can be upto
// 25 units below div("item2") top edge


_assertFitsWidth

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.3.0NANA8.0.0NANA

Available for modes: Browser | Windows | Java

_assertFitsWidth($element1, $element2[, $leftSpace[, $rightSpace[, $message]]])

Arguments
$element1HTML DOM element First element to be asserted.
$element2HTML DOM element Second element to be asserted. Base Element.
$leftSpaceinteger array|integer optionalSpace between left edges of the two elements. If leftSpace is an integer, it will take the exact value. And if leftSpace = [0, 20], implies top edge of element2 lies to the right side of left edge of element1. If nothing provided leftSpace will be considered as 0.
$rightSpaceinteger array|integer optionalSpace between right edges of the two elements. If rightSpace is an integer, it will take the exact value. And if rightSpace = [0, 20], implies right edge of element2 lies to the right side of right edge of element1. If nothing provided rightSpace will be considered as 0.
$messagestring optional Message to be written to logs if the assertion fails

Returns
null

Details

_assertFitsWidth checks if element1 fits within the width of element2. If element1 fits within element2, assertion passes. If element1 does not fits within element2, the failure messasge will be displayed in logs as failure.
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 _fitsWidth instead.
Example
_assertFitsWidth(_div("item1"), _div("item2"), [0,25], [-25,0]);  //implies _div("item1") is  on _div("item2") where left edge of div("item1") can be
//upto 25 units right to div("item2") left edge and right edge of div("item1") can be upto 25 units left to div("item2") right edge


_assertFitsHeight

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-OnSAP Add-On
6.3.0NANA8.0.0NANA

Available for modes: Browser | Windows | Java

_assertFitsHeight($element1, $element2[, $topSpace[, $bottomSpace[, $message]]])

Arguments
$element1HTML DOM element First element to be asserted.
$element2HTML DOM element Second element to be asserted. Base Element.
$topSpaceinteger array|integer optionalSpace between top edges of the two elements. If topSpace is an integer, it will take the exact value. And if topSpace = [-20, 0], implies top edge of element2 lies above top edge of element1. If nothing provided topSpace will be considered as 0.
$bottomSpaceinteger array|integer optionalSpace between bottom edges of the two elements. If bottomSpace is an integer, it will take the exact value. And if bottomSpace = [0, 20], implies bottom edge of element2 lies below bottom edge of element1. If nothing provided bottomSpace will be considered as 0.
$messagestring optional Message to be written to logs if the assertion fails

Returns
null

Details

_assertFitsHeight checks if element1 fits within the height of element2. If element1 fits within element2, assertion passes. If element1 does not fits within element2, the failure messasge will be displayed in logs as failure.
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 _fitsHeight instead.
Example
_assertFitsHeight(_div("item1"), _div("item2"), [0,25], [-25,0]);  //implies _div("item1") is  on _div("item2") where top edge of div("item1") can be
//upto 25 units below div("item2") top edge and bottom edge of div("item1") can be upto 25 units above div("item2") bottom edge