Sahi Pro - 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 Pro: 3.5
Since Sahi OS: 2

_assert($condition[, $message])

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

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 Pro: 3.5
Since Sahi OS: 2

_assertTrue($condition[, $message])

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

Details

Same as _assert

_assertNotTrue

Since Sahi Pro: 3.5
Since Sahi OS: 2

_assertNotTrue($condition[, $message])

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

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 Pro: 3.5
Since Sahi OS: 2

_assertFalse($condition[, $message])

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

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 Pro: 3.5
Since Sahi OS: 2

_assertNull($value[, $message])

Arguments
$valueanything Anything to be checked for null
$messagestring optionalmessage to log if value is not 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 Pro: 3.5
Since Sahi OS: 2

_assertNotNull($value[, $message])

Arguments
$valueanything Anything to be checked for not null
$messagestring optionalmessage to log if value is 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 Pro: 3.5
Since Sahi OS: 2

_assertExists($element[, $message])

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

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

_assertVisible($element[, $message])

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

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

_assertNotVisible($element[, $message])

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

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 Pro: 3.5
Since Sahi OS: 2

_assertNotExists($element[, $message])

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

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 Pro: 3.5
Since Sahi OS: 2

_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

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 Pro: 3.5
Since Sahi OS: 3

_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

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 Pro: 3.5
Since Sahi OS: 2

_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

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 Pro: 3.5
Since Sahi OS: 2

_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

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 Pro: 3.5
Since Sahi OS: 3

_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

Details

_assertContainsText will do nothing if the expected string/regex is not part of the text content of given element
_assertContainsText 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 Pro: 6.0.0
Since Sahi OS: NA

_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

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