Android APIs

This page lists the APIs specific to Android. These APIs have an _a prefix in camel case, example: _aPressBack.

These APIs will work only on an Android device/emulator.

Action APIs

_aWakeUp

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aWakeUp()

Arguments
None

Returns
null

Details

_aWakeUp simulates pressing the power button if the screen is OFF else it does nothing if the screen is already ON.


_aPressBack

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aPressBack()

Arguments
None

Returns
null

Details

_aPressBack Performs a Back action.


_aPressRecentApps

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aPressRecentApps()

Arguments
None

Returns
null

Details

_aPressRecentApps Brings up the Recent Apps screen.


_aPressSearch

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aPressSearch()

Arguments
None

Returns
null

Details

_aPressSearch Brings up the Search box.


_aPressMenu

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aPressMenu()

Arguments
None

Returns
null

Details

_aPressMenu Simulates a press on the MENU button.


_aPressEnter

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aPressEnter()

Arguments
None

Returns
null

Details

_aPressEnter Simulates a press on the ENTER key.


_aPressDelete

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aPressDelete()

Arguments
None

Returns
null

Details

_aPressDelete Simulates a press on the DELETE key.


Fetch APIs

_aIsScreenOn

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aIsScreenOn()

Arguments
None

Returns
booleantrue or false based based on screen is ON or OFF.

Details

Returns true or false based on screen is ON or OFF.
var $screenOn = _aIsScreenOn();


Implicit scroll APIs for element identification

In Android, only visible elements can be interacted with. Thus if a scroll view has elements that do not lie on the screen, these elements cannot be interacted with, unless they are scrolled into view. In a scroll view that can contain different numbers of elements at different times, the user will first have to determine how much to scroll. To save the user this trouble, Sahi provides APIs that automatically perform the scrolling to identify the element.
info By default, scrolling is disabled.

_aEnableVerticalScroll

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aEnableVerticalScroll([$element[, $maxScrollCount]])

Arguments
$elementAndroid Element optional Scrollable element in which subsequent elements will be searched. If not specified, top most scrollable element will be considered.
$maxScrollCountinteger optional Specify maximum scroll count to attempt scrolling to identify an element. If not specified, it will perform the scrolling till the end.

Returns
null

Details

Enables automatic vertical scrolling and disables horizontal scrolling for element identification. This affects all subsequent steps in the script. To turn it off, call _aDisableScrolling().

Once _aEnableVerticalScroll has been called, an element is identified as follows.
  • When an element is identified, if an _in clause is specified, it will be identified in that container. Else it will be identified in the topmost container.
  • If the element is visible on the page, it will be identified.
  • Else, if the container is scrollable, it will be scrolled vertically from the beginning till the element is identified. If the end has been reached, it means that the element has not been found.
  • Else, if the container is not scrollable but contains a scrollable child container, the child container will be scrolled vertically from the beginning till the element is identified. If the end has been reached, it means that the element has not been found.
info NOTE: Scrollable element as first parameter is supported from Sahi Pro Mobile Add-On 8.0.0


_aEnableHorizontalScroll

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aEnableHorizontalScroll([$element[, $maxScrollCount]])

Arguments
$elementAndroid Element optional Scrollable element in which subsequent elements will be searched. If not specified, top most scrollable element will be considered.
$maxScrollCountinteger optional Specify maximum scroll count to attempt scrolling to identify an element. If not specified, it will perform the scrolling till the end.

Returns
null

Details

Enables automatic horizontal scrolling and disables vertical scrolling for element identification. This affects all subsequent steps in the script. To turn it off, call _aDisableScrolling().

Once _aEnableHorizontalScroll has been called, an element is identified as follows.
  • When an element is identified, if an _in clause is specified, it will be identified in that container. Else it will be identified in the topmost container.
  • If the element is visible on the page, it will be identified.
  • Else, if the container is scrollable, it will be scrolled horizontally from the beginning till the element is identified. If the end has been reached, it means that the element has not been found.
  • Else, if the container is not scrollable but contains a scrollable child container, the child container will be scrolled horizontally from the beginning till the element is identified. If the end has been reached, it means that the element has not been found.
info NOTE: Scrollable element as first parameter is supported from Sahi Pro Mobile Add-On 8.0.0


_aDisableScroll

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aDisableScroll()

Arguments
None

Returns
null

Details

Disables automatic horizontal and vertical scrolling for element identification. This affects all subsequent steps in the script.

