Core

Native mobile apps, used as people use them: launched, or opened with a deep link straight at the screen a scenario tests; their controls tapped and filled, found by the names people see; what they show checked, waiting as apps take their time.

The steps every app takes, on a phone or a desktop, are app-core‘s, which this pack carries out for phones; its own are the steps of phones alone: deep links, the background, swipes, the system’s dialogs and notifications. The apps are registered, and run, by the platform packs: mobile-android (Android emulators and devices) and, later, mobile-ios. They drive the apps through the platforms’ own drivers: the UiAutomator2 server on Android, which Axx runs itself, and WebDriverAgent on iOS, through Appium; Axx downloads them on first use. Each scenario has a device to itself, and a clean app: the platform pack leases a device for the scenario and resets the app, and what it can see, before the scenario starts. Every step names its app, so a scenario can drive two, and use a web app too.

Controls are found by the name people see: a button’s text, a field’s label, a list item’s text. When no name tells a control apart, id= (the Android resource ID or the iOS accessibility identifier) or xpath= finds it.

Add it to a project with axx pack add mobile-core; it builds on app-core, which comes with it.

Settings

In axx.yaml, under packs.mobile-core:

Setting	Takes	Values	Default
screenshots.folder	The folder of the apps’ screenshots, in the project. Unset, each feature keeps its screenshots in a screenshots folder next to its file.	text
screenshots.tolerance	The share of a screenshot’s pixels that may differ.	a number, 0 to 1	0
screenshots.update	Take every screenshot again, as the app looks now, instead of comparing.	true, false
traces	Which scenarios keep a trace of each app in .axx/mobile/traces: its screen after each step, and its controls where it failed.	failed, always, never	never
videos	Which scenarios keep a video in .axx/mobile/videos: their phones as they ran, each touch drawn, with their steps beside them.	failed, always, never	never

Steps

mobile-core.link

When the {word} app is opened with the {string} link

Open a link in the app, as tapping it in another app would: a deep link jumps straight to the screen a scenario tests. The app is launched first when it is not running.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Example:

When the courier app is opened with the "parcels-courier://deliveries/PX-MOB-9401" link

Since 0.1.5.

mobile-core.background

When the {word} app is sent to the background

Send the app to the background, as switching to another app does.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the courier app is sent to the background

Since 0.1.5.

mobile-core.foreground

When the {word} app is brought back

Bring the app back to the front from the background, where it left off.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the courier app is brought back

Since 0.1.5.

mobile-core.swipe

When the {word} app is swiped {direction}

Swipe across the screen: down, from the top, refreshes a list that pulls to refresh; left and right page through what pages.

Parameter	Takes	Values	For example
{word}	one word, with no spaces		parcels, PX-4101
{direction}	where a swipe goes, as the finger moves (down from the top pulls a list to refresh); or which way a phone moves or turns in the scene its camera sees, where it also moves forward and back	up, down, left, right, forward, back	down, left

Example:

When the courier app is swiped down

Since 0.1.5.

mobile-core.dialog.accepted

When the {word} app's dialog is accepted

Answer the dialog the system shows over the app, like a request for a permission: accepted allows, dismissed does not. It waits for the dialog. A dialog of the app’s own is part of its screen: tap its buttons.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the courier app's dialog is accepted

Since 0.1.5.

mobile-core.dialog.dismissed

When the {word} app's dialog is dismissed

Answer the dialog the system shows over the app, like a request for a permission: accepted allows, dismissed does not. It waits for the dialog. A dialog of the app’s own is part of its screen: tap its buttons.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the courier app's dialog is dismissed

Since 0.1.5.

mobile-core.dialog.shows

Then [[within {duration} ]]the {word} app's dialog shows {string}

Check the text of the dialog the system shows over the app: it waits for the dialog (10 seconds, or within).

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {word} app's dialog shows {string}
• within {duration} the {word} app's dialog shows {string}

Example:

Then the courier app's dialog shows "send you notifications"

Since 0.1.5.

mobile-core.camera-sees

Given the {word} app's camera sees {filepath}

The app’s camera sees a 3D scene, a glTF file (.glb or .gltf), or an image (PNG or JPEG, and HEIC on iOS) or a video (MP4 or MOV; H.264 on Android), as the phone held upright sees it: Axx plays the camera of an iOS simulator, which has none, and of an Android emulator it starts, and, from a scene, the app’s AR. A scene’s camera is where the phone is, which the phone’s steps move; the app’s AR finds the scene’s surfaces and objects where they are. A video plays in a loop. A running app starts again, to see it.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{filepath}	a file of the project: a path relative to the feature file’s directory, the resources directories or axx.yaml’s directory (looked for in that order), or an absolute path, quoted when it has a space	seeds/parcels.yaml, kafka/scan-delivered.json

