# Core

> Desktop apps on macOS, Windows and Linux, used as people use them, through the operating system's accessibility tree: what screen readers read. Axx starts the app as it ships, with no build for testing, and clicks and types with the pointer and the keyboard, as a person does.

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

Desktop apps on macOS, Windows and Linux, used as people use them, through the operating system's accessibility tree: what screen readers read. Axx starts the app as it ships, with no build for testing, and clicks and types with the pointer and the keyboard, as a person does.

An app is registered for each OS it runs on, by that OS's pack (`desktop-macos`, `desktop-windows`, `desktop-linux`), and every other step is `app-core`'s: a feature lists the app once for each OS and runs unchanged on each. This pack adds what only desktops do: a key pressed, a click at a place on a control, a drag.

**Each scenario has the desktop, and a clean app.** A desktop has one screen, one pointer and one keyboard focus, so on macOS and Windows desktop scenarios take the machine's desktop in turns (other runs on the machine wait too), while other scenarios run alongside them; on Linux, Axx runs desktops of its own. Before an app starts in a scenario, its home (a folder of the project's `.axx/desktop`) is emptied, and what its OS keeps of it elsewhere is reset; after the scenario, the app and every process it started are stopped. An app's files are a folder of the files pack whose `owner` is the app: `./` is where its OS keeps an app's data, `~/` its home.

**Screenshots** are of the app's front window, as it draws itself, one for each platform and display scale (`arrivals.darwin@2x.png`). A focused field's text cursor is left out of them, as the web pack leaves it out of its screenshots: it blinks.

Add it to a project with `axx pack add desktop-core`; it builds on [`app-core`](https://axx.nimbusxr.us/references/packs/app-core/), which comes with it.

## Settings

In `axx.yaml`, under `packs.desktop-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.platforms` | The platforms whose screenshots the project keeps: each compares its own; elsewhere the steps pass without comparing (default: every platform). | a list of `linux`, `darwin`, `windows` | |
| `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/desktop/traces: a page with its window after each step, and its controls where the scenario failed. | `failed`, `always`, `never` | `never` |
| `videos` | Which scenarios keep a video of their desktop in .axx/desktop/videos, an MP4 file (H.264), and the run one of them all, run.mp4. OpenH264 Video Codec provided by Cisco Systems, Inc.: Axx downloads it from Cisco when a video is first kept; never turns it off. | `failed`, `always`, `never` | `never` |

## Steps

### `desktop-core.key`

```gherkin
When the {word} key is pressed in the {word} app
```

Press a key, with the keys held with it, in the app's focused window: `Enter`, `Escape`, `Tab`, `Control+Shift+S`, as the web pack names them. `ControlOrMeta+Z` is Command on macOS and Control elsewhere, so a feature runs unchanged on each OS.

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

**Example:**

```gherkin
When the Escape key is pressed in the depot app
When the ControlOrMeta+S key is pressed in the depot app
```

_Since 0.2.0._

### `desktop-core.click-at`

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

Click at a place on a control, in points from its top left, for what an app draws rather than names: a signature pad, a map, a canvas.

| 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` |
| `{int}` | a whole number |  | `200`, `3` |

**Example:**

```gherkin
When the "Courier signature" element in the depot app is clicked at 40, 40
```

_Since 0.2.0._

### `desktop-core.click-at-anchor`

```gherkin
When the {string} {control} in the {word} app is clicked at {int}, {int} from its {anchor}
```

Click at a place on a control, in points from its middle or a corner, for what keeps its place there as the control grows with the window or the screen: a picture an app shows in its middle, a button in its bottom right corner. Places run right and down, so one left of or above the point is negative.

| 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` |
| `{int}` | a whole number |  | `200`, `3` |
| `{anchor}` | the point of a control that places on it are measured from: its `middle`, or a corner. Places run right and down from it, so one left of or above it is negative | `middle`, `top left`, `top right`, `bottom left`, `bottom right` | `middle`, `bottom right` |

**Example:**

```gherkin
When the "Courier signature" element in the depot app is clicked at -40, -20 from its bottom right
```

_Since 0.2.2._

### `desktop-core.drag`

```gherkin
When the pointer is dragged from {int}, {int} to {int}, {int} on the {string} {control} in the {word} app
```

Press the pointer at a place on a control, move it to another in steps, as a hand does, and release it there; places are in points from the control's top left.

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{int}` | a whole number |  | `200`, `3` |
| `{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 pointer is dragged from 40, 30 to 140, 30 on the "Courier signature" element in the depot app
```

_Since 0.2.0._

### `desktop-core.drag-from-anchor`

```gherkin
When the pointer is dragged from {int}, {int} to {int}, {int} from the {anchor} of the {string} {control} in the {word} app
```

Drag on a control as a hand does, with places in points from its middle or a corner, for what keeps its place there as the control grows with the window or the screen. Places run right and down, so one left of or above the point is negative.

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{int}` | a whole number |  | `200`, `3` |
| `{anchor}` | the point of a control that places on it are measured from: its `middle`, or a corner. Places run right and down from it, so one left of or above it is negative | `middle`, `top left`, `top right`, `bottom left`, `bottom right` | `middle`, `bottom right` |
| `{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 pointer is dragged from -60, 0 to 60, 0 from the middle of the "Courier signature" element in the depot app
```

_Since 0.2.2._

## Parameter types

| Parameter | Takes | Values | For example |
|---|---|---|---|
| `{anchor}` | the point of a control that places on it are measured from: its `middle`, or a corner. Places run right and down from it, so one left of or above it is negative | `middle`, `top left`, `top right`, `bottom left`, `bottom right` | `middle`, `bottom right` |