Once _aDisableScroll has been called, an element is identified as follows.
  • When an element is identified, if an _in clause is specified, it will be identified in that container. Else it will be identified in the topmost container.
  • If the element is visible on the page, it will be identified. Else it means that the element has not been found.
info NOTES:
  • Use _aEnableVerticalScroll() and _aEnableHorizontalScroll() ONLY when required, as this affects performance. After the step(s) that require scrolling for element identification, disable automatic scrolling by calling _aDisableScroll().
  • As mentioned before, automatic scrolling is disabled by default.

_aIsVerticalScrollEnabled

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aIsVerticalScrollEnabled()

Arguments
None

Returns
booleantrue or false based on vertical scrolling is enabled or not.

Details

Returns true if automatic vertical scrolling has been enabled by calling _aEnableVerticalScroll().
var $enabled = _aIsVerticalScrollEnabled();


_aIsHorizontalScrollEnabled

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aIsHorizontalScrollEnabled()

Arguments
None

Returns
booleantrue or false based on horizontal scrolling is enabled or not.

Details

Returns true if automatic horizontal scrolling has been enabled by calling _aEnableHorizontalScroll().
var $enabled = _aIsHorizontalScrollEnabled();


_aIsScrollEnabled

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aIsScrollEnabled()

Arguments
None

Returns
booleantrue or false based on vertical/horizontal scrolling is enabled or not.

Details

Returns true if automatic horizontal or vertical scrolling has been enabled by calling _aEnableVerticalScroll() or _aEnableHorizontalScroll().
var $enabled = _aIsScrollEnabled();


Explicit scroll APIs

info These APIs should be used in usecases like _count, _collectAttributes, _collect etc. For element identification, consider using Implicit Scroll APIs instead.

_aScrollLeftMost

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aScrollLeftMost($element[, $maxSwipes])

Arguments
$elementAndroid Element element to be scrolled
$maxSwipesinteger optionalmaximum swipes to attempt to scroll to the leftmost position. If not specified, the default max swipes as supported by the device will be used.

Returns
booleantrue or false based based whether the element can still scroll.

Details

Scrolls the element's contents to the leftmost position, i.e. it scrolls horizontally to the beginning. Returns true or false.
_aScrollLeftMost(_mScrollView("Test"));
_aScrollLeftMost(_mScrollView("Test"), 5); //this will perform 5 swipes only


_aScrollRightMost

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aScrollRightMost($element[, $maxSwipes])

Arguments
$elementAndroid Element element to be scrolled
$maxSwipesinteger optionalmaximum swipes to attempt to scroll to the rightmost position. If not specified, the default max swipes as supported by the device will be used.

Returns
booleantrue or false based based whether the element can still scroll.

Details

Scrolls the element's contents to the rightmost position, i.e. it scrolls horizontally to the end. Returns true or false.
_aScrollRightMost(_mScrollView("Test"));
_aScrollRightMost(_mScrollView("Test"), 5); //this will perform 5 swipes only


_aScrollTopMost

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aScrollTopMost($element[, $maxSwipes])

Arguments
$elementAndroid Element element to be scrolled
$maxSwipesinteger optionalmaximum swipes to attempt to scroll to the topmost position. If not specified, the default max swipes as supported by the device will be used.

Returns
booleantrue or false based based whether the element can still scroll.

Details

Scrolls the element's contents to the topmost position, i.e. it scrolls vertically to the beginning. Returns true or false.
_aScrollTopMost(_mScrollView("Test"));
_aScrollTopMost(_mScrollView("Test"), 5); //this will perform 5 swipes only


_aScrollBottomMost

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aScrollBottomMost($element[, $maxSwipes])

Arguments
$elementAndroid Element element to be scrolled
$maxSwipesinteger optionalmaximum swipes to attempt to scroll to the bottommost position. If not specified, the default max swipes as supported by the device will be used.

Returns
booleantrue or false based based whether the element can still scroll.

Details

Scrolls the element's contents to the bottommost position, i.e. it scrolls vertically to the end. Returns true or false.
_aScrollBottomMost(_mScrollView("Test"));
_aScrollBottomMost(_mScrollView("Test"), 5); //this will perform 5 swipes only


_aScrollLeft

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aScrollLeft($element[, $percent[, $speed]])

Arguments
$elementAndroid Element element to be scrolled
$percentfloat optionalpercent to scroll the element, If not specified, a value of 1.0 will be used.
$speedinteger optionalspeed to perform scroll, If not specified, default value will be used specific to device.