Example:

Given the courier app's camera sees scenes/parcel-on-porch.glb
Given the courier app's camera sees labels/label-PX-IOS-9621.png

Since 0.1.5.

mobile-core.phone-to-camera

When the {word} app's phone moves to the scene's {string} camera

Put the phone where one of the scene’s cameras is, looking the way it looks: a place the scene names, with a camera there. The app’s camera sees the scene from there.

Parameter	Takes	For example
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Example:

When the courier app's phone moves to the scene's "crouched beside the parcel" camera

Since 0.1.5.

mobile-core.phone-path

When the {word} app's phone {travel} the scene's {string} path[[ at {speed}]]

Carry the phone along one of the scene’s paths: an animation that moves a camera (the phone’s, or another the phone follows), as it was recorded. With no speed, the phone keeps to the animation’s own times; at 2x goes twice as fast; at 1.4 m/s keeps one speed along the way. travels waits for the phone to arrive; starts traveling lets the scenario go on while it moves, and a later step waits for it to reach the end. The phone stays where the path ends.

Parameter	Takes	Values	For example
{word}	one word, with no spaces		parcels, PX-4101
{travel}	whether the step waits for the phone to arrive (travels), or lets the scenario go on while it moves (starts traveling)	travels, starts traveling	travels, starts traveling
{string}	text in double or single quotes, which the step leaves out		"Get a quote", 'Express'
{speed}	how fast a phone travels: 25 mph, 40 km/h or 11 m/s; or, for a GPX file with times, how many times its own pace: 4x		25 mph, 40 km/h

Variants, the parts in [[...]] said or left out:

• the {word} app's phone {travel} the scene's {string} path
• the {word} app's phone {travel} the scene's {string} path at {speed}

Example:

When the courier app's phone travels the scene's "up the garden path" path
When the courier app's phone starts traveling the scene's "up the garden path" path at 2x

Since 0.1.5.

mobile-core.phone-move

When the {word} app's phone moves {float} m {direction}

Step with the phone, as the person holding it steps, still facing the same way, at a walking pace: forward and back along the ground the way the phone looks, left and right across it, up and down.

Parameter	Takes	Values	For example
{word}	one word, with no spaces		parcels, PX-4101
{float}	a decimal number		2.5, 0.1
{direction}	where a swipe goes, as the finger moves (down from the top pulls a list to refresh); or which way a phone moves or turns in the scene its camera sees, where it also moves forward and back	up, down, left, right, forward, back	down, left

Example:

When the courier app's phone moves 1.5 m right

Since 0.1.5.

mobile-core.phone-turn

When the {word} app's phone turns {int} degrees {direction}

Turn the phone where it stands, as the person holding it turns: left and right about the upright, keeping its tilt; up and down, tilting it.

Parameter	Takes	Values	For example
{word}	one word, with no spaces		parcels, PX-4101
{int}	a whole number		200, 3
{direction}	where a swipe goes, as the finger moves (down from the top pulls a list to refresh); or which way a phone moves or turns in the scene its camera sees, where it also moves forward and back	up, down, left, right, forward, back	down, left

Example:

When the courier app's phone turns 90 degrees left

Since 0.1.5.

mobile-core.camera-tap

When the {string} in the {word} app's camera view is tapped

Tap what the app’s camera shows, by its name in the scene the camera sees: the tap lands where the object shows on the screen (its middle, or where the scene’s _tap point for it says), as a finger would.

Parameter	Takes	For example
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the "left end of the parcel" in the courier app's camera view is tapped

Since 0.1.5.

mobile-core.notification

Then [[within {duration} ]]the {word} app shows a notification {string}

Check that the device shows a notification with a text, in its title or its text: it opens the notifications (Android’s notification shade, iOS’s Notification Center), looks, and closes them. It waits for the notification (10 seconds, or within).

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'

Variants, the parts in [[...]] said or left out:

• the {word} app shows a notification {string}
• within {duration} the {word} app shows a notification {string}

Example:

Then the courier app shows a notification "PX-MOB-9401 delivered"

Since 0.1.5.

mobile-core.notification-action

When the {string} action of the {string} notification is tapped in the {word} app

Tap one of a notification’s actions, the notification found by a text in its title or its text: on Android a button under it (opened out first, if it is not), on iOS in the menu a long press shows. It waits for the notification (10 seconds). The notification itself, as a person opens it, is tapped with the "PX-MOB-9401 delivered" notification is tapped in the courier app.

Parameter	Takes	For example
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the "Next delivery" action of the "PX-MOB-9401 delivered" notification is tapped in the courier app

Since 0.1.5.

mobile-core.background-task

When the {string} background task is run in the {word} app

