Mobile Modules

The folder TBox XEngines->Mobile in the Standard subset contains Modules that perform specific tasks for the Mobile Engine 3.0.

Android Snackbar

The Module Android Snackbar allows you to steer snackbar in Android applications.

It has the following ModuleAttributes:

ModuleAttribute

Description

Text

Specify the text that appears on the snackbar.

Action

If the snackbar contains a button, specify the action you want to perform on it.

In this example, you perform the following actions:

  • You open the mobile application with the Module Open Mobile App.

  • You click on the button Show SnackBar With Delay, which triggers the snackbar.

  • You use ActionMode WaitOn to wait until the snackbar with the text message Speed changes everything appears.

  • You verify whether the message is Speed changes everything.

  • You click the button on the snackbar to close it.

Android Snackbar Module in a TestCase

Click On Screen

This Module allows you to perform a tap gesture on a certain point of the mobile device screen.

It has the following ModuleAttributes:

ModuleAttribute

Description

X

Specify the x-coordinate in percent. The leftmost value is 0 and the rightmost value is 100.

Y

Specify y-coordinate in percent. The top value is 0 and the bottom value is 100.

In this example, you perform a tap gesture at 10% of the x-coordinate and at 50% of the y-coordinate from the top left corner of the screen.

Click on Screen Module in a TestCase

Download File from Mobile Device

The Module Download File from Mobile Device allows you to download a file from an Android device to a computer (see chapter "Transfer files to Android").

If the file already exists on the computer, the Mobile Engine 3.0 overwrites it.

It has the following ModuleAttributes:

ModuleAttribute

Description

Mobile Device Path

Specify the full path to the file that you want to upload, including the file name and extension.

Use forward slashes (/) in the path.

Example: /sdcard/Download/abc.pdf

On Samsung devices, replace Internal Storage with sdcard in the file path. For example, replace /Internal storage/Download/abc.txt with /sdcard/Download/abc.txt.

Desktop Path

Specify the full path to the location where you want to save the file, including the file name and extension.

Example: D:\abc.pdf

You can specify a different name for your file.

In this example, you download the file example.png from your Android device to your computer.

Download File from Mobile Device Module in a TestCase

Draw On Screen

The Module Draw On Screen allows you to draw a shape directly on the screen.

The Module has the following ModuleAttributes:

ModuleAttribute

Description

Long Tap

Specify whether you want to start the drawing with a tap or a long tap.

Possible values are:

  • True: start with a long tap.

  • False: start with a tap.

Duration

Specify the duration of the movement in milliseconds.

A higher value makes the movement slower and shorter. A lower value makes the movement faster and longer.

This ModuleAttribute is optional. The default value is 300 ms.

Point->X

Specify the start x-coordinate in percent. The leftmost value is 0 and the rightmost value is 100.

Point->Y

Specify the start y-coordinate in percent. The top value is 0 and the bottom value is 100.

In this example, you draw a simple shape with three swipe movements. Each movement lasts one second.

Draw On Screen Module in a TestCase

End Appium Session

The Module End Appium Session allows you to end the current Appium session.

In this example, you perform the following actions:

  • You start a new Appium session and open the URL http://sampleapp.tricentis.com/101/app.php.

  • You interact with the mobile controls on the screen.

  • In the End Appium Session TestStep, you use the Module End Appium Session to end your current Appium session.

  • You start a new Appium session and interact with the same screen.

End Appium Session Module in a TestCase

Execute Driver Script

The Execute Driver Script Module allows you to bundle many commands from a JavaScript and execute them all at once on the Appium server. The Appium server executes this code in the current session and returns all the values specified in the script. For more information on writing the JavaScript code, see the Appium documentation execute-driver-plugin (opens in new tab) and WebdriverIO (opens in new tab).

This Module works for devices connected via Tricentis Mobile Agent and Tricentis Device Cloud.

The Module has the following ModuleAttributes:

ModuleAttribute

Description

Driver Script from File

Specify the name of the JavaScript file stored on the device running Tosca.

You must specify either a Driver Script from File or an Inline Driver Script value.

Inline Driver Script

Enter the driver script as TestStepValue.

You must specify either a Driver Script from File or an Inline Driver Script value.

Result

Returns all the values specified by the script.

In this example, you verify if the driver script returns the property username with the value testuser1.

Execute Driver Script Module in a TestCase

Get Appium Session Id

The Module Get Appium Session Id allows you to save the Appium session ID to a buffer.

The Module has the following ModuleAttribute:

ModuleAttribute

Description

Buffer Name

Specify the name of the buffer to which you want to save the ID of your current Appium session.

In this example, you save the Appium session ID to a buffer named SampleBuffer.

Get Appium Session Id Module in a TestCase

ME3.0 Hardware Button Operations

The Module ME3.0 Hardware Button Operations allows you to steer the following platform-specific hardware buttons:

  • Home button for iOS and Android

  • Back button on Android

  • App Selection button on Android

It has the following ModuleAttribute:

ModuleAttribute

Description

Button

