Device

Kết nối iOS Simulator, iPhone thật và device Android, đồng thời xử lý sự cố kết nối.

Chọn device bằng bộ chọn device ở giữa thanh công cụ. Bộ chọn hiện Chọn device cho tới khi bạn chọn. Chọn một device là kết nối nó, và Ngắt kết nối (ở cuối bộ chọn) giải phóng nó. Danh sách tự cập nhật khi simulator hoặc device xuất hiện. Khi mở lại app, app tự kết nối lại device bạn chọn lần trước (nếu device có mặt); sau khi Ngắt kết nối thì không.

Để tìm một device trong danh sách dài, gõ vào ô lọc ở đầu bộ chọn. Dùng phím mũi tên lên xuống để di chuyển và Return để kết nối. Ngắt kết nối là dòng cuối khi đã có device kết nối.

Ngắt kết nối cũng tắt WebDriverAgent trên iPhone hoặc simulator, nên trên máy không còn bài test nào chạy. Khi bạn chuyển sang device khác hoặc bấm Kết nối lại, WebDriverAgent vẫn chạy thêm 10 phút. Quay lại trong khoảng đó thì kết nối chỉ mất khoảng một giây.

Khi đang kết nối, bảng hiển thị các step như Kết nối simulator, Kết nối iPhone, Kết nối emulator, Kết nối driver và Stream về Astra Scout. Lần kết nối iOS đầu tiên build WebDriverAgent (WDA) và mất khoảng 3 đến 10 phút. Sau đó bản build được dùng lại.

Kiểm tra máy của bạn trước

Help → Kiểm tra thiết lập… kiểm tra mọi thứ trên trang này và chỉ cách sửa từng mục. Xem Cài đặt.

iOS Simulator

1. Cài Xcode từ App Store, rồi mở nó một lần để đồng ý license và cài các thành phần nó đề nghị.

2. Trong Xcode → Settings → Components, tải runtime iOS Simulator.

3. Trỏ command-line tools tới Xcode:

   sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
   sudo xcodebuild -license accept
   sudo xcodebuild -runFirstLaunch

4. Kiểm tra xcrun simctl list runtimes có một dòng bắt đầu bằng iOS.

5. Chọn một simulator trong bộ chọn device.

App tự render màn hình simulator qua SimulatorKit của Xcode. Chạm, phím, nút cứng và xoay đi qua devicehid, còn con lăn chuột thành một cú kéo một ngón. Không có app native thì server hiển thị simulator bằng ảnh chụp WDA chậm hơn. Video flow được quay bằng xcrun simctl io recordVideo.

Cây phần tử của simulator được đọc qua xcuiax, nhanh hơn WDA nhưng cần simulator iOS 27+. Simulator cũ hơn, màn hình có nội dung web, và mọi error, sẽ tự động chuyển sang WDA. Chạy server với SCOUT_FAST_AX=0 để tắt tính năng này.

iPhone thật

Chạy trên iPhone thật đòi hỏi phải ký WebDriverAgent bằng tài khoản Apple của bạn. Làm các step này một lần cho mỗi máy Mac và mỗi iPhone.

1. Đăng nhập Xcode

1. Hoàn tất các step iOS Simulator ở trên.
2. Trong Xcode → Settings → Accounts, thêm Apple ID của bạn (tài khoản thuộc team Apple Developer của công ty, hoặc tài khoản cá nhân).
3. Chọn team, rồi Manage Certificates… → + → Apple Development. Keychain của bạn giờ có chứng chỉ tên "Apple Development: Tên Của Bạn (XXXXXXXXXX)".

Mã trong ngoặc không phải Team ID

Team ID là giá trị 10 ký tự ở developer.apple.com → Membership details. App đọc đúng Team ID từ chứng chỉ.

Personal Team (Apple ID miễn phí) dùng được, nhưng provisioning profile của nó chỉ có hiệu lực 7 ngày. Khi hết hạn, WDA không mở được nữa và bạn phải kết nối lại để app ký lại. Hãy dùng team của công ty nếu có.

