bdd-maestro

Convert Gherkin .feature files into Maestro 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

npm install -g @shiftposts/bdd-maestro

Quick Start

# 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.

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:

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:

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:

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

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