Have the phone run one of the app’s background tasks now, as it does when the task’s time comes: the app’s own code runs, in the app, and does what it does then (a sync, a reminder). Axx only moves the moment: the app must have scheduled the task (Axx waits up to 15 seconds for it to, as an app does a moment after it launches), and on Android the conditions it set (a network, say) still apply. The task is named as the app names it: on Android, its WorkManager work’s unique name or one of its tags (each is tagged with its worker’s class); on iOS, its identifier (BGTaskSchedulerPermittedIdentifiers). The step waits for the task to be done: on iOS, until the app says so, in the 30 seconds iOS gives a task; on Android, until the work ends.

Parameter	Takes	For example
{string}	text in double or single quotes, which the step leaves out	"Get a quote", 'Express'
{word}	one word, with no spaces	parcels, PX-4101

Example:

When the "round-reminder" background task is run in the courier app
When the "example.parcels.courier.round-reminder" background task is run in the courier app

Since 0.1.5.

mobile-core.travel-through

When the {word} app's phone {travel} at {speed} through:
  | latitude | longitude |

The table may start with the row naming its columns, as above, or go straight to its rows.

Move the phone along a route, as its GPS reports a person walking or driving it: from the first point of the table to the last, each a latitude and a longitude, at a steady speed. The app sees where the phone is, how fast it moves and which way. travels waits for the phone to arrive; starts traveling lets the scenario go on while it moves, and a later step waits for it to reach the end. The phone stays at the last point.

Parameter	Takes	Values	For example
{word}	one word, with no spaces		parcels, PX-4101
{travel}	whether the step waits for the phone to arrive (travels), or lets the scenario go on while it moves (starts traveling)	travels, starts traveling	travels, starts traveling
{speed}	how fast a phone travels: 25 mph, 40 km/h or 11 m/s; or, for a GPX file with times, how many times its own pace: 4x		25 mph, 40 km/h

A row is a point the route goes through, in order.

Example:

When the courier app's phone travels at 30 km/h through:
  | 51.3397 | 12.3731 |
  | 51.3397 | 12.3760 |

Since 0.1.5.

mobile-core.travel-route

When the {word} app's phone {travel} the {filepath} route[[ at {speed}]]

Move the phone along a GPX file’s route, as its GPS reports it: its track, else its route, else its waypoints. With no speed, the phone keeps to the file’s own times; at 4x goes four times as fast; at 25 mph keeps one speed throughout. travels waits for the phone to arrive; starts traveling lets the scenario go on while it moves.

Parameter	Takes	Values	For example
{word}	one word, with no spaces		parcels, PX-4101
{travel}	whether the step waits for the phone to arrive (travels), or lets the scenario go on while it moves (starts traveling)	travels, starts traveling	travels, starts traveling
{filepath}	a file of the project: a path relative to the feature file’s directory, the resources directories or axx.yaml’s directory (looked for in that order), or an absolute path, quoted when it has a space		seeds/parcels.yaml, kafka/scan-delivered.json
{speed}	how fast a phone travels: 25 mph, 40 km/h or 11 m/s; or, for a GPX file with times, how many times its own pace: 4x		25 mph, 40 km/h

Variants, the parts in [[...]] said or left out:

• the {word} app's phone {travel} the {filepath} route
• the {word} app's phone {travel} the {filepath} route at {speed}

Example:

When the courier app's phone travels the routes/grimmaische-strasse.gpx route
When the courier app's phone starts traveling the routes/grimmaische-strasse.gpx route at 4x

Since 0.1.5.

mobile-core.route-end

Then [[within {duration} ]]the {word} app's phone reaches the end of its route

Wait for the phone a starts traveling step set off to arrive at the last point of its route, or the end of the scene’s path it travels (the route’s own time and 10 seconds, or within).

Parameter	Takes	For example
{duration}	a duration in seconds (s) or minutes (m)	5s, 2m
{word}	one word, with no spaces	parcels, PX-4101

Variants, the parts in [[...]] said or left out:

• the {word} app's phone reaches the end of its route
• within {duration} the {word} app's phone reaches the end of its route

Example:

Then within 2m the courier app's phone reaches the end of its route

Since 0.1.5.

Parameter types

Parameter	Takes	Values	For example
{direction}	where a swipe goes, as the finger moves (down from the top pulls a list to refresh); or which way a phone moves or turns in the scene its camera sees, where it also moves forward and back	up, down, left, right, forward, back	down, left, forward
{speed}	how fast a phone travels: 25 mph, 40 km/h or 11 m/s; or, for a GPX file with times, how many times its own pace: 4x		25 mph, 40 km/h, 4x
{travel}	whether the step waits for the phone to arrive (travels), or lets the scenario go on while it moves (starts traveling)	travels, starts traveling	travels, starts traveling