Chạy flow

Mở workspace, viết flow, chạy trên device và đọc kết quả.

Tester làm việc theo một vòng lặp: mở workspace, viết flow, chạy trên device và đọc kết quả. Mỗi lần chạy một flow là một run.

Workspace

Workspace là một thư mục chứa các flow Maestro (file .yaml) và bất cứ thứ gì khác đặt cạnh chúng. Dùng menu File, hoặc cửa sổ Chào mừng đến với Astra Scout khi chưa mở workspace nào:

Lệnh	Chức năng
Workspace mới… (Cmd+N)	Chọn hoặc tạo thư mục cho test và dựng sẵn cấu trúc workspace bên dưới.
Mở workspace… (Cmd+O)	Mở thư mục đã có flow.
Đóng workspace	Đóng workspace hiện tại.
Mở gần đây	Mở lại workspace đã dùng trước đó. Xoá danh sách gần đây ở cuối menu con làm trống danh sách.

Để tạo một workspace:

1. Bấm Workspace mới… trong cửa sổ Chào mừng đến với Astra Scout, hoặc chọn File > Workspace mới….
2. Một bảng chọn thư mục mở ra với thông báo "Chọn hoặc tạo thư mục cho các test Maestro". Chọn một thư mục có sẵn, hoặc dùng nút tạo thư mục mới của bảng.
3. Bấm Tạo. Workspace mở trong cửa sổ chính.

Để mở thư mục đã có flow, bấm Mở workspace…. Bảng ghi "Chọn workspace"; chọn thư mục rồi bấm Mở.

Nếu thư mục workspace không còn tồn tại, app yêu cầu mở lại thư mục dự án.

Workspace mới có sẵn cấu trúc sau. Mở workspace… giữ nguyên thư mục như hiện có.

<workspace>/
├── first-flow.yaml   flow mẫu để chạy và học
├── README.md         mô tả từng thư mục
├── *.yaml            các flow
├── subflows/         flow được flow khác gọi
├── tracking-specs/   spec tracking, kèm README (xem Tracking)
└── artifacts/runs/   video và ảnh chụp màn hình của mỗi run; workspace đã liên kết đưa chúng lên team dưới dạng team run, không sync như file

