# Core

> Apps, used as people use them, whatever they run on: launched, their controls tapped or clicked and filled, found by the names people see; what they show checked, waiting as apps take their time.

Source: https://axx.nimbusxr.us/references/packs/app-core/

Apps, used as people use them, whatever they run on: launched, their controls tapped or clicked and filled, found by the names people see; what they show checked, waiting as apps take their time.

An app is registered by the pack of the platform it runs on: `mobile-android` and `mobile-ios` for phones, `desktop-macos`, `desktop-windows` and `desktop-linux` for desktops (`the courier android app with the following properties:`, `the depot macos app with the following properties:`). Every other step names the app the same way on every platform (`the courier app`, `the depot app`), so a feature for a desktop app lists its registration for each OS and runs unchanged on each: a registration for a platform the machine cannot run does nothing there. An app runs on one platform in a scenario; two apps may run on two, and a scenario can use a web app too.

**Each scenario has a clean app:** the platform pack resets the app, and what it keeps, before the scenario starts. Controls are found by the name people see: a button's text, a field's label, a list item's or a row's text. When no name tells a control apart, `id=` or `xpath=` finds it. An app's files are a folder of the files pack whose `owner` is the app (`app:depot`).

Add it to a project with `axx pack add app-core`.

## Steps

### `app-core.launch`

```gherkin
When the {word} app is launched
```

Launch the app, reset for the scenario by its platform's pack (see the pack), or bring it to the front if it is already running.

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

**Example:**

```gherkin
When the courier app is launched
When the depot app is launched
```

_Since 0.1.5._

### `app-core.restart`

```gherkin
When the {word} app is restarted
```

Stop the app and start it again, keeping what it stored: what survives a restart, like a sign-in, is still there.

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

**Example:**

```gherkin
When the courier app is restarted
```

_Since 0.1.5._

### `app-core.tapped`

```gherkin
When the {string} {control} is tapped in the {word} app
```

Press a control, found by the name people see, or by an `id=` or `xpath=` selector: a tap on a phone, a click on a desktop. "tapped" and "clicked" are the same step: either word works on every platform.

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{string}` | text in double or single quotes, which the step leaves out |  | `"Get a quote"`, `'Express'` |
| `{control}` | a kind of control an app shows, found by the name people see: a `button` by its text, a `field` by its label, a `list item` or a `row` by one of its texts, a `menu item` in its open menu, an `element` is anything, by its text or accessibility label; a phone's `notification` is tapped, by a text in its title or its text. A kind an app's platform does not have (a phone has no menu bar) fails the step | `button`, `field`, `checkbox`, `radio button`, `switch`, `tab`, `menu`, `menu item`, `list item`, `row`, `link`, `image`, `text`, `element`, `notification` | `button`, `list item` |
| `{word}` | one word, with no spaces |  | `parcels`, `PX-4101` |

**Example:**

```gherkin
When the "Sign in" button is tapped in the courier app
When the "PX-MOB-9401" list item is tapped in the courier app
```

_Since 0.1.5._

### `app-core.clicked`

```gherkin
When the {string} {control} is clicked in the {word} app
```

Press a control, found by the name people see, or by an `id=` or `xpath=` selector: a tap on a phone, a click on a desktop. "tapped" and "clicked" are the same step: either word works on every platform.

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{string}` | text in double or single quotes, which the step leaves out |  | `"Get a quote"`, `'Express'` |
| `{control}` | a kind of control an app shows, found by the name people see: a `button` by its text, a `field` by its label, a `list item` or a `row` by one of its texts, a `menu item` in its open menu, an `element` is anything, by its text or accessibility label; a phone's `notification` is tapped, by a text in its title or its text. A kind an app's platform does not have (a phone has no menu bar) fails the step | `button`, `field`, `checkbox`, `radio button`, `switch`, `tab`, `menu`, `menu item`, `list item`, `row`, `link`, `image`, `text`, `element`, `notification` | `button`, `list item` |
| `{word}` | one word, with no spaces |  | `parcels`, `PX-4101` |

