Install & setup

1. Open the DMG and drag AppFlight to Applications.
2. Open the app. It’s signed and notarized by Apple, so macOS opens it without a warning.
3. The Setup Assistant opens by itself when something is missing. Each row shows OK / Missing and has a one-click fix: Xcode, the license, the iOS Simulator runtime (~8 GB), an iPhone simulator, Java 17+ and Maestro. AXe is bundled.
4. Choose your app under test: a Simulator build (.app), or an app already installed on the simulator.

Cài đặt & thiết lập

1. Mở file DMG và kéo AppFlight vào Applications.
2. Mở app. App đã được ký và notarize bởi Apple nên macOS mở luôn, không cảnh báo.
3. Setup Assistant tự mở khi thiếu thứ gì đó. Mỗi dòng báo OK / Missing kèm nút sửa một chạm: Xcode, license, iOS Simulator runtime (~8 GB), máy ảo iPhone, Java 17+ và Maestro. AXe có sẵn trong app.
4. Chọn app cần test: bản build cho Simulator (.app) hoặc app đã cài trên máy ảo.

Record your first test

1. Boot a simulator in the Devices column (or pick one that is already booted).
2. Press Record ⇧⌘R and use the app in the preview: click to tap, drag to swipe, type on your keyboard. Password fields become ${VARIABLES} automatically.
3. Press Stop. Review the steps; double-click one to edit its selector or value.
4. Press Run ⌘R. The running step is highlighted and every step turns ✓ or ✗. A failure card shows the failing step with a screenshot and logs.

Tests save automatically and appear in the sidebar. This is the YAML a short login recording produces:

Ghi bài test đầu tiên

1. Bật một máy ảo ở cột Devices (hoặc chọn máy đang chạy sẵn).
2. Bấm Record ⇧⌘R rồi dùng app trên màn hình xem trước: bấm chuột để chạm, kéo để vuốt, gõ bằng bàn phím. Ô mật khẩu tự thành ${BIẾN}.
3. Bấm Stop. Xem lại các bước; nhấp đúp một bước để sửa selector hoặc giá trị.
4. Bấm Run ⌘R. Bước đang chạy được tô sáng, mỗi bước chuyển ✓ hoặc ✗. Thẻ lỗi hiện bước bị lỗi kèm ảnh chụp và log.

Test tự lưu và hiện ở thanh bên. Đây là YAML của một lần ghi đăng nhập ngắn:

appId: com.example.app
---
- launchApp
- tapOn:
    id: "email_input"
- inputText: ${EMAIL}
- tapOn: "Sign in"
- assertVisible: "Home"

Add checks and logic

• Pick Element ⇧⌘P → click an element → Visible, Not Visible, Text Equals or Text Exists.
• Maestro matches an element’s whole text. For part of a label (“Good morning,” inside “Good morning, Anna!”) use Text Contains; for several possible texts use Text One Of.
• Flow Control → Only If / Repeat / Retry wraps the selected step, e.g. tap “No” only if the Save password popup shows up.
• Wait is a fixed delay; Wait for animations to end returns as soon as the screen is still.

Thêm kiểm tra và logic

• Pick Element ⇧⌘P → bấm vào phần tử → Visible, Not Visible, Text Equals hoặc Text Exists.
• Maestro so khớp toàn bộ chữ của phần tử. Nếu chỉ là một phần (“Good morning,” trong “Good morning, Anna!”) hãy dùng Text Contains; nhiều khả năng thì dùng Text One Of.
• Flow Control → Only If / Repeat / Retry bọc bước đang chọn, ví dụ chỉ bấm “No” khi popup lưu mật khẩu xuất hiện.
• Wait là chờ cố định; Wait for animations to end chờ tới khi màn hình đứng yên.

Record and run on a real iPhone

1. Connect over USB or the same Wi-Fi, unlock, trust the Mac and enable Developer Mode.
2. Settings → Project → Apple Team ID → pick your team.
3. Select the iPhone under DEVICES. A live view starts in ~15 s: record, pick elements and run as usual.