2. Chọn team trong app

1. Mở Settings → iOS (mục Team ký app).
2. Chọn một team từ danh sách Team (lưu ngay, không cần khởi động lại). Nếu chỉ có đúng một team, nó được dùng tự động.
3. Nếu thiếu team của bạn, kiểm tra lại step trên và bấm Quét lại. Bạn cũng có thể nhập Team ID thủ công (10 ký tự, A đến Z và 0 đến 9) rồi bấm Lưu.
4. Dòng "Đang dùng: …" cho biết Team ID mà lần kết nối tiếp theo sẽ dùng.

Ai chạy server từ dòng lệnh có thể dùng --team-id hoặc MAESTRO_TEAM_ID. Giá trị chọn trong Settings được ưu tiên.

3. Chuẩn bị iPhone

1. Cắm cáp và mở khoá máy. Chạm Trust khi máy hỏi "Trust This Computer?".
2. Trong Xcode, mở Window → Devices and Simulators, chọn iPhone và đợi nó chuẩn bị xong.
3. Trên iPhone, bật Settings → Privacy & Security → Developer Mode. Máy sẽ khởi động lại. Mở khoá và xác nhận lần nữa. Mục này chỉ xuất hiện sau khi iPhone đã được kết nối với Xcode.
4. Đặt Settings → Display & Brightness → Auto-Lock → Never khi test. Astra Scout không đọc được cài đặt này, nhưng Kiểm tra thiết lập sẽ nhắc bạn.

4. Kết nối và tin cậy nhà phát triển

Chọn iPhone trong bộ chọn device. Lần đầu, app build và cài WDA. Nếu iPhone hiện "Untrusted Developer", vào Settings → General → VPN & Device Management, chọn chứng chỉ Apple Development: … và chạm Trust, rồi kết nối lại.

Nếu build WDA fail do ký, dòng dưới mirror hiện cách sửa và đường dẫn tới build.log, kèm nút Mở cài đặt iOS… để mở Cài đặt → iOS.

Khi iPhone tự khoá

iPhone bị khoá làm mirror màu đen, inspector rất chậm và các step fail. Trước mỗi run, khám phá, tự sửa, lệnh MCP và lần dùng inspector, Astra Scout hỏi WDA xem màn hình có đang khoá không.

• iPhone không có passcode được mở khoá tự động và run tiếp tục.
• iPhone có passcode chỉ được đánh thức màn hình. Astra Scout từ chối run với thông báo "iPhone screen is locked — unlock the iPhone and try again".
• Mirror hiện thông báo Màn hình iPhone đang khoá khi phát hiện máy khoá.
• Nếu iPhone khoá giữa run, kết luận là Bị chặn với mã DEVICE_LOCKED. Trường hợp này không bị coi là bug của app.

Mirror iPhone

Khung device mirror iPhone bằng media stream của CoreDevice (Xcode 27 và iOS 27, cáp hoặc Wi-Fi). Đây là cách mirror duy nhất: không còn screen capture USB và không cần quyền Camera. Việc gõ phím và các nút vẫn đi qua WDA.

• Nếu iPhone đang khoá hoặc chưa kết nối được, khung báo mở khoá iPhone và tự chạy ngay khi iPhone phản hồi.
• iPhone không có media stream hiện "this iPhone cannot stream its screen over CoreDevice". Flow vẫn chạy bình thường.
• Nếu bạn ngắt và kết nối lại trong vòng 15 giây, stream đang chạy được dùng lại.
• Video quay flow trên iPhone chỉ lấy từ media stream của CoreDevice. Khi stream này không có, flow chạy không có video và lý do được ghi vào log.

Điều khiển trực tiếp (HID)

