Script actions - Smartphone specific actions – kapptivate

Enable / disable airplane mode

As a reminder, all helpers can be used as follows:

browser.helper_name
driver.helper_name

browser and driver are alias

The following helpers may be used:

isAirplaneModeEnabled() :
No parameters
Returns true or false depending on the airplane mode state on the smartphone.
Only valid for Android phones at the moment (returns an error Not implemented for iOS if run on an iOS phone.
enableAirplaneMode({ pause, selectorStrategy, airplaneSwitchXPATH, airplaneLabelRegex, forceNativeAttempt }) :
No action performed if the airplane mode is already activated (or if run on iOS phones).
Calls the toggleAirplaneMode helper using the same parameters (see below).
disableAirplaneMode({ pause, selectorStrategy, airplaneSwitchXPATH, airplaneLabelRegex, forceNativeAttempt }) :
No action performed if the airplane mode is already deactivated (or if run on iOS phones).
Calls the toggleAirplaneMode helper using the same parameters (see below).
toggleAirplaneMode({ pause, selectorStrategy, airplaneSwitchXPATH, airplaneLabelRegex, forceNativeAttempt }) :
Depending on Android version :
If Android <7 :=":">
Switches airplane mode without going through the interface
If Android = 7 :
Switches airplane mode going through the interface
Pauses the script after the switch to leave additional time to the phone before performing any other action.
Triggers the error "Airplane mode should be enabled" if the airplane mode is already deactivated before running the action and remains deactivated after running it (if the airplane mode has been switched through the interface).
(See parameters below)</7>

Usage

browser.enableAirplaneMode()
browser.disableAirplaneMode()

Parameters

All the parameters of helpers enableAirplaneMode, disableAirplaneMode, and toggleAirplaneMode are optional:

Name	Type	Details
pause	Number(ms)	A pause after the switch is done, to allow some time before the phone does any other action
selectorStrategy	Number	A constant that can be either: selectorStrategy.TEXT : Uses an approach based on the airplane mode label text from the smartphone parameters. Reads airplaneLabelRegex (or its default value) and builds an xpath on the following model: //[matches(@text,airplaneLabelRegex,"i")])* selectorStrategy.XPATH : Uses an approach based on a full xpath of the airplane mode switch from the smartphone parameters. Reads airplaneSwitchXPATH (or its default value) selectorStrategy.ALL : Combines all the available approaches. Tries the text approach, then the xpath approach and keep doing so until one of them is successful in the allowed timeframe
airplaneSwitchXPATH	String	Full xpath of the airplane mode switch from the smartphone parameters. Default value: //[contains(@resource-id,"com.android.settings:id/switch_widget")]*
airplaneLabelRegex	String	A regex that represents all possible values of the label located net to the airplane mode switch from the smartphone parameters. On a few smartphones, clicking on the switch itself via a script is not possible, but clicking on the label is. Default value: avion\|airplane French and English language are supported (as long as "avion" or "airplane" are part of the label).
forceNativeAttempt	Boolean	Allows to choose forcing an attempt via the default approach, even when using Android = 7. In theory, this would just increase the delay to perform the action, as the default approach should fail, and it would then perform the approach through the interface. Default value: false

Examples

Enable

Here is an example of airplane mode enabling :

describe('Airplane mode', function () {

    it(`Enable airplane mode`, function () {
        browser.enableAirplaneMode();
    });

});

This will result in enabling the airplane mode, if it is not enabled yet

Disable

Here is an example of airplane mode disabling:

describe('Airplane mode', function () {

    it(`Disable airplane mode`, function () {
        browser.disableAirplaneMode();
    });

});

This will result in disabling the airplane mode, if it is not disabled yet

Listen for smartphone events

You can "listen" for occurrences of some events on iOS and Android smartphones and perform actions as they occur. Note that, at the time of writing, you MUST "wait" for an event to occur as well, for the event to be caught. That means you have to call the addEventListener described in this section, and then the waitForEvent function from the "Wait for smartphone events" section below.

Usage

driver.addEventListener(callback, expectedEvent)

Parameters

Name	Type	Details
callback	function	The callback to execute. It takes the event as a parameter.
expectedEvent optional	Event	The event to wait for. Must be one of the events listed below in the "Events" section. If empty, all events will be listened on.

Examples

Assuming the following events occurred in that order :

IncomingCallEvent ;

SwitchTechnologyCellularEvent ;

ActiveCallEvent.

All events

Here is an example of listening to all events :

describe('My suite', function () {
  it('Step 1', function () {
    driver.addEventListener((event) = { console.log("Received an event", event)})
    driver.waitForEvent(new ActiveCallEvent())
  });
});

This will result in prints of all three events.

Only a given kind of events

Here is an example of listening to all cellular events :

describe('My suite', function () {
  it('Step 1', function () {
    driver.addEventListener((event) = { console.log("Received a cellular event", event)}, new CellularEvent())
    driver.waitForEvent(new ActiveCallEvent())
  });
});

This will result in prints of only IncomingCallEvent and ActiveCallEvent, as SwitchTechnologyCellularEvent is not a CellularEvent.

Only a specific event

Here is an example of listening to only the ActiveCallEvent event :

describe('My suite', function () {
  it('Step 1', function () {
    driver.addEventListener((event) = { console.log("Received a active call event", event)}, new ActiveCallEvent())
    driver.waitForEvent(new ActiveCallEvent())
  });
});

This will result in a print of only ActiveCallEvent, as the two others are different events.

Wait for smartphone events

You can "wait" for the occurrence of a given event on iOS and Android smartphones. The script will only continue if an instance occurs, and will fail otherwise.

Usage

driver.waitForEvent(expectedEvent, { timeout, timeoutMsg, interval, requestTimeout })

Parameters

Name	Type	Details
expectedEvent	Event	The event to wait for. Must be one of the events listed below in the Events section.
timeout optional	Number	Timeout in ms (default: 5000).
timeoutMsg optional	string	Error message to throw when waitForEvent times out.
interval optional	Number	Interval between condition checks (default: 500).
requestTimeout optional	Number	Timeout in ms for each individual underlying request made to get events (default: 2000).

Examples

Assuming the following events occurred in that order :

SwitchTechnologyCellularEvent ;

IncomingCallEvent ;

ActiveCallEvent.

Only a given kind of events

Here is an example of waiting for the occurrence of any of the cellular events :

describe('My suite', function () {
  it('Step 1', function () {
    driver.waitForEvent(new CellularEvent())
  });
});

This will result in waiting through the SwitchTechnologyCellularEvent and resuming only after the IncomingCallEvent event occurs.

Only a specific event

Here is an example of listening to only the ActiveCallEvent event :

describe('My suite', function () {
  it('Step 1', function () {
    driver.waitForEvent(new ActiveCallEvent())
  });
});

This will result in waiting through the SwitchTechnologyCellularEvent and IncomingCallEvent event, resuming only after the ActiveCallEvent event occurs.

Events

Every event has the following properties :

kind : the kind of the event (e.g.: CALL, CELLULAR, etc.) ;

name : the name of the event (e.g.: RING, SWITCH_TECHNOLOGY, etc.) ;

time : the time at which the event occurred.

Common Android & iOS events

CellularEvent :
- SwitchTechnologyCellularEvent (iOS only) : the phone switched its cellular access technology ;

CallEvent :
- IncomingCallEvent
- ActiveCallEvent

Android specific events

CallEvent :
- IdleCallEvent
- RingCallEvent
- ComposeCallEvent
- FailedCallEvent

AudioFocusEvent :
- GainAudioFocusEvent : an app took control of the phone's audio output ;
- HandoffAudioFocusEvent

SMSEvent :
- ReceivedSMSEvent

AirplaneModeEvent :
- EnabledAirplaneModeEvent
- DisabledAirplaneModeEvent

BatteryEvent

BrowserPackageEvent

PhoneStateEvent
- EmergencyOnlyPhoneStateEvent
- InServicePhoneStateEvent
- OutOfServicePhoneStateEvent
- PowerOffPhoneStateEvent

RotationEvent :
- Rotation0RotationEvent
- Rotation90RotationEvent
- Rotation180RotationEvent
- Rotation270RotationEvent

iOS specific events

CallEvent :

- MissingCallEvent
- DisconnectCallEvent
- OutgoingCallEvent

Specific example: OTP code reception by SMS

You may use kapptivate to check the SMS reception of an OTP code on your Android or iOS phones using the events mentioned in the previous paragraph.

Prerequisite: your robot must be up to date.

You may refer to this video to help you with the configuration.

Android usage

On Android phones, you need to add the following parts in your script.

Before the first "it" of your script, you need to declare an additional variable:

  let promise;

At the step of the script that triggers the OTP, you need to add (inside the "it" of the corresponding step):

        promise = driver.waitForEvent(new ReceivedSMSEvent(), {
            timeout: 45000,
            timeoutMsg: "sms not received",
        })

You may modify the timeout duration (45s in this case) and the error message in case no SMS is received.

After that step, and before the next step on your app, you need to add a new step:

    it(`Get OTP sms`, async function() {
        const {event, allEvents} = await promise;
        const regex = /This is your OTP code: (\d{4})/gm;
        const smsBody = _.get(event, 'payload.body', '');
        let m = regex.exec(smsBody);
        let otp = m[1];
        console.log(m[1]); //This is the OTP code that has been received
    });
 
    it(`Input OTP code`, function () {
        elem = $(`//*[contains(@long-clickable,"true")]`);
        elem.setValue(otp);
    });

You will need to customize the regex according to the message you are expecting to receive. You may use this website to help you build it.

The OTP code will be extracted from the SMS using the regex you mentioned and will be stored in m[1] if it is needed for the next steps.

Example

In this example, we are waiting a SMS starting with "Votre code d autorisation est" for 60 seconds after we select "VALIDER" on the app:

   it(`Click on "VALIDER"`, function () {
        elem = $(`//*[contains(@text,"VALIDER")]`);
        elem.click();
        promise = driver.waitForEvent(new ReceivedSMSEvent(), {
            timeout: 60000,
            timeoutMsg: "sms not received",
        })
    });
    
    it(`Get OTP sms`, async function() {
        const {event, allEvents} = await promise;
        console.log(event);
        const regex = /Votre code d autorisation est (\d{4})/gm;
        const smsBody = _.get(event, 'payload.body', '');
        let m = regex.exec(smsBody);
        let otp = m[1];
        console.log(m[1]);
    });

    it(`Assert that "code OTP a été envoyé" exists after 40000ms`, function () {
        elem = $(`//*[contains(@text,"code OTP a été envoyé")]`);
        elem.waitForExist(40000);
    });

    it(`Input OTP code`, function () {
        elem = $(`//*[contains(@long-clickable,"true")]`);
        elem.setValue(otp);
    });

iOS usage

On iOS phones, you need to add the following parts in your script.

Before the first "it" of your script, you need to declare an additional variable:

  let sms_code;

After the step that triggers the SMS, and before the next step on your app, you need to add a new step:

    it("Wait for OTP sms", function(){
        elem = $('//*[contains(@name,"NotificationShortLookView")]')
        elem.waitForExist({timeout: 35000, interval: 50})
        let smsBody = elem.getText()
        const regex = /(\d{4})/gm;
        let m = regex.exec(smsBody)
        if (m != null){
            sms_code = m[0]
        }
    })

You may modify the timeout duration (35s in this case).

You will need to customize the regex according to the message you are expecting to receive. You may use this website to help you build it.

The OTP code will be extracted from the SMS using the regex you mentioned and will be stored in variable m if it is needed for the next steps.

Example

In this example, we are entering a PIN, wait for the OTP code sent by SMS and then enter the OTP code:

    it(`Enter pin`, function(){
        const pin = "12345"
        _.forEach(pin, (keyToPress, index) ={
            elem = $(`(//XCUIElementTypeSecureTextField)[${index+1}]`);
            elem.click();
            elem.setValue(keyToPress)
        })
    })
    
    it("Wait for OTP sms", function(){
        elem = $('//*[contains(@name,"NotificationShortLookView")]')
        elem.waitForExist({timeout: 35000, interval: 50})
        let smsBody = elem.getText()
        console.log(smsBody)
        const regex = /(\d{4})/gm;
        let m = regex.exec(smsBody)
        if (m != null){
            console.log(m)
            sms_code = m[0]
        }
    })
    
    it("Enter OTP code", function(){
        _.forEach(sms_code, (keyToPress, index)={
            elem = $(`(//XCUIElementTypeTextField)[${index+1}]`);
            elem.click();
            elem.setValue(keyToPress)
        })
    })

Manipulate calls

Place a call

To call another device :

driver.placeCall("0123456789", {"timeout_ring_call": 30, "timeout_wait_compose": 30, "sound_filename": "file-0m30s", "debug": false});

This command returns an object with various call metrics:

{
    "dial_time": 1.454,
    "ring_time": 0.454,
    "call_time": 43.532
}

The first parameter is the phone number to call and is mandatory.

The following options are available in the object passed as second parameter :

timeout_wait_compose : how long to wait (at most) for the call to be initiated after the number is dialed (in seconds) ;

timeout_ring_call : how long to wait (at most) for the other device to answer (in seconds) ;

sound_filename : audio file to play to the other device once it has answered. We offer various files with different durations : file-0m30s, file-1m, file-1m30s, file-2m, file-2m30s, and file-3m ;

debug : print additional information in the result (mostly used for debugging) ;

Warning : placeCall will throw an error if any of the timeout options is exceeded.

Wait a call

To wait a call from another device :

driver.waitCall({"timeout_incoming_call": 90, "timeout_end_call": 300, "timeout_pickup_call": 20, "debug": false, "mos_activate": true, "mos_listening_condition": "NB", "mos_ref_file": "file-0m30s", mos_algo: "polqa"});

This command return an object with calculated time:

{
    "incoming_time": 1.454,
    "pickup_time": 4.39,
    "call_time": 43.532
}

The following options are available in the object passed as second parameter :

timeout_incoming_call : how long to wait (at most) for the call to be received (in seconds) ;

timeout_end_call : how long to wait (at most) for the call to end (in seconds) ;

timeout_pickup_call : how long to wait (at most) for the call to become "active" once picked up (in seconds) ;

debug : print additional information in the result (mostly used for debugging) ;

enable_mos : will activate mos after record is ended;

mos_listening_condition : value possible is NB (voice over 2G, 3G) or SWB (VoLTE);

mos_ref_file : audio file to use for reference. We offer various files with different durations : voice-30s, voice-1m, file-0m30s, file-1m, file-1m30s, file-2m, file-2m30s, and file-3m ;

mos_algo: mos algorithm for use to compute mos. Possible value are polqa (need license), visqol, aqua ;

Warning : waitCall will throw an error if any of the timeout options is exceeded.

Manipulate sound

Play sound

To play sound on device :

Using the "Play Sound" action will block the smartphone during the execution of action

driver.playSound({"sound_filename": "file-0m30s"});

The following options are available in the object passed as first parameter :

sound_filename : audio file to play to the other device once it has answered. We offer various files with different durations : voice-30s, voice-1m, file-0m30s, file-1m, file-1m30s, file-2m, file-2m30s, and file-3m ;

Warning : playSound will throw an error if sound couldn't be played on device

Record sound

To start record sound on device :

driver.startRecordSound({mos_activate: true, mos_listening_condition: "NB", mos_ref_file: "file-0m30s", mos_algo: "polqa"});

The following options are available in the object passed as first parameter :

mos_activate : will activate mos after record is ended;

mos_listening_condition : value possible is NB (voice over 2G, 3G) or SWB (VoLTE);

mos_ref_file : audio file to use for reference. We offer various files with different durations : voice-30s, voice-1m, file-0m30s, file-1m, file-1m30s, file-2m, file-2m30s, and file-3m ;

mos_algo: mos algorithm for use to compute mos. Possible value are polqa (need license), visqol, aqua ;

Warning : startRecordSound this command is asynchrone;

To stop record sound on device :

driver.stopRecordSound();

Warning : stopRecordSound will stop previously startRecordSound command and wait record end