The first run per Maestro version builds and signs Maestro’s small test driver with your team (~2 min). Remove it any time: Device menu → Remove Test Driver. Not available on real devices (Maestro limits): Clear State, openLink, location and media.

Ghi và chạy trên iPhone thật

1. Kết nối qua USB hoặc cùng Wi-Fi, mở khoá, tin cậy máy Mac và bật Developer Mode.
2. Settings → Project → Apple Team ID → chọn team của bạn.
3. Chọn iPhone trong mục DEVICES. Màn hình trực tiếp hiện sau ~15 giây: ghi, chọn phần tử và chạy như bình thường.

Lần chạy đầu với mỗi phiên bản Maestro, app build và ký test driver nhỏ của Maestro bằng team của bạn (~2 phút). Gỡ bất cứ lúc nào: menu Device → Remove Test Driver. Không dùng được trên máy thật (giới hạn của Maestro): Clear State, openLink, vị trí và media.

Reuse a login flow, chain workflows

1. Record the shared part once as its own test, e.g. Login.
2. Drag Login from the sidebar into another test’s steps. Editing Login updates every test that uses it; export writes - runFlow: login.yaml.
3. Sidebar → Workflows: drag tests onto the board, then Run Workflow. The Run Report shows passed / failed / skipped, timings, screenshots and can be copied as Markdown.

Tái sử dụng flow đăng nhập, nối workflow

1. Ghi phần dùng chung thành một test riêng, ví dụ Login.
2. Kéo Login từ thanh bên vào danh sách bước của test khác. Sửa Login là mọi test dùng nó đều cập nhật; khi xuất sẽ ra - runFlow: login.yaml.
3. Thanh bên → Workflows: kéo các test vào bảng rồi bấm Run Workflow. Run Report hiện số pass / fail / skip, thời gian, ảnh chụp và copy được dạng Markdown.

Test data and run history

Add variables in Settings → Environment, or Import .env file…. While recording, tap a text field: the Fill with bar under the preview lists your variables, best match first. Click one and its value is typed while the step is saved as ${KEY}, so the YAML never holds the secret.

Every run is saved. Test Run → History shows the pass rate of the last 10 runs, a Flaky badge when results flip between pass and fail, and the step that fails most.

Dữ liệu test và lịch sử chạy

Thêm biến ở Settings → Environment, hoặc Import .env file…. Khi đang ghi, chạm vào một ô nhập: thanh Fill with dưới màn hình xem trước liệt kê các biến, khớp nhất đứng đầu. Bấm một biến là giá trị được gõ vào, còn bước được lưu là ${KEY}, nên YAML không bao giờ chứa bí mật.

Mọi lần chạy đều được lưu. Test Run → History hiện tỉ lệ pass của 10 lần gần nhất, nhãn Flaky khi kết quả lúc pass lúc fail, và bước hay lỗi nhất.

Connect an AI provider

1. Open Settings ⌘, → AI and choose a Provider.
2. Claude API or OpenAI API: paste your key (sk-ant-… / sk-…) and press Save. It is stored in the macOS Keychain. Without a saved key the app uses ANTHROPIC_API_KEY / OPENAI_API_KEY from your environment.
3. Claude Code, Codex or Command Code: no key. Install the CLI and run it once in Terminal to sign in; the row shows the path it found.
4. Press Test connection. For Claude you can also pick the model and how hard it thinks (Effort).
5. Leave Verify AI-recorded tests with Maestro when done on: every test the AI records is replayed once before you keep it.

Kết nối nhà cung cấp AI

1. Mở Settings ⌘, → AI và chọn Provider.
2. Claude API hoặc OpenAI API: dán key (sk-ant-… / sk-…) rồi bấm Save. Key được lưu trong Keychain của macOS. Nếu chưa lưu key, app dùng ANTHROPIC_API_KEY / OPENAI_API_KEY trong môi trường.
3. Claude Code, Codex hoặc Command Code: không cần key. Cài CLI rồi chạy nó một lần trong Terminal để đăng nhập; dòng Command hiện đường dẫn app tìm thấy.
4. Bấm Test connection. Với Claude bạn chọn thêm model và mức suy nghĩ (Effort).
5. Giữ bật Verify AI-recorded tests with Maestro when done: mỗi test AI ghi sẽ được chạy lại một lần trước khi bạn giữ nó.