Với Xcode 27 trên Mac và iOS 27 trên iPhone, thao tác chạm và kéo trên mirror được tool devicehid đi kèm gửi thẳng tới màn hình cảm ứng ảo của iPhone. Ngón tay nhấn khi bạn bấm chuột, di theo chuột và nhấc lên khi bạn nhả chuột. Siri, Nút Tác vụ, Chụp màn hình, Đa nhiệm và vuốt mép cũng dùng HID. Việc gõ phím, cuộn, xoay màn hình và các nút Home, âm lượng, Nguồn vẫn đi qua WDA.

• Session điều khiển mở khi bạn chạm lần đầu trên mirror và giữ mở trong lúc mirror mở, cộng thêm 15 giây sau khi bạn ngắt kết nối.
• Khi session đang mở, iPhone hiện "<tên Mac> is viewing and controlling this iPhone". Đây là bình thường.

Không chạm "Stop Session" trên iPhone

Thao tác đó huỷ ghép đôi iPhone với Mac. Bạn sẽ phải cắm lại, chạm Trust và ghép đôi lại trong Xcode.

• Nếu không dùng được, cử chỉ chuyển về phát lại qua WDA và flow vẫn chạy.
• Help → Kiểm tra thiết lập… → iPhone thật → Direct iPhone control (HID) cho biết iPhone nào dùng được. devicehid gắn với phiên bản framework CoreDevice của Xcode, nên sau khi cập nhật Xcode, hãy cài bản build mới hơn nếu phép kiểm tra báo fail.
• Tắt bằng cách chạy server với SCOUT_IOS_HID=0.

clearState trên iPhone thật

iOS không có lệnh "xoá dữ liệu app", nên clearState gỡ cài đặt rồi cài lại app. Trên Simulator, Astra Scout tự lấy app đã cài. Trên iPhone thật, lệnh cần một file .ipa hoặc .app bản iPhone trên máy Mac. Nó tìm theo thứ tự:

1. File bạn chọn trong sheet Bản build clearState. Mở menu app trên toolbar và chọn Bản build cho clearState… (chỉ hiện khi có iPhone thật đang kết nối và đã chọn một app). App ID lấy từ bộ chọn app. Ở mục App cho iPhone thật, bấm Chọn File…. Bỏ Chọn xoá lựa chọn của bạn.
2. Bản build iPhone mới nhất của app (khớp bundle id) trong Xcode DerivedData hoặc Archives. Để tạo, chọn iPhone đang cắm làm đích chạy trong Xcode và bấm Product → Build.

Một file chỉ dùng được nếu nó là bản build cho iPhone (iphoneos, không phải iphonesimulator), đã được ký, và provisioning profile của nó có iPhone đang cắm. Bản release App Store không cài được lên device test. Sheet này cho biết file nào sẽ được dùng và vì sao một file không dùng được. Sau khi build trong Xcode, bấm Kiểm tra lại, rồi Xong.

Nếu không có file dùng được, run dừng trước step đầu tiên với kết luận Bị chặn và mã APP_FILE_REQUIRED.

clearState xoá dữ liệu app

Lệnh này xoá toàn bộ dữ liệu của app trên device (đăng nhập, cài đặt, file đã tải), giống như tự gỡ cài đặt.

Android

1. Cài Android Studio và để nó tải Android SDK (mặc định ~/Library/Android/sdk).
2. Trong Android Studio → Settings → Languages & Frameworks → Android SDK → SDK Tools, bật Android SDK Platform-Tools và Android Emulator.
3. Tạo device ảo ở Device Manager → Create Virtual Device (ví dụ Pixel 8, API 34 trở lên).
4. Trong Astra Scout, mở Settings → Android → Android SDK. Để trống nếu SDK ở vị trí mặc định, hoặc nhập đường dẫn hay bấm Chọn thư mục….

Với device Android thật, chạm Build number 7 lần trong Settings → About phone để bật Developer options, bật USB debugging, cắm cáp và chạm Allow USB debugging trên device (tick "Always allow from this computer"). Kiểm tra bằng:

