Maests

2.8.6 verified Fri May 01 auth: no javascript

Maests (v2.8.6) is a TypeScript executable compiler that transforms TypeScript flows into Maestro-compatible YAML for mobile end-to-end testing. It supports modular flow composition, automatic .env loading, type-safe runScript, and direct YAML output. Active development with frequent releases (weekly/monthly). Differentiator: TypeScript-first, composable modules, and runScript type safety versus plain YAML or maestro-ts.

Common errors

error Error: Cannot find module 'maests' ↓

cause maests is installed as a dev dependency but not in node_modules

fix

Run pnpm install or npm install, ensure maests is in package.json devDependencies

error TypeError: M.initFlow is not a function ↓

cause Importing M incorrectly (default import instead of named import)

fix

Use import { M } from 'maests'

error Error: Maestro not found. Please install Maestro CLI ↓

cause Maestro CLI not installed or not on PATH

fix

Install Maestro CLI from https://maestro.mobile.dev/getting-started/installing-maestro

Warnings

breaking Version 2.0 dropped support for older Maestro versions (<1.20) ↓

fix Update Maestro to >=1.20

gotcha runScript callbacks must be functions, not arrow functions if using 'this' ↓

fix Use regular function expressions for callbacks that reference 'this'

gotcha Environment variables from .env are loaded only once at start; changing .env during test won't be reflected ↓

fix Restart maests after modifying .env

deprecated Older M.xxx syncing methods like M.tapOnText will be removed in v3 ↓

fix Use M.tapOn({ text: '...' }) instead

Install

npm install maests

yarn add maests

pnpm add maests

Imports

wrong

import M from 'maests' || const M = require('maests')

correct

import { M } from 'maests'

Named export only; M is not a default export. ESM/CJS compatible.

getOutput

wrong

import { getOutput } from 'maests/commands' || require('maests').getOutput

correct

import { getOutput } from 'maests'

Named export from top-level package.

M.initFlow

wrong

initFlow({ appId: '...' })

correct

M.initFlow({ appId: 'com.example.app' })

Must call as method on M object, not standalone.

Quickstart

Basic usage: initialize a flow with appId, tap an element, and assert visibility.

// First, install: pnpm add -D maests
// Create my-test.ts:
import { M, getOutput } from 'maests';
M.initFlow({ appId: 'com.example.app' });
M.tapOn('welcome_button');
M.assertVisible({ id: 'welcome_label' });
// Run: npx maests my-test.ts