Mavster Docs
The Mavster user manual. Each section below covers a feature area; click any page to jump straight in.
System Requirements
- System Requirements — OverviewChecklist of everything Mavster needs on your Mac before it will run a test.
- macOS permissionsMavster needs four macOS permissions — Accessibility, Automation, Screen & System Audio Recording, and Local Network. This page covers what each is for, how to grant it, and how to verify the state.
- iOS toolsMavster needs a working Xcode install with the Command Line Tools to discover and drive iOS simulators. This page covers installing them, accepting Xcode's license, and verifying everything's in order.
- Android toolsMavster needs the Android SDK with `adb` on your PATH to discover and drive Android emulators and devices. This page covers installing the SDK, getting `adb` on PATH, and verifying everything works.
- SimulatorsHow Mavster discovers iOS simulators and the most common reasons no simulators show up in the picker.
- Physical devicesSet up a physical iPhone for use with Mavster — pair it with Xcode for development and enable Automation in the device's Developer menu.
Getting Started
- Install the Mavster macOS appDownload Mavster, drag it to Applications, and grant the permissions it asks for on first launch.
- Connecting a simulator or devicePick a target in the Preview Connection panel — always visible inside a project. iOS Simulator, physical iPhone, or Android emulator. Covers the picker and the most common connection issues.
- Authoring your first testWalk through building a minimal test — drag Open Application, Visual Assert, and Tap tiles from the Toolbox, hit play, and read the result.
- Enabling Cloud SyncCloud Sync runs automatically while you're signed in. This page explains where it lives in the Mavster macOS app and how synced data shows up in the web app.
Core Concepts
- Tests, Suites, and StepsThe vocabulary that runs through the rest of the manual — what a step is, what a test is, what a suite is, and how conditional branches let one step react to the outcome of another.
- The ToolboxThe Toolbox is the palette of every interaction kind you can drag into a test. This page lists all ten kinds, what each one does in one line, and where to read more.
- Parameters & $placeholdersHow $name placeholders work — syntax, escape sequence, the fields that recognize them, and how values are supplied at run time. The mechanism behind data-driven tests and Run Test arguments.
- User-Defined Templates vs. InstancesTemplates are reusable step sequences shared across all your projects. Instances are copies you drop into a test. How edits to a template propagate to its instances, when you can override locally, and why this is different from Run Test.
- Region of InterestROI narrows the search to a specific band of the screen. What the options mean, when each one helps, and the cost / accuracy reasons to set it.
Interactions Reference
- Visual AssertPass/fail gate that verifies what's described in the question is on screen. The simplest interaction and the one that most determines whether your test catches regressions.
- TapTouch a screen element you describe in plain language. Tap one to ten times, repeat until a condition holds, AI element search, region narrowing, and Position Memory caching for speed.
- ScrollScroll a list or surface in a direction, optionally polling a "Scroll Until" condition that stops the scroll. Five directions, six speeds, region narrowing, and List Bounds Memory caching.
- DragPan or drag a draggable element. Two modes — Auto (AI-driven, describe the handle in plain language) and Hardcoded (explicit normalized coordinates).
- Built-In commandsMavster's eight built-in system commands — Go Home, Go Back, Open Application, Terminate Application, Hit Return, Clear Text, Hit Backspace, Tap to Dismiss.
- Keyboard TypeType text into the currently focused field. Supports $parameter substitution and [[random]] markers for unique-per-run values.
- WaitPause the test for a fixed number of seconds. The bluntest tool in the box — almost always worse than Wait Until.
- Wait UntilPoll the screen for up to N seconds and continue as soon as a visual condition is met. The robust alternative to Wait.
- Run TestCall another test from the same project, optionally passing arguments and overriding its run count. The composition primitive — build small tests, compose them into big tests.
- User DefinedDrop an instance of a User-Defined template into a test. Edit the embedded steps with the pencil button, set per-instance parameter values, and edits to the master template propagate to non-overridden instances.
Authoring Guide
- Drag-drop editor tourA guided tour of the test editor — Toolbox on the left, test column in the center, header chips on top. Where each piece lives and what it's for.
- Mavster CreateDescribe a test in plain English and let Mavster's AI explore your app and author the steps for you — building each test live in the tray.
- Suite managementSuites are folders for organizing tests. Multi-suite membership and three filter modes (All / By Suite / Unassigned).
- Reusing logic — Run Test vs. User-DefinedTwo ways to share a step sequence across tests. When to use Run Test (calls another test by name) and when to use User-Defined templates (embedded, editable, propagating).
- Parameterizing testsAuthor one test, run it for many inputs. How to design parameter names, where they're picked up from, and how to feed values from Run Test arguments or User-Defined instances.
- Self-healingSelf-healing lets Mavster recover from a failed step by planning and executing recovery actions. Three modes, an Ultra-tier gate, and per-step opt-in.
AI Features
- AI Segmentation modesThree modes — None, Auto, and Force Fresh — that control how Mavster's AI looks at the screen for a step. Trade off cost vs. reliability per step.
- Position MemoryPosition Memory remembers where Mavster previously found a Tap target and reuses it on the next run. Validates before reuse, falls back to a fresh search on mismatch. The biggest single speed-up for stable tests.
- Assert Memory & List Bounds MemoryTwo memory toggles — Assert Memory (Visual Assert) and List Bounds Memory (Scroll) — that reuse a recent result when the screen is unchanged instead of resolving from scratch. Both validate before reuse.
- Cost-saving playbookConcrete settings that drop the credit cost of a test without sacrificing reliability. Memory on, the cheapest segmentation mode that still works, and a checklist for auditing existing tests.
Running Tests
- Reading results & historyPer-step status indicators, the test's overall pass/fail/hard-fail outcome, and how run history shows up both in the macOS app and the web app.
- Credits & cost preflightMavster checks your credits and subscription before every test. What can block a run, what happens after, and how to top up.
- Nested tests in depthHow Run Test composes flows from smaller tests, with cycle detection, parameter substitution at call time, and run history attribution that survives nesting.