Specify which button you want to click. Possible values are:

  • Home

  • Back

  • ApplicationSelector

In this example, you press the Back button on Android.

ME 3.0 Hardware Button Operations Module in a TestCase

ME3.0 Set Device Orientation

The Module ME3.0 Set Device Orientation allows you to define whether the Mobile Engine 3.0 should steer your device in portrait or landscape orientation.

It has the following ModuleAttribute:

ModuleAttribute

Description

Orientation

Specify the orientation of your device and use ActionMode Select. The following values are available:

  • Portrait

  • Landscape

In the example below, you set the screen orientation to Landscape.

ME3.0 Set Device Orientation Module in a TestCase

Open Mobile App

The Open Mobile App Module allows you to open native and hybrid mobile applications on your Android or iOS device.

This step is a mandatory first TestStep in Mobile Engine 3.0 TestCases. The only exception is if you want to set Desired Capabilities.

For more information on the Open Mobile App Module, see Open mobile applications.

The Module has the following ModuleAttributes:

ModuleAttribute

Description

Application

For Android devices and emulators, specify the full path or PackageName and Activity of the application you want to steer. Separate the PackageName from the Activity with a forward slash (/). However, we recommend that you use the AppPackage and AppActivity ModuleAttributes.

For iOS devices and simulators, specify the full path or BundleID of the application you want to steer. However, we recommend that you use the BundleID ModuleAttribute.

BundleID

For iOS devices and simulators, specify the BundleID of the application you want to steer.

AppPackage

For Android devices and emulators, specify the PackageName of the application you want to steer.

AppActivity

For Android devices and emulators, specify the Activity of the application you want to steer.

Application Path

For devices connected to Tricentis Mobile Agent, specify the full path of the application you want to steer.

In this example, you open the mobile application with the Open Mobile App Module by specifying the PackageName and the Activity of the application you want to steer.

Open Mobile App Module in a TestCase

If you want to open a native or hybrid app, use the Module OpenURL from the Standard subset.

When you upgrade Tricentis Tosca 12.3 or any earlier versions to 2023.2 LTS, you have to perform an XEngines migration to ensure that the Open Mobile App Module works correctly. To do so, right-click on the project root element and select XEngines Migration->Update project to current version.

Send Text Input To Focused Control

The Module Send Text Input To Focused Control allows you to send text input to a focused control to simulate user action.

The Module has the following ModuleAttribute:

ModuleAttribute

Description

Text

Specify the text input that you want to send to a focused control.

In this example, you send text input to a dynamic search field.

  • The Focused Control TestStep sets the focus on the dynamic search field.

  • The next TestStep uses the Send Text Input To Focused Control Module to send text input to the search field.

  • After the search, a drop-down list appears with results that match your search query. The Destination Airport TestStep selects the correct result from the drop-down list.

Send Text Input To Focused Control Module in a TestCase

Set Autohide Keyboard

The Module Set Autohide Keyboard allows you to disable the auto-hide mode for keyboards in native applications. This impacts the performance of steering text boxes (see chapter "Disable the keyboard auto-hide on iOS").

The Module has the following ModuleAttribute:

ModuleAttribute

Description

Autohide Keyboard

Specify whether you want to enable the auto-hide mode of the iOS onscreen keyboard.

Possible values are:

  • True: enable auto-hide mode.

  • False: disable auto-hide mode.

In this example, you disable the default auto-hide mode of the onscreen iOS keyboard.

Set Autohide Keyboard Module in a TestCase

Set Desired Capabilities

Desired Capabilities allow you to indicate important parameters. These parameters tell the Appium Server how you want your test sessions to behave. For more information on using Desired Capabilities in your tests, see chapter "Set Desired Capabilities".

The Module Set Desired Capabilities allows you to apply Desired Capabilities to your test execution. It has to be the first TestStep of your TestCase (see chapter "Set Desired Capabilities for test execution").

The Module has the following ModuleAttribute:

ModuleAttribute

Description

Capability

Specify which Desired Capability you want to apply:

Names and values are case-sensitive.

In this example, you apply the Desired Capabilities skipServerInstallation and skipDeviceInitialization to reduce the startup time of Android test execution.

Set Desired Capabilities Module in a TestCase

Set iOS biometrics enrollment

The Module Set iOS biometrics enrollment allows you to enable or disable FaceID or TouchID user authentication on your iOS simulator.

The Module has the following ModuleAttribute:

ModuleAttribute

Description

State

Enable or disable the biometrics enrollment on your iOS simulator.

Possible values are:

  • True: enable biometrics enrollment.

  • False: disable biometrics enrollment.

In this example, you perform the following actions:

  • You open the mobile application with the Module Open Mobile App.

  • You enable biometric authentication on your iOS simulator. In the TestStep Set iOS biometrics enrollment, you set the ModuleAttribute State to True.

  • In the Click the Login button TestStep, you click a button which triggers an action that requires user authentication.

  • In the TestStep Use iOS biometric authentication, you set the type of user authentication to TouchID.

  • To trigger positive authentication, you set the TestStepValue Positive authentication to True.