first-flow.yaml có appId: ${APP_ID} (app đang chọn ở toolbar), header tracking, và các step để chạy (launchApp, takeScreenshot), xen kẽ các step đang tắt (dòng bắt đầu bằng #: assertVisible, assertEvents) mà bạn bật bằng cách xoá dấu #. tracking-specs/sample.yaml là catalog mà flow trỏ tới. File mẫu chỉ được tạo trong thư mục chưa có file .yaml nào; workspace đã có flow thì không bị thay đổi.

Navigator File

Navigator File hiển thị các file và thư mục của workspace.

Ở cuối navigator có nút Thêm (+) và một ô lọc. Ô lọc thu hẹp danh sách khi gõ.

Tạo file hoặc thư mục

1. Bấm nút Thêm (+), hoặc bấm chuột phải vào một thư mục hay chỗ trống trong navigator.
2. Chọn File mới… (Shift+Cmd+N) hoặc Thư mục mới….
3. Với file, chọn một mẫu (Test mobile, File JavaScript, File văn bản hoặc Tracking Catalog) rồi bấm Tiếp. Nhập tên và bấm Tạo. Một test mobile còn hỏi App ID. Các step đầy đủ nằm ở Tạo flow.
4. Với thư mục, gõ tên trong sheet Tạo thư mục rồi bấm Tạo.

Flow có appId: ${APP_ID} chạy trên app đang chọn ở bộ chọn app trên toolbar. Khi chưa chọn app nào, lúc chạy sẽ nhắc chọn app. Nếu môi trường tự đặt APP_ID, giá trị đó được ưu tiên. Flow có appId cố định (ví dụ appId: com.example.app) thì chạy trên đúng app đó, không phụ thuộc bộ chọn app.

Thao tác với một mục

Bấm chuột phải vào một mục trong navigator. Menu tuỳ theo mục được bấm:

Bấm vào	Menu
Một file flow	Chạy test (bật cho flow chạy được khi có device kết nối), Hiện trong Finder, Nhân bản, Đổi tên, Xoá
File khác	Hiện trong Finder, Nhân bản, Đổi tên, Xoá. Chạy test có hiện nhưng bị tắt.
Một thư mục	File mới…, Thư mục mới…, Hiện trong Finder, Đổi tên, Xoá
Chỗ trống	File mới…, Thư mục mới…, Hiện trong Finder
Nhiều mục	Chỉ Xoá N mục

Xoá hỏi trước ("Xoá mục này?") và chuyển mục vào Thùng rác. Kéo thả file và thư mục để di chuyển; Astra Scout yêu cầu xác nhận bằng Di chuyển hoặc Huỷ.

Các cách khác để tạo flow: xem Tạo flow.

Tìm trong workspace

Dùng khi cần tìm mọi flow nhắc đến một đoạn text, ví dụ tên màn hình hoặc một appId.

1. Ở navigator, chuyển sang Tìm (biểu tượng kính lúp trên thanh biểu tượng dưới bộ chuyển ở trên cùng).
2. Gõ vào ô Tìm trong workspace. Kết quả hiện sau một khoảng ngắn. Tìm không phân biệt hoa thường và bỏ qua file ẩn.
3. Kết quả được nhóm theo file, số kết quả nằm bên phải tên file. Việc tìm dừng ở 1.000 kết quả đầu tiên và có thông báo.
4. Bấm một kết quả. File mở ra với đoạn tìm thấy được chọn.

Nhấn Esc hoặc bấm Xoá nội dung tìm để làm trống ô.

Editor

Editor hiển thị một file tại một thời điểm. Dùng Quay lại và Tiến tới trên thanh công cụ (Ctrl+Cmd+← và Ctrl+Cmd+→) để chuyển giữa các file đã mở. Editor gợi ý lệnh Maestro khi gõ. Trong danh sách gợi ý, các lệnh mà device đang kết nối không chạy được bị gạch ngang, và trong văn bản chúng bị gạch chân bằng đường chấm; rê chuột lên đường gạch chân để xem lý do.

• Thanh phía trên editor (jump bar) hiện workspace, các thư mục và file. Bấm một đoạn để mở menu các file cạnh nó và nhảy sang file khác. Với file .yaml, .yml hoặc .js, cuối thanh có nút ? mở tài liệu.
• Khi Tự động lưu bật (mặc định), file tự lưu sau một khoảng trễ ngắn. Tắt bằng File > Tự động lưu hoặc trong Cài đặt > Chung. Cmd+S lưu ngay lập tức và Cmd+W đóng file.
• Khi flow chạy, mỗi dòng lệnh hiển thị trạng thái: đang chờ, đang chạy, hoàn tất hoặc fail.
• Bấm vào số dòng ở lề (gutter) để mở một menu nhỏ. Menu có Chạy “lệnh” và Chạy từ đây. Khi đang chọn nhiều lệnh, mục đầu là Chạy N lệnh đã chọn (N là số lệnh đang chọn). Dòng gọi file khác bằng runFlow còn có Mở tên file. Các mục này chạy trên device đang kết nối mà không rời editor. Ở dòng assertEvents, bấm chuột phải vào số dòng để có Xem chi tiết event ở đầu menu. Xem Tracking.
• Khi Tự động lưu tắt, đóng file hoặc thoát app sẽ hỏi có lưu thay đổi không. Chọn Lưu, Huỷ hoặc Không lưu (Cmd+D).
• Nếu một chương trình khác sửa file đang có thay đổi chưa lưu, Astra Scout hỏi giữ bản nào: Giữ thay đổi của tôi hoặc Tải lại từ đĩa. File chưa sửa thì tự tải lại.

Cần một lệnh nhanh?

Bật Device > Kiểm tra phần tử, bấm chuột phải vào một phần tử trên màn hình device và dùng Chèn vào trình soạn thảo. Xem Inspector.

Chọn app cần kiểm thử

Đoạn đầu của viên thuốc trên toolbar, bên trái bộ chọn device, là app mà flow chạy trên đó. Nó hiện Chưa chọn app cho tới khi chọn app. Lựa chọn được lưu trong workspace, nên mọi người mở workspace đều dùng cùng một app. Bộ chọn bị vô hiệu cho tới khi mở workspace.

1. Bấm bộ chọn app trên toolbar.

2. Chọn một mục trong menu:

   Mục	Dùng để
   Dự án này	App đã lưu trong dự án
   Trên tên device	App đã cài trên device đang kết nối
   Gần đây	App đã dùng trước đó
   App ID khác…	Gõ bundle id như com.example.app, rồi bấm Dùng. Dùng bị tắt và dòng ghi chú "App ID (bundle id) không hợp lệ" hiện cho tới khi id hợp lệ.
   Bản build cho loại device, Builds…	Các bản build mới nhất của team, để đổi bản đang dùng, và cửa sổ Builds. Hiện khi team có project cho app đã chọn.

3. Bộ chọn app giờ hiện app đó. Flow có appId: ${APP_ID} chạy trên app này, và Khám phá cũng bắt đầu với app đó.

Chạy một flow

Các cách chạy flow

• Một flow: bấm Chạy test (Cmd+R). Xem Chạy một flow.
• Chỉ một số lệnh: Chạy một số lệnh.
• Mọi flow trong workspace: Chạy tất cả flow (Shift+Cmd+R).
• Từ terminal: skill run-flow của plugin hoặc tool MCP run_flow. Xem Plugin scout.
• Sửa flow đang fail đến khi chạy qua: Tự sửa.

1. Kết nối device. Xem Device.
2. Mở file flow.
3. Bấm Chạy test trên thanh công cụ (Cmd+R). Chạy test chỉ bật khi có device kết nối và file đang mở là một flow. Nút bị tắt trong lúc có run đang chạy.
4. Xem Runner. Trạng thái trên thanh của Runner đổi thành "Running" kèm tên flow, và mỗi dòng trong editor hiện trạng thái của nó.
5. Dùng Dừng (Cmd+.) để huỷ. Khi run đang dừng, trạng thái ghi "Đang dừng…".
6. Khi run kết thúc, trạng thái ghi "Run gần nhất pass" hoặc "Run gần nhất bị fail". Xem Đọc kết quả.

Trước khi một run bắt đầu, Astra Scout kiểm tra driver (và, trên iOS device, xem màn hình có đang khoá không). Các step giống mua hàng chạy như mọi step khác. Xem Test mua hàng.

Chạy một số lệnh

1. Chọn từ hai lệnh trở lên trong editor.
2. Chọn Chạy > Chạy các lệnh đã chọn (Option+Cmd+R), hoặc bấm chuột phải và chọn Chạy N lệnh đã chọn.

Chỉ các lệnh đó chạy trên device. Cả hai bị tắt trong lúc có run đang chạy.

Chạy tất cả flow trong workspace

1. Kết nối device.
2. Chọn Chạy > Chạy tất cả test (Shift+Cmd+R). Mọi flow trong workspace được chạy. Thanh của Runner ghi "Đang chạy tất cả test".
3. Để dừng, chọn Chạy > Dừng (Cmd+.). Trong lúc chạy cả workspace, nút trên thanh công cụ có nhãn Dừng tất cả test.

Video của một run workspace dùng chung một thư mục, với _2, _3 được thêm vào các tên trùng.

Chọn môi trường

Menu Môi trường ở bên phải thanh của Runner áp dụng các biến và tag có đặt tên cho run. Nút của menu ghi Không có môi trường hoặc tên môi trường đã chọn. Menu liệt kê Không có, rồi từng môi trường, rồi Quản lý môi trường…. Menu bị tắt trong lúc có run đang chạy. Xem Môi trường và biến.

Thanh của Runner

Thanh mỏng dưới editor luôn hiện, kể cả khi Runner bị ẩn. Từ trái sang phải:

• Step và Tracking chuyển nội dung của bảng: step và log của một run, hoặc kiểm tra Tracking.
• Trạng thái run gần nhất: "Chưa có run nào", "Running" kèm tên flow, "Đang chạy tất cả test", "Đang dừng…", "Run gần nhất pass" hoặc "Run gần nhất bị fail".
• Vị trí con trỏ (Dòng và Cột) của file đang mở, trừ tracking spec đang hiện dạng form, và, khi workspace là một repository git, nhánh hiện tại.
• Menu Môi trường và nút Ẩn Runner / Hiện Runner (Shift+Cmd+Y).

Viên thuốc nhỏ trên toolbar, cạnh bộ chọn device, cũng cho biết run gần nhất: vòng quay khi đang chạy, dấu đỏ kèm số step fail, hoặc dấu tích xanh khi pass. Bấm vào để mở các step của run đó.

Thông báo của run

Khi một run không bắt đầu hoặc không dừng được, một thanh thông báo hiện phía trên các step. Ví dụ: "Một test khác đang chạy", "Chưa kết nối device", "YAML không hợp lệ". Bấm nút x (Bỏ qua) để đóng. Khi driver không phản hồi và kết nối lại không giải quyết được, thông báo ghi "Device không khả dụng" và có nút Kết nối lại.

Nếu không ký được app trên iOS device, bảng kết nối hiện error cùng Kết nối lại, Ngắt kết nối và nút Mở cài đặt iOS…. Xem Device.

Đọc kết quả

Navigator Test run liệt kê các run, mới nhất ở trên. Mỗi mục có biểu tượng trạng thái, tên flow, kết quả (Pass, Fail hoặc "Đang chạy test"), ngày và thời lượng.

1. Bấm Test run trên thanh biểu tượng của navigator.
2. Bấm một run. Bảng chạy test mở ra: mỗi flow một dòng (kết quả và thời điểm ở dưới tên, thời lượng ở bên phải), rồi mỗi step một dòng. Step fail có lý do hiện ngay bên dưới.
3. Bấm một dòng để xem khung chi tiết ở bên phải danh sách. Với một step, khung hiện error và Log của step.
4. Bấm đúp một dòng để mở file flow.

Mỗi dòng có một biểu tượng trạng thái: đang chờ, đang tiến hành, pass, fail, warning hoặc đã bỏ qua. Dòng của assertEvents hiện từng event mong đợi thành một dòng riêng, kèm thời điểm event đến hoặc issue gặp phải. Sau khi báo bug lên Jira, dòng flow hiện liên kết tới issue Jira. Trong workspace đã liên kết với project của team, navigator còn liệt kê run của team: xem Run của team.

Bấm chuột phải vào một dòng, hoặc dùng các nút ở khung chi tiết, để có các thao tác:

Thao tác	Ở đâu	Mục đích
Mở file	Menu và khung chi tiết	Nhảy tới file flow
Sao chép log	Khung chi tiết, cạnh Log của một step; cũng có trong sheet Toàn bộ log	Sao chép log của một step
Xem bản ghi	Menu và khung chi tiết	Phát video của run lên trên mirror device. Hai nút biểu tượng ở góc trên bên phải của trình phát, Tải bản ghi và Đóng bản ghi, lưu video và quay về mirror.
Xem toàn bộ log…	Chỉ trong menu	Mở toàn bộ log của run trong một sheet
Sửa bằng AI	Menu và khung chi tiết	Giao flow fail cho AI. Xem Trợ lý AI.
Tự sửa…	Chỉ trong khung chi tiết	Để AI sửa flow và chạy lại đến khi pass. Bị tắt khi AI không khởi động được.
Báo bug lên Jira…	Menu và khung chi tiết	Xem Jira

Xoá lịch sử… ở cuối navigator xoá lịch sử chạy cục bộ của workspace, sau khi xác nhận.

Kết luận (verdict)

Ngoài pass hoặc fail theo từng step, mỗi run có một nhãn kết luận do Astra Scout tính từ chính báo cáo của driver về những gì xảy ra trên device. AI không bao giờ viết nó.

Nhãn	Ý nghĩa	Bạn làm gì	Exit code của CLI (dùng khi chạy từ terminal hoặc CI)
Pass	Mọi step đều qua.	Không cần làm gì.	0
Fail	Bug thật của app hoặc flow: selector sai, assertion fail, app crash.	Mở step bị fail, rồi sửa flow hoặc báo bug.	1
Chưa xong	Dừng trước khi có kết luận: bấm Dừng, chạm giới hạn, AI hết thời gian.	Chạy lại.	2
Chưa chắc chắn	Một phép kiểm tra AI bắt buộc không kết luận được, nên cần người xem lại.	Mở ảnh chụp màn hình của step và tự quyết định.	2
Bị chặn	Issue về device hoặc môi trường: mất kết nối, driver không phản hồi, app chưa cài, ký không được, không có AI cho phép kiểm tra AI bắt buộc.	Kết nối lại device hoặc sửa môi trường, rồi chạy lại.	3

Chi tiết

Các phép kiểm tra AI (assertWithAI, assertNoDefectsWithAI, extractTextWithAI) mặc định là optional: true. Một phép kiểm tra AI optional bị fail, chưa chắc chắn, bị chặn hoặc hết giờ chỉ hiện là warning và run vẫn kết thúc Pass. Thêm optional: false vào step để nó quyết định kết luận như mô tả ở trên.

Step bị cắt ngang vì thiết bị mất kết nối làm run thành Bị chặn (ENVIRONMENT_UNAVAILABLE, step báo "Device disconnected"), kể cả step optional hay continueOnFailure. Flow đã chạy xong mọi step thì giữ nguyên kết luận khi kết nối đóng ngay sau đó.

Để xem lý do, bấm vào dòng flow. Khung chi tiết hiện kết luận, lý do, Mã lý do, Step quyết định, Mã thoát CLI và liên kết Báo cáo (JSON) kèm nội dung báo cáo bên dưới. Báo cáo được lưu cùng run dưới dạng Markdown và JSON.

Mã lý do

Mã lý do là tên ngắn cho nguyên nhân khiến run không kết luận được. Tester thường chỉ cần đọc cột "Ý nghĩa"; mã dùng khi báo lỗi cho team hoặc khi viết script. Một run Bị chặn luôn có mã lý do. Một run Chưa xong có mã khi biết nguyên nhân. Run có mã lý do không bao giờ bị coi là bug của app, nên không có báo cáo bug nào được đề xuất.

Mã	Ý nghĩa
ENVIRONMENT_UNAVAILABLE	Device hoặc driver chưa sẵn sàng (mất kết nối, WDA hoặc driver của device không phản hồi)
APP_NOT_INSTALLED	App chưa được cài
APP_FILE_REQUIRED	clearState trên iOS device cần một bản build đang dùng. Bấm Mở Builds… và chọn một bản. Xem Builds.
AUTOMATION_UNSUPPORTED	Lệnh không được hỗ trợ trên nền tảng này
AI_PROVIDER_UNAVAILABLE	AI chưa cài, chưa đăng nhập, fail hoặc hết thời gian
AI_BUDGET_EXHAUSTED	Hết lần gọi AI (khám phá)
STEP_BUDGET_EXHAUSTED	Chạm giới hạn step, vòng hoặc thời gian
POLICY_DENIED	Bị từ chối theo chính sách
NEEDS_HUMAN	Tester phải thao tác trên device (hộp thoại mua hàng hoặc mật khẩu của hệ thống)
SYSTEM_OVERLAY	Một hộp thoại hoặc sheet hệ thống iOS che app. Các step khớp text hoặc id trên hộp thoại đó sẽ thao tác trực tiếp lên nó.
DEVICE_LOCKED	Màn hình iOS device đang khoá và có passcode
UNKNOWN	Bị chặn, nhưng không có dữ kiện nào nêu nguyên nhân

Video

Video của flow được lưu trong workspace đang mở:

<workspace>/artifacts/runs/<ngày_giờ bắt đầu run>/<tên file flow>.mp4

takeScreenshot với đường dẫn tương đối, ví dụ - takeScreenshot: home, lưu home.png vào <ngày_giờ bắt đầu run>/<tên file flow>/, cạnh video, thay vì cạnh file flow, nên mỗi run giữ ảnh riêng. Đường dẫn tuyệt đối được giữ nguyên. Lệnh chạy ngoài file flow trong một workspace lưu ảnh vào một thư mục run riêng.

Astra Scout tạo artifacts/runs/.gitignore chứa * để video không bị commit. Nó không sửa .gitignore của workspace. Video của các lệnh chạy ngoài file flow và của khám phá nằm trong thư mục dữ liệu của app, dưới tests/<session>/videos/.

Lịch sử chạy phát video từ các đường dẫn đó. Nếu xoá file, video biến mất khỏi lịch sử.

Lệnh không chạy được

Các lệnh mà nền tảng đang kết nối không hỗ trợ được đánh dấu trong editor và bị AI cùng các tool MCP từ chối. Xem Nền tảng được hỗ trợ.

Tiếp theo

• Viết flow và tham chiếu lệnh
• Xử lý sự cố