**Example:**

```gherkin
When the "Register" button is clicked in the depot app
When the "PX-DSK-4138" row is clicked in the depot app
```

_Since 0.2.0._

### `app-core.fill`

```gherkin
When the {string} field in the {word} app is filled with {string}
```

Replace what a field holds with a text, as typing it would. `${env:..}` values are secrets: masked in logs and failures.

| 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:**

```gherkin
When the "Courier ID" field in the courier app is filled with "CR-LEJ-12"
```

_Since 0.1.5._

### `app-core.scroll`

```gherkin
When the {string} {control} is scrolled into view in the {word} app
```

Scroll until a control shows: on a desktop, every area it is in, the outermost first; on a phone, the screen, down first, then up.

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{string}` | text in double or single quotes, which the step leaves out |  | `"Get a quote"`, `'Express'` |
| `{control}` | a kind of control an app shows, found by the name people see: a `button` by its text, a `field` by its label, a `list item` or a `row` by one of its texts, a `menu item` in its open menu, an `element` is anything, by its text or accessibility label; a phone's `notification` is tapped, by a text in its title or its text. A kind an app's platform does not have (a phone has no menu bar) fails the step | `button`, `field`, `checkbox`, `radio button`, `switch`, `tab`, `menu`, `menu item`, `list item`, `row`, `link`, `image`, `text`, `element`, `notification` | `button`, `list item` |
| `{word}` | one word, with no spaces |  | `parcels`, `PX-4101` |

**Example:**

```gherkin
When the "PX-MOB-9412" list item is scrolled into view in the courier app
```

_Since 0.1.5._

### `app-core.shows`

```gherkin
Then [[within {duration} ]]the {word} app shows {string}
```

Check that the app shows a text: in a control's text or label, whitespace collapsed. It waits for the text (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 {string}`
- `within {duration} the {word} app shows {string}`

**Example:**

```gherkin
Then the courier app shows "Today's deliveries"
Then within 20s the courier app shows "Delivered"
```

_Since 0.1.5._

### `app-core.hides`

```gherkin
Then [[within {duration} ]]the {word} app does not show {string}
```