Set iOS biometrics enrollment Module and Use iOS biometric authentication Module in a TestCase

Swipe On Screen

The Module Swipe On Screen allows you to perform a swipe operation directly on the screen. The length of the swipe movement is equal to one third of the mobile screen size.

The Module has the following ModuleAttributes:

ModuleAttribute

Description

Direction

Specify which type of swipe you want to perform. Possible values are:

  • SWIPELEFT

  • SWIPERIGHT

  • SWIPEUP

  • SWIPEDOWN

  • SWIPE to perform a swipe towards a defined End Point

Duration

Specify the duration of the swipe in milliseconds.

A higher value makes the swipe slower and shorter. A lower value makes the swipe faster and longer.

The default value is 300 ms.

Start Point

Define the start coordinates of the swipe.

By default, the swipe starts at the center of the screen.

You can specify different coordinates. If you specify one coordinate, you also have to enter a value for the other.

Start Point->X

Specify the start x-coordinate in percent. The leftmost value is 0 and the rightmost value is 100.

Start Point->Y

Specify the start y-coordinate in percent. The top value is 0 and the bottom value is 100.

End Point

Define the end coordinates of the swipe.

If you enter end coordinates, set the Direction to SWIPE.

If you specify one coordinate, you also have to enter a value for the other.

End Point->X

Specify the end x-coordinate in percent. The leftmost value is 0 and the rightmost value is 100.

End Point->Y

Specify the end y-coordinate in percent. The top value is 0 and the bottom value is 100.

In this example, you perform an upward swipe that lasts 1 second.

Swipe On Screen Module in a TestCase

Switch Mobile App

The Module Switch Mobile App allows you to switch to a different mobile application during a single TestCase.

The Module has the following ModuleAttribute:

ModuleAttribute

Description

Application

Specify the application to which you want to switch:

  • For an iOS application, use its BundleID.

  • For an Android application, use its PackageName. Don't specify the Activity.

In this example, you perform the following actions:

  • You open the first mobile application with the Module Open Mobile App.

  • You click on a screen position in the first application.

  • You switch to the second mobile application with the Module Switch Mobile App.

  • You click on a screen position in the second mobile application.

Switch Mobile App Module in a TestCase

Upload File to Mobile Device

The Module Upload File to Mobile Device allows you to upload a file from a computer to an Android device (see chapter "Transfer files to Android"). The file upload limit is 2 GB.

If the file already exists on the Android device, the Mobile Engine 3.0 overwrites it.

It has the following ModuleAttributes:

ModuleAttribute

Description

Desktop Path

Specify the full path to the file that you want to upload, including the file name and extension.

Example: D:\abc.pdf

Mobile Device Path

Specify the full path to the location where you want to save the file, including the file name and extension.

Use forward slashes (/) in the path.

Example: /sdcard/Download/abc.pdf

You can specify a different name for your file.

On Samsung devices, replace Internal Storage with sdcard in the file path. For example, replace /Internal storage/Download/abc.txt with /sdcard/Download/abc.txt.

Use Android fingerprint authentication

The Module Use Android fingerprint authentication allows you to use fingerprint authentication on your Android emulator.

To use this Module in your TestCase, you have to configure fingerprint ID(s) on your Android emulator first.

The Module has the following ModuleAttribute:

ModuleAttribute

Description

FingerprintId

Enter the fingerprint ID that you configured on your emulator and want to use for user authentication.

In this example, you perform the following actions:

  • You open the mobile application with the Module Open Mobile App.

  • In the Click the Login button TestStep, you click a button that requires user authentication.

  • In the TestStep Use Android fingerprint authentication, you specify the fingerprint ID. If you have set the same ID on your emulator, the authentication is positive. Consequently, the TestStep passes.

Use Android fingerprint authentication Module in a TestCase

Use iOS biometric authentication

The Module Use iOS biometric authentication allows you to use FaceID or TouchID user authentication on your iOS simulator.

To use this Module, you have to enable biometrics enrollment on your iOS simulator. To do so, use the Module Set iOS biometrics enrollment.

The Module has the following ModuleAttributes:

ModuleAttribute

Description

Type of biometric authentication

Specify what type of biometric authentication you want to use.

Possible values are:

  • FaceID: use face authentication.

  • TouchID: use fingerprint authentication.

Positive authentication

Specify whether the authentication is positive or negative.

Possible values are:

  • True: use positive authentication.

  • False: use negative authentication.

In this example, you perform the following actions:

  • You open the mobile application with the Module Open Mobile App.

  • You enable biometric authentication on your iOS simulator. In the TestStep Set iOS biometrics enrollment, you set the ModuleAttribute State to True.

  • In the Click the Login button TestStep, you click a button which triggers an action that requires user authentication.

  • In the TestStep Use iOS biometric authentication, you set the type of user authentication to TouchID.

  • To trigger positive authentication, you set the TestStepValue Positive authentication to True.

Set iOS biometrics enrollment Module and Use iOS biometric authentication Module in a TestCase