Let the AI pilot write a test

1. Open the chat with the ✨ button or ⌘J, with a booted simulator or a live iPhone and your app selected.
2. Write what to do: “Create a test: log in with ${EMAIL} and open Settings”. The AI drives the device and records each step live.
3. If it gets stuck it pauses with Needs your help: reply with a hint, or do the step yourself and press Continue.

Attach tests or steps to the message to improve selectors, suggest assertions or explain a failure.

Để AI pilot viết test

1. Mở chat bằng nút ✨ hoặc ⌘J, khi đã có máy ảo đang chạy hoặc iPhone đang kết nối và đã chọn app.
2. Viết việc cần làm: “Create a test: đăng nhập bằng ${EMAIL} rồi mở Settings”. AI tự thao tác trên thiết bị và ghi từng bước trực tiếp.
3. Khi bị kẹt, AI dừng lại với nhãn Needs your help: trả lời gợi ý, hoặc tự làm bước đó rồi bấm Continue.

Đính kèm test hoặc các bước vào tin nhắn để cải thiện selector, gợi ý kiểm tra hoặc giải thích lỗi.

Share with your team, run in CI

1. Project → Save Project to Folder (git)… → pick your app repository. Commit .maestro-recorder/ and .maestro/.
2. Teammates use Open Project from Folder…; changes from git pull reload automatically. Secret values are never written, only their names.
3. Export → Export Project to Repository ⇧⌘E writes the YAML plus .github/workflows/maestro-e2e.yml.

Chia sẻ cho team, chạy trên CI

1. Project → Save Project to Folder (git)… → chọn repository của app. Commit .maestro-recorder/ và .maestro/.
2. Đồng đội dùng Open Project from Folder…; thay đổi từ git pull tự nạp lại. Giá trị bí mật không bao giờ được ghi ra, chỉ có tên biến.
3. Export → Export Project to Repository ⇧⌘E ghi YAML kèm .github/workflows/maestro-e2e.yml.

# run one flow locally or in CI
maestro test .maestro/login-flow.yaml -e PASSWORD="$PASSWORD"

Run on real devices with BrowserStack

1. Settings → Cloud: enter your BrowserStack username and access key, then Test connection. The key is stored in the Keychain.
2. Press the ☁ button next to Run Test, or ⌥⌘R. On the Workflow board use BrowserStack to run every test of the workflow.
3. Choose .ipa…: a device build (Ad Hoc or Development). An unchanged .ipa is uploaded only once.
4. Pick one or several iPhones and iPads, then Run. Follow the progress, or close the sheet and keep working.

The report shows every device and test with its error and a ▶ video. Results land in History with a Cloud badge, and the steps of the current test turn ✓ or ✗ like a local run.

Chạy trên máy thật với BrowserStack

1. Cài đặt → Cloud: nhập username và access key BrowserStack rồi bấm Thử kết nối. Key được lưu trong Keychain.
2. Bấm nút ☁ cạnh Run Test, hoặc ⌥⌘R. Trên Workflow board, dùng nút BrowserStack để chạy mọi test của workflow.
3. Chọn .ipa…: bản build cho máy thật (Ad Hoc hoặc Development). File .ipa không đổi chỉ tải lên một lần.
4. Chọn một hoặc nhiều iPhone, iPad rồi bấm Chạy. Theo dõi tiến trình, hoặc đóng sheet và làm việc khác.

Báo cáo hiện từng thiết bị, từng test kèm lỗi và ▶ video. Kết quả được lưu vào Lịch sử với nhãn Cloud, và các bước của test hiện tại chuyển ✓ hoặc ✗ như khi chạy trên máy.