Check that the app does not show a text, or no longer does: it waits for the text to go (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 does not show {string}`
- `within {duration} the {word} app does not show {string}`

**Example:**

```gherkin
Then the courier app does not show "PX-MOB-9401"
```

_Since 0.1.5._

### `app-core.control.shown`

```gherkin
Then [[within {duration} ]]the {string} {control} is shown in the {word} app
```

Check that the app shows a control: it waits for it (10 seconds, or `within`).

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) |  | `5s`, `2m` |
| `{string}` | text in double or single quotes, which the step leaves out |  | `"Get a quote"`, `'Express'` |
| `{control}` | a kind of control an app shows, found by the name people see: a `button` by its text, a `field` by its label, a `list item` or a `row` by one of its texts, a `menu item` in its open menu, an `element` is anything, by its text or accessibility label; a phone's `notification` is tapped, by a text in its title or its text. A kind an app's platform does not have (a phone has no menu bar) fails the step | `button`, `field`, `checkbox`, `radio button`, `switch`, `tab`, `menu`, `menu item`, `list item`, `row`, `link`, `image`, `text`, `element`, `notification` | `button`, `list item` |
| `{word}` | one word, with no spaces |  | `parcels`, `PX-4101` |

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

- `the {string} {control} is shown in the {word} app`
- `within {duration} the {string} {control} is shown in the {word} app`

**Example:**

```gherkin
Then the "Mark delivered" button is shown in the courier app
```

_Since 0.1.5._

### `app-core.control.enabled`

```gherkin
Then [[within {duration} ]]the {string} {control} is enabled in the {word} app
```

Check that a control can be used: it waits for it (10 seconds, or `within`).

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) |  | `5s`, `2m` |
| `{string}` | text in double or single quotes, which the step leaves out |  | `"Get a quote"`, `'Express'` |
| `{control}` | a kind of control an app shows, found by the name people see: a `button` by its text, a `field` by its label, a `list item` or a `row` by one of its texts, a `menu item` in its open menu, an `element` is anything, by its text or accessibility label; a phone's `notification` is tapped, by a text in its title or its text. A kind an app's platform does not have (a phone has no menu bar) fails the step | `button`, `field`, `checkbox`, `radio button`, `switch`, `tab`, `menu`, `menu item`, `list item`, `row`, `link`, `image`, `text`, `element`, `notification` | `button`, `list item` |
| `{word}` | one word, with no spaces |  | `parcels`, `PX-4101` |

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

- `the {string} {control} is enabled in the {word} app`
- `within {duration} the {string} {control} is enabled in the {word} app`

**Example:**

```gherkin
Then the "Sign in" button is enabled in the courier app
```

_Since 0.1.5._

### `app-core.control.disabled`

```gherkin
Then [[within {duration} ]]the {string} {control} is disabled in the {word} app
```

Check that a control is shown but cannot be used, like a button until a form is complete.

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) |  | `5s`, `2m` |
| `{string}` | text in double or single quotes, which the step leaves out |  | `"Get a quote"`, `'Express'` |
| `{control}` | a kind of control an app shows, found by the name people see: a `button` by its text, a `field` by its label, a `list item` or a `row` by one of its texts, a `menu item` in its open menu, an `element` is anything, by its text or accessibility label; a phone's `notification` is tapped, by a text in its title or its text. A kind an app's platform does not have (a phone has no menu bar) fails the step | `button`, `field`, `checkbox`, `radio button`, `switch`, `tab`, `menu`, `menu item`, `list item`, `row`, `link`, `image`, `text`, `element`, `notification` | `button`, `list item` |
| `{word}` | one word, with no spaces |  | `parcels`, `PX-4101` |

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

- `the {string} {control} is disabled in the {word} app`
- `within {duration} the {string} {control} is disabled in the {word} app`

**Example:**

```gherkin
Then the "Sign in" button is disabled in the courier app
```

_Since 0.1.5._

### `app-core.field.value`

```gherkin
Then [[within {duration} ]]the {string} field in the {word} app has the value {string}
```

Check what a field holds: it waits for the value (10 seconds, or `within`). A password field holds its dots.

| Parameter | Takes | For example |
|---|---|---|
| `{duration}` | a duration in seconds (`s`) or minutes (`m`) | `5s`, `2m` |
| `{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` |

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

- `the {string} field in the {word} app has the value {string}`
- `within {duration} the {string} field in the {word} app has the value {string}`

**Example:**

```gherkin
Then the "Courier ID" field in the courier app has the value "CR-LEJ-12"
```

_Since 0.1.5._

### `app-core.screenshot`

```gherkin
Then [[within {duration} ]]the {word} app looks like the {string} screenshot
```

Check that the app looks like its screenshot, pixel by pixel (anti-aliasing aside), once it has settled.

- Each platform draws apps its own way, so each device or desktop has its own screenshot, named after it (`delivered.android-parcels-pixel.png`); see the platform's family pack for where they are kept.
- Without one, the step takes it and fails: look at it, and keep it.
- When the app looks different, the step attaches the screenshot, the app and their difference.
- The check waits for the app to settle and look right: 10 seconds, or `within {duration}`.

| 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 looks like the {string} screenshot`
- `within {duration} the {word} app looks like the {string} screenshot`

**Example:**

```gherkin
Then the courier app looks like the "delivered" screenshot
```

_Since 0.1.5._

## Parameter types

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{control}` | a kind of control an app shows, found by the name people see: a `button` by its text, a `field` by its label, a `list item` or a `row` by one of its texts, a `menu item` in its open menu, an `element` is anything, by its text or accessibility label; a phone's `notification` is tapped, by a text in its title or its text. A kind an app's platform does not have (a phone has no menu bar) fails the step | `button`, `field`, `checkbox`, `radio button`, `switch`, `tab`, `menu`, `menu item`, `list item`, `row`, `link`, `image`, `text`, `element`, `notification` | `button`, `list item` |