npm package: @shiftposts/bdd-maestro
Description: Convert Gherkin .feature files into Maestro YAML flow files for mobile testing
Latest version: 0.2.1

# bdd-maestro

Convert Gherkin `.feature` files into [Maestro](https://maestro.mobile.dev/) YAML flow files for mobile testing.

Write your tests in plain English using Gherkin syntax, and bdd-maestro generates the Maestro flows to run them. Built-in step definitions cover common mobile testing operations out of the box — no custom code required for most scenarios.

## Install

```bash
npm install -g @shiftposts/bdd-maestro
```

## Quick Start

```bash
# Scaffold a project with example files
bdd-maestro init

# Generate Maestro flows
bdd-maestro generate
```

The `init` command creates:

- `bdd-maestro.config.yaml` — configuration
- `features/login.feature` — example feature file
- `steps/custom.yaml` — place for custom step definitions
- `maestro/flows/` — output directory

## Writing Features

Write standard Gherkin feature files. Built-in step definitions handle the mapping to Maestro commands automatically.

```gherkin
Feature: Login
  @smoke
  Scenario: Successful login
    Given the app is running
    When I tap on "Login"
    And I enter "admin" into "Username"
    And I enter "password123" into "Password"
    And I tap on "Submit"
    Then I should see "Dashboard"
```

Running `bdd-maestro generate` produces:

```yaml
appId: com.example.myapp
tags:
  - smoke
---
- launchApp
- tapOn: Login
- tapOn: Username
- inputText: admin
- tapOn: Password
- inputText: password123
- tapOn: Submit
- assertVisible: Dashboard
```

## Configuration

`bdd-maestro.config.yaml` in your project root:

```yaml
appId: "com.example.myapp"        # Maestro appId (optional)
features:
  - "features/**/*.feature"       # Glob patterns for feature files
steps:
  - "steps/**/*.yaml"             # Glob patterns for custom step definitions
outputDir: "maestro/flows"        # Where to write generated flows
useDefaultProviders: true         # Load built-in step definitions
```

All fields are optional. Defaults are shown above (except `appId`).

## CLI

### `bdd-maestro generate`

Parse all feature files and write Maestro YAML flows to the output directory. Reports any unmatched steps with file and line context.

### `bdd-maestro watch`

Same as `generate`, then watches feature and step files for changes and regenerates automatically.

### `bdd-maestro init`

Scaffold a config file and example files in the current directory.

## Built-in Steps

### Tap

| Gherkin step | Maestro command |
| --- | --- |
| `I tap on {element}` | `tapOn` |
| `I tap {element}` | `tapOn` |
| `I double tap on {element}` | `doubleTapOn` |
| `I double tap {element}` | `doubleTapOn` |
| `I long press on {element}` | `longPressOn` |
| `I long press {element}` | `longPressOn` |

### Text Input

| Gherkin step | Maestro command |
| --- | --- |
| `I enter {text} into {field}` | `tapOn` field, then `inputText` |
| `I type {text} into {field}` | `tapOn` field, then `inputText` |
| `I enter {text}` | `inputText` |
| `I type {text}` | `inputText` |
| `I clear the text` | `eraseText` |
| `I erase {count} characters` | `eraseText` |
| `I hide the keyboard` | `hideKeyboard` |

### Assertions

| Gherkin step | Maestro command |
| --- | --- |
| `I should see {element}` | `assertVisible` |
| `I can see {element}` | `assertVisible` |
| `{element} is visible` | `assertVisible` |
| `I should not see {element}` | `assertNotVisible` |
| `{element} is not visible` | `assertNotVisible` |

### Navigation

| Gherkin step | Maestro command |
| --- | --- |
| `I go back` | `back` |
| `I press back` | `back` |
| `I navigate back` | `back` |
| `I open the link {url}` | `openLink` |
| `I take a screenshot` | `takeScreenshot` |
| `I take a screenshot named {name}` | `takeScreenshot` |

### Scroll & Swipe

| Gherkin step | Maestro command |
| --- | --- |
| `I scroll down` | `scroll` |
| `I scroll up` | `scroll` (direction: UP) |
| `I scroll down until I see {element}` | `scrollUntilVisible` |
| `I scroll up until I see {element}` | `scrollUntilVisible` |
| `I swipe left` | `swipe` (direction: LEFT) |
| `I swipe right` | `swipe` (direction: RIGHT) |
| `I swipe up` | `swipe` (direction: UP) |
| `I swipe down` | `swipe` (direction: DOWN) |

### App Lifecycle

| Gherkin step | Maestro command |
| --- | --- |
| `the app is running` | `launchApp` |
| `I launch the app` | `launchApp` |
| `I stop the app` | `stopApp` |
| `I close the app` | `stopApp` |

### Device

| Gherkin step | Maestro command |
| --- | --- |
| `I wait for animations to finish` | `waitForAnimationToEnd` |
| `animations have finished` | `waitForAnimationToEnd` |
| `I wait {seconds} seconds` | `waitForAnimationToEnd` (with timeout) |

## Custom Step Definitions

Create YAML files in your steps directory to add new patterns or override built-in ones:

```yaml
steps:
  - pattern: "I log in as {role}"
    maestro:
      - tapOn: "Login"
      - tapOn: "Role"
      - inputText: "{role}"
      - tapOn: "Submit"
```

Placeholders use `{name}` syntax. Values in quotes in the Gherkin step (e.g. `"admin"`) are captured without the quotes.

Custom step definitions are loaded after built-in providers, so they take priority when patterns overlap.

## Gherkin Features

- **Scenario** — generates one Maestro flow file
- **Scenario Outline + Examples** — generates one flow per examples row
- **Background** — steps prepended to every scenario in the feature
- **Tags** — preserved as Maestro flow tags (`@smoke` becomes `tags: [smoke]`)
- **Given/When/Then/And/But** — keywords are stripped before matching

## Programmatic API

```typescript
import { generate, writeFlows, loadConfig } from "@shiftposts/bdd-maestro";

const config = loadConfig();
const result = await generate(config);
const files = writeFlows(result.flows, config.outputDir);
```

## License

MIT