maests/README.md

An executable compiler for creating Maestro's yaml-flows with typescript.

# A TypeScript-based solution inspired by [maestro-ts](https://github.com/johkade/maestro-ts) for writing and running Maestro flows in a modular and reusable way.

## ✅ Features

- You can write Maestro flows in TypeScript and execute directly.
- Break down Flow into smaller, reusable modules
- Automatically load environment variables from .env
- Handling runScript with type.

## 🚀 Getting Started

### Requirement

If you have not installed maestro yet, you have to [install](https://maestro.mobile.dev/getting-started/installing-maestro) it at first.

### Installation

```sh:
pnpm -D add maests
```

### Step 1: Create your first flow

Create a new file \<flow-name>.ts:

```typescript
import { M } from "maests";

M.initFlow({ appId: "com.myTeam.myApp" });
M.tapOn("someTestId");
```

### Step 2: Execute Test

```sh
npx maests my-first-flow.ts
```

## 🛹 Playground

There is sample flow you can try actually in [playground](playground)

`sample-flow.ts`

```typescript
import { getOutput, M } from "maests";
import { openApp } from "@/e2e/utils/openApp";
import { someScript } from "./utils/script";

// use composable flow easiliy
openApp();

// run script like this
M.runScript(someScript);

// use variables set in someScript
M.assertVisible({ id: getOutput("id") });

// use runFlow to run some flow with condition
M.runFlow({
  flow: () => {
    M.repeatWhileNotVisible(
      {
        text: "4",
      },
      () => {
        M.tapOnText("Increment");
      }
    );
  },
  condition: {
    visible: "Increment",
  },
});
```

You can try maests by this sample flow with simulator in [playground](playground)

```shell
# clone this repo
git clone https://github.com/shoma-mano/maests
cd maests

# build maests
pnpm install
pnpm build

# try maests in playground
cd playground
pnpm install
pnpm test
```

## 🛠️ Commands

This package offers a rich set of commands to cover various actions in your flows, including initializing flows, performing taps and presses, swiping, asserting conditions, and more.

For a detailed list of all commands with examples, refer to the [Commands Documentation](./commands.md).

## 🚨 Trouble Shooting

Most of the issues are caused by Maestro itself rather than this library. But you can still check the YAML files that are generated by maests in the "maests" folder.

## ⭐️ Contributing

This package is currently under active development, and we welcome contributions from everyone!