~/Library/Android/sdk/platform-tools/adb devices

Device phải hiện trạng thái device, không phải unauthorized.

Làm việc với device đã kết nối

Điều khiển dưới mirror

Thanh thao tác dưới mirror có các nút chỉ xuất hiện khi device đang kết nối hỗ trợ chúng.

Vị trí	iOS	Android
Thanh thao tác	Home, Chụp màn hình, Xoay, Kiểm tra, Khám phá	Quay lại, Home, Chụp màn hình, Xoay, Kiểm tra, Khám phá
Menu Thao tác device khác (⋯)	Đa nhiệm (App Switcher), Âm lượng +, Âm lượng −, Siri (iPhone thật), Nút Tác vụ, Khoá, rồi Cài app…, Xoá lịch sử mua sandbox…, Phóng to mirror, Mở cửa sổ riêng và Ngắt kết nối	Đa nhiệm, Âm lượng +, Âm lượng −, Nguồn, Chế độ tối, rồi Cài app…, Phóng to mirror, Mở cửa sổ riêng và Ngắt kết nối

Các nút bên hông chỉ nằm trong menu ⋯ khi mirror không có khung máy hiển thị chúng. Kiểm tra và Khám phá tương ứng với Device → Kiểm tra phần tử và Device → Khám phá app….

Trên iPhone thật có Xcode 27 trên Mac và iOS 27 trên iPhone, Siri, Nút Tác vụ, Chụp màn hình và Đa nhiệm đi qua đường HID của CoreDevice (xem Điều khiển trực tiếp (HID)), còn Home, âm lượng và Khoá đi qua WDA. Không có Xcode 27 và iOS 27 thì iPhone chỉ có những nút mà WDA bấm được.

Cài đặt simulator (iOS Simulator)

Đổi cài đặt của simulator mà không cần rời mirror, bằng tab Cài đặt của thanh kiểm tra hoặc Device → Simulator:

• Giao diện: Sáng hoặc Tối.
• Cỡ chữ: Nhỏ hơn, Lớn hơn hoặc Mặc định trong menu, hoặc thanh trượt trong thanh kiểm tra.
• Tăng độ tương phản: Bật hoặc Tắt.
• Công tắc trợ năng trong tab Cài đặt: Cỡ chữ trợ năng lớn hơn, Giảm chuyển động, Hiện viền, Giảm độ trong suốt và VoiceOver. Mỗi công tắc chỉ hiện khi simulator hỗ trợ.
• Vị trí: một vị trí có sẵn, Tuỳ chỉnh… (vĩ độ và kinh độ cách nhau bằng dấu phẩy, ví dụ 37.3349, -122.009) hoặc Không có để xoá.
• Face ID / Touch ID: Đã đăng ký hoặc Chưa đăng ký, rồi Khuôn mặt / vân tay khớp hoặc Khuôn mặt / vân tay không khớp để trả lời một yêu cầu xác thực.
• Lắc máy.

Tab Cài đặt còn có Kiểu hiển thị và thanh trượt Độ mờ Liquid Glass, khi simulator hỗ trợ.

Cài đặt Android

Trên device hoặc emulator Android, tab Cài đặt của thanh kiểm tra (và menu Device → Android) đổi cài đặt của device mà không cần rời mirror:

• Giao diện: Sáng hoặc Tối. Device → Android → Chế độ tối và mục Chế độ tối trong menu ⋯ cũng làm việc này.
• Cỡ phông chữ và Kích thước hiển thị: thanh trượt.
• TalkBack: bật hoặc tắt.
• Điều hướng: Cử chỉ hoặc 3 nút.
• Ngôn ngữ app: Mặc định hệ thống hoặc một ngôn ngữ.
• Đặt lại (Device → Android → Đặt lại cài đặt Android) đưa các cài đặt về giá trị ban đầu.

Thu phóng