Returns
booleantrue or false based based whether the element can still scroll.

Details

Scrolls the element's contents one page to the left. Returns false if content cannot be scrolled further, true otherwise.
_aScrollLeft(_mScrollView("Test"));
_aScrollLeft(_mScrollView("Test"), 0.5, 1000);


_aScrollRight

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aScrollRight($element[, $percent[, $speed]])

Arguments
$elementAndroid Element element to be scrolled
$percentfloat optionalpercent to scroll the element, If not specified, a value of 1.0 will be used.
$speedinteger optionalspeed to perform scroll, If not specified, default value will be used specific to device.

Returns
booleantrue or false based based whether the element can still scroll.

Details

Scrolls the element's contents one page to the right. Returns false if content cannot be scrolled further, true otherwise.
_aScrollRight(_mScrollView("Test"));
_aScrollRight(_mScrollView("Test"), 0.5, 1000);


_aScrollUp

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aScrollUp($element[, $percent[, $speed]])

Arguments
$elementAndroid Element element to be scrolled
$percentfloat optionalpercent to scroll the element, If not specified, a value of 1.0 will be used.
$speedinteger optionalspeed to perform scroll, If not specified, default value will be used specific to device.

Returns
booleantrue or false based based whether the element can still scroll.

Details

Scrolls the element's contents one page up. Returns false if content cannot be scrolled further, true otherwise.
_aScrollUp(_mScrollView("Test"));
_aScrollUp(_mScrollView("Test"), 0.5, 1000);


_aScrollDown

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aScrollDown($element[, $percent[, $speed]])

Arguments
$elementAndroid Element element to be scrolled
$percentfloat optionalpercent to scroll the element, If not specified, a value of 1.0 will be used.
$speedinteger optionalspeed to perform scroll, If not specified, default value will be used specific to device.

Returns
booleantrue or false based based whether the element can still scroll.

Details

Scrolls the element's contents one page down. Returns false if content cannot be scrolled further, true otherwise.
_aScrollDown(_mScrollView("Test"));
_aScrollDown(_mScrollView("Test"), 0.5, 1000);


Android Browser APIs

_launchNewMobileBrowser

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_launchNewMobileBrowser($deviceId[, $url])

Arguments
$deviceIdstring deviceId of the device on which the browser will be launched.
$urlstring optional URL to load on opening new browser instance. If URL is null, the Start URL of the script is launched.

Returns
stringBrowser instanceId. This can be passed to _selectBrowser

Details

Returns the browserInstanceId Launches a new browser instance. This instance does not share cookies with the base browser.

Once launched, steps can be directed to different browser instances via _selectBrowser

infoMode has to be set to ANDROID_BROWSER, using _setMode before calling this API.
_setMode("ANDROID_BROWSER");
// _connectDevice will return the deviceId and use that deviceId as parameter in _launchNewMobileBrowser
var $deviceId = _connectDevice();
// It will launch browser with Specified URL.
var $sessionId = _launchNewMobileBrowser($deviceId, "http://sahitest.com/demo/");
_selectBrowser($sessionId);


Android WebView APIs

_aStartWebContext

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA8.0.0

Available for modes: Android

_aStartWebContext($packageName)

Arguments
$packageNamestring application package name

Returns
null

Details

Change the execution mode to ANDROID_WEBVIEW and start the execution of the following steps as Web.
_aStartWebContext("com.sahipro.SahiTestApp");
infoSpecify the _aStopWebContext() API to stop the execution of the script in Android WebView mode.


_aStopWebContext

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA8.0.0

Available for modes: Android

_aStopWebContext()

Arguments
None

Returns
null

Details

Stop the execution of following steps in Android WebView.


Other APIs

_aSetSwipeDeadzonePercentage

Since: Sahi ProSahi OSSahi Pro StarterDesktop Add-OnMobile Add-On
NANANANA7.5.0

Available for modes: Android

_aSetSwipeDeadzonePercentage($percent)

Arguments
$percentfloat percent to set the deadzone for Swipe gesture.

Returns
null

Details

Swipes right on the element.
_aSetSwipeDeadzonePercentage(0.1);
info Some scrollviews starts from the edge of the screen, so perforing the scroll/swipe gesture it does scroll/swipe the other things. So to prevent this, use this api to set the deadzone percentage.

Note: 0.1% is enough for most of the cases.