Thu phóng mirror bằng các nút thu phóng trên thanh công cụ hoặc Device → Thu phóng: Phóng to (Cmd+=), Thu nhỏ (Cmd+-), Vừa khung (Cmd+9) và Kích thước thật (Option+Cmd+9). Giữ Option và cuộn để di chuyển trong mirror đã phóng.

Tab Báo cáo (iPhone thật)

Tab Báo cáo của thanh kiểm tra liệt kê các báo cáo crash, log, spin và chẩn đoán của một iPhone thật. Dùng Loại báo cáo để lọc. Simulator không có các báo cáo này.

Tab Thông tin

Tab Thông tin của thanh kiểm tra liệt kê những gì Astra Scout biết về device đang kết nối. Tab có ba phần: Thông tin, App và Hồ sơ (Hồ sơ chỉ có trên iPhone thật). Ở App bạn có thể gỡ cài đặt một app, và ở Hồ sơ bạn có thể gỡ một hồ sơ. Cả hai đều hỏi xác nhận trước.

Cử chỉ trên iPhone thật

Kéo từ mép dưới của mirror lên để thực hiện cử chỉ Home, giống trên điện thoại. Một cú chạm bắt đầu trong khoảng 3% màn hình tính từ mép được tính là vuốt mép. Flow dùng cùng kiểu vuốt mép này.

Ngang, Phóng to và cửa sổ riêng

• Ngang: khi bạn xoay device, khung máy xoay theo màn hình.
• Phóng to mirror: cho mirror chiếm toàn bộ cửa sổ. Bấm Hiện các khung khác để trả bố cục lại như cũ. Stream hình vẫn chạy liên tục.
• Mở cửa sổ riêng: tách mirror thành một cửa sổ riêng với đầy đủ thao tác chạm, bàn phím. Cửa sổ giữ đúng tỉ lệ màn hình và xoay theo device. Cửa sổ chính hiện một khung giữ chỗ với nút Đưa về lại, còn Cây phần tử vẫn nằm ở cửa sổ chính. Cửa sổ riêng đóng cùng lúc với device, cửa sổ chính hoặc server.

Lưu ý về iPhone thật

• Khi session điều khiển đang mở, iPhone hiện "<tên Mac> is viewing and controlling this iPhone". Tuyệt đối không chạm Stop Session: nó huỷ ghép nối iPhone. Để ghép lại, cắm cáp, chạm Trust và dùng Xcode → Window → Devices and Simulators.
• macOS phải nhìn thấy iPhone. Cáp luôn dùng được. Qua Wi-Fi sync, iPhone chỉ hiện khi đang thức và có thể biến mất khi máy ngủ, nên hãy dùng cáp.

Cài app

Chọn Device → Cài app… (Shift+Cmd+I), hoặc Cài app… trong menu ⋯ dưới mirror. Bạn cũng có thể thả file .app, .ipa, .apk hoặc .apkm lên mirror. Chọn file .app hoặc .ipa cho iOS, hoặc file .apk hoặc .apkm cho Android bằng Chọn file…, hoặc chọn một file trong Dùng gần đây, rồi bấm Cài đặt. Astra Scout báo warning nếu nền tảng của app không khớp với device đang kết nối. Bấm nút thùng rác ở cuối một dòng trong Dùng gần đây (Quên) để bỏ app đó khỏi danh sách; việc này không đụng đến device.

Tình trạng driver

Astra Scout kiểm tra driver (WDA trên iOS, socket DeviceLab trên Android) trước mỗi run và cứ 15 giây một lần khi đang kết nối. Nếu driver không phản hồi, device hiện Đang kết nối lại driver và driver khởi động lại một lần. Nếu vẫn không được, device hiện error kèm nút Kết nối lại (cạnh Ngắt kết nối), và các run không bắt đầu.

Cây phần tử

Device → Cây phần tử (Option+Cmd+E) hiện cây các phần tử của màn hình hiện tại trong navigator. Xem Inspector.