Astra Scout Docs

Tiếng Việt

English

Tiếng Việt

English

Giao diện

Jira ​

Soạn bug từ các run fail và gửi lên Jira Cloud sau khi bạn xác nhận.

Tester báo bug lên Jira Cloud từ Astra Scout, và Jira admin thiết lập kết nối.

Astra Scout gom các fail của một run hoặc một lần khám phá, soạn bug từ chính dữ liệu của run (step, video, crash), và gửi lên Jira sau khi người dùng xác nhận. Không có gì được gửi khi chưa được đồng ý.

Việc thiết lập có ba phần, do những người khác nhau làm:

  1. Một admin đăng ký app OAuth trên Atlassian cho cả công ty, để Astra Scout đăng nhập Jira thay người dùng. Admin đưa Client ID cùng secret của app cho các tester.
  2. Mỗi tester kết nối Astra Scout với tài khoản Jira của mình.
  3. Mỗi dự án chọn nơi nhận bug (site Jira, dự án, loại issue).

Admin: tạo app OAuth ​

Người có quyền tạo app Atlassian, thường là Jira admin, tạo một app OAuth cho cả công ty.

  1. Mở Atlassian developer console, bấm Create > OAuth 2.0 integration và đặt tên, ví dụ Astra Scout.

  2. Ở Permissions, thêm Jira API và cấu hình các classic scope sau: read:jira-work, write:jira-work và read:jira-user. Astra Scout tự xin offline_access.

  3. Ở Authorization, cấu hình OAuth 2.0 (3LO) và nhập Callback URL này đúng từng ký tự:

    http://127.0.0.1:47219/callback

    Cùng URL này hiện, kèm nút sao chép, ở trang App OAuth của Astra Scout (xem bên dưới). Nếu cổng 47219 bị chiếm, xem Chi tiết kỹ thuật.

  4. Ở Settings, sao chép Client ID và Secret.

  5. Ở Distribution, chỉ bật Sharing nếu người dùng thuộc site khác với tài khoản đã tạo app.

  6. Đưa Client ID và Secret cho tester qua kênh an toàn. Không commit chúng. Cách đơn giản nhất là nhập trong app, theo các bước dưới đây. Hai cách khác (lúc build, lúc chạy) nằm ở Chi tiết kỹ thuật.

Để nhập Client ID và secret trong app:

  1. Chọn Astra Scout > Cài đặt… (Cmd+,) và bấm Jira ở thanh bên.
  2. Ở Tài khoản, bấm hàng App OAuth. Hàng này bị ẩn khi cả hai giá trị đã lấy từ biến môi trường.
  3. Trang App OAuth hiện URL callback kèm nút sao chép. Đăng ký URL này trong Atlassian console (step 3 ở trên).
  4. Dán Client ID vào ô của nó. Giá trị được lưu khi bấm Return hoặc bấm sang ô khác.
  5. Dán Client secret và bấm Lưu. Ghi chú "Đã lưu client secret" hiện ra. Secret được lưu mã hoá và không hiện lại. Ô đó sau đó ghi "đã lưu", kèm nơi lưu.
  6. Mở Hướng dẫn Admin mở trang này.

Cài đặt > Jira

Tester: kết nối ​

  1. Chọn Astra Scout > Cài đặt… (Cmd+,) và bấm Jira ở thanh bên.
  2. Ở Tài khoản, hàng Jira Cloud ghi "Chưa đăng nhập". Nếu có thêm "Cần app OAuth để kết nối", admin chưa thiết lập. Hỏi admin.
  3. Bấm Kết nối. Trình duyệt mở trang đồng ý của Atlassian, và hàng đó ghi "Đang chờ đăng nhập trong trình duyệt…" (bấm Huỷ để bỏ). Chọn site và Accept.
  4. Quay lại Astra Scout, hàng đó hiện tên tài khoản và Ngắt kết nối. Một nút Cài đặt dự án… hiện bên dưới.

Ngắt kết nối xoá mọi bí mật Jira trên máy: refresh token và client secret đã nhập trong Cài đặt. Để thu hồi hẳn app, vào https://id.atlassian.com/manage-profile/apps.

Phiên đăng nhập hết hạn sau 90 ngày không dùng. Khi đó bấm Kết nối lại. Cách lưu token nằm ở Chi tiết kỹ thuật.

Chọn nơi nhận bug ​

Bước này chọn dự án Jira nhận bug. Lựa chọn được lưu trong workspace, nên ai mở dự án cũng báo bug vào cùng một dự án Jira. Mở một workspace trước.

  1. Chọn File > Cài đặt dự án… (Option+Cmd+,), hoặc bấm Cài đặt dự án… trong Cài đặt > Jira. Nếu cửa sổ ghi "Chưa kết nối Jira.", bấm Kết nối Jira trong Cài đặt… và kết nối trước.
  2. Ở Nơi nhận báo cáo, đặt:
    • Site: chỉ hiện khi tài khoản có nhiều hơn một site Jira. Chọn site trước; Dự án bị tắt cho đến khi chọn. Với một site, nó được chọn cùng lúc với dự án.
    • Dự án: chọn từ danh sách (key và tên).
    • Loại issue: hiện khi đã chọn dự án. Ban đầu là Bug (hoặc loại đầu tiên của dự án nếu không có Bug).
    • Nhãn mặc định: cách nhau bằng dấu phẩy. Khoảng trắng trong một nhãn thành dấu gạch ngang. Được lưu khi bấm Return hoặc rời khỏi ô.
    • Components: các ô tick cho component của dự án. Chỉ hiện khi dự án có component. Chọn dự án khác sẽ xoá các lựa chọn này.
    • Ngôn ngữ bug: Tiếng Việt (mặc định) hoặc English. Đây là ngôn ngữ của nội dung bug được soạn.
    • Đặt Priority theo severity: xem Priority theo severity.
  3. Thay đổi có hiệu lực ngay và được lưu trong workspace.

Cài đặt dự án với Nơi nhận báo cáo

Gửi bug ​

Bug có thể đến từ một run fail hoặc chưa chắc chắn, một run có warning, hoặc một lần khám phá có issue. Một run Pass mà lý do có nhắc tới warning được tính là run có warning. Run Bị chặn hoặc Chưa xong, hoặc bất kỳ run nào mang mã lý do (device, driver, AI, giới hạn, phê duyệt), không phải bug của app và không được đề xuất.

  1. Mở sheet báo cáo theo một trong các cách:

    • Trong runner hoặc navigator Test run, bấm chuột phải vào hàng của run và chọn Báo bug lên Jira…. Chi tiết của hàng cũng có nút này.
    • Chọn Device > Báo bug lên Jira… (Shift+Cmd+B). Nó báo lần khám phá có issue nếu có, nếu không thì run mới nhất có gì đó để báo. Mục này bị tắt khi không có gì để báo.
    • Trong cửa sổ Khám phá app, bấm Báo bug lên Jira… ở phần đầu kết quả (báo tất cả issue), hoặc chọn một issue ở tab Issue rồi bấm Báo bug lên Jira… trong inspector (một issue).
    • Trên một dòng assertEvents bị fail trong editor, mở inspector và bấm Báo bug lên Jira… ở mục Cách sửa. Nó báo step đó.

    Một run fail cần báo

  2. Sheet Báo lên Jira mở ra và hiện "Đang gom bug, cắt video và tìm issue trùng…". Nó liệt kê mỗi issue khác nhau một dòng. Nếu Jira chưa được thiết lập, nó ghi "Chưa thiết lập Jira" và có nút Mở Cài đặt dự án….

    IssueChọn sẵn mặc định
    Step fail đã làm flow dừngCó
    Một crash (gộp với step fail khi crash là nguyên nhân)Có
    Một step optional failKhông
    Một phép kiểm tra *WithAI fail (optional) hoặc chưa chắc chắnKhông
    Một rule tracking fail hoặc warningFail: có. Warning: không.
    Run workspace: mỗi flow fail (các fail giống hệt được gộp)Tuỳ loại
    Issue của khám pháCó
    Warning của khám pháKhông

    Mỗi dòng hiện loại của nó (ví dụ Step fail, Crash, Kiểm tra AI, Tracking, Khám phá), severity, và các nhãn như "severity 4/5" (khám phá), "crash làm step fail", "AI viết lại" và "Cũng gặp ở: …" (cùng issue ở các flow khác).

  3. Tick hoặc bỏ tick ô của từng dòng để chọn cái sẽ gửi. Bấm mũi tên ở cuối dòng (Mở rộng) để mở dòng.

  4. Trong dòng đã mở, sửa tiêu đề và tóm tắt. Bên dưới là fingerprint (mã ngắn nhận diện cùng một lỗi) và Dữ kiện Astra Scout ghi (không sửa được): các step, mong đợi và thực tế, device, OS, app id và phiên bản, crash. Ở Đính kèm, tick các file muốn gửi:

    • Một đoạn video quanh step fail, và ảnh chụp màn hình trước và sau (cắt bằng ffmpeg nếu có).
    • Crash report (.ips trên iOS, đoạn logcat trên Android) và kết quả tracking.
    • YAML của flow và report của run.

  5. Có thể gõ một dòng vào Ghi chú thêm; nó được thêm vào mọi issue. Dòng bên dưới ("N bug được chọn") đếm số dòng đã tick.

  6. Có thể bấm Viết lại Tiêu đề và Tóm tắt bằng AI. Nó chỉ viết lại các dòng đã tick. Nếu AI thêm dữ kiện không có trong run, Astra Scout giữ nguyên văn bản gốc. Dòng đã được viết lại hiện "AI viết lại".

    Sheet Báo lên Jira

  7. Bấm Gửi. Astra Scout hiện một hộp thoại native tên "Gửi lên Jira?" liệt kê chính xác cái gì sẽ được gửi đi đâu. Bấm Gửi lên Jira để tiếp tục, hoặc Huỷ.

  8. Sheet sau đó liệt kê kết quả cho từng dòng: Đã tạo hoặc Đã comment, kèm issue key dạng liên kết, hoặc một error. Mỗi dòng đã tick thành một issue riêng, các issue của cùng một lần gửi được liên kết "relates to", và issue key được ghi vào report của run. Khi run đã ở trên cloud của team, mô tả issue có liên kết tới run và run được gắn issue key: xem Run của team. Bấm Xong.

Trùng lặp ​

Mỗi dòng có một nhãn fingerprint scout-fp-<12 hex> để nhận ra cùng một lỗi. Trong lúc chuẩn bị sheet, Astra Scout tìm trong dự án một issue đang mở có cùng fingerprint. Nếu có, dòng đó ghi "Đã có issue đang mở cùng fingerprint" kèm key của nó, và đưa ra hai lựa chọn:

  • Thêm comment + đính kèm vào KEY-12 (chọn sẵn), hoặc
  • Tạo issue mới.

Issue mới mang fingerprint, astra-scout và các nhãn mặc định.

Che dữ liệu nhạy cảm (redaction) ​

Redaction che dữ liệu nhạy cảm trước khi gửi. Mọi thứ được gửi đều đi qua bộ che này:

  • Giá trị environment, text đã gõ (inputText, setClipboard) và mọi thứ có tên giống password, secret, token hay apikey được thay bằng ***.
  • Đường dẫn tuyệt đối thành <workspace>/… hoặc ~/…, và đường dẫn temp thành <tmp>/….
  • YAML và report đính kèm là bản đã che.
  • Bộ che nghiêng về phía che thừa hơn là bỏ sót.

Xem lại trước khi gửi

Bộ che chỉ che các giá trị bí mật đã biết và các key trông giống bí mật. Bộ che không che: chuỗi literal bên trong evalScript hoặc runScript, text trên màn hình dùng trong selector, và đường dẫn tuyệt đối ngoài thư mục home và workspace. Video và ảnh chụp màn hình có thể lộ text đã gõ. Với flow nhạy cảm, bỏ tick đoạn video và ảnh chụp, hoặc để tự gửi tắt.

Priority theo severity ​

Khi Đặt Priority theo severity được bật trong Nơi nhận báo cáo, Priority của issue lấy từ severity của phát hiện trong lần khám phá. Severity 5 ứng với priority cao nhất trong danh sách của dự án và severity 1 ứng với thấp nhất. Nếu không đọc được danh sách, dùng priority mặc định của dự án.

Tự động gửi crash ​

Khi một run làm app crash, Astra Scout có thể tự tạo issue, kèm video và crash log (đã che).

  1. Mở File > Cài đặt dự án…. Mục Crash hiện khi Jira đã kết nối và đã chọn dự án.
  2. Đặt Số issue tối đa mỗi giờ trước (1 đến 20, mặc định 3). Ô tăng giảm bị tắt khi tự gửi đang bật.
  3. Bật Tự gửi crash. Một hộp thoại native tên "Bật tự gửi crash lên Jira?" nêu site, dự án và giới hạn. Bấm Bật tự gửi.
  4. Khi đang bật, một dòng hiện "Đã gửi N issue trong giờ qua."

Mặc định nó tắt và tự tắt khi Astra Scout khởi động lại. Có thể tắt bất cứ lúc nào mà không cần hộp thoại. Nó chỉ gửi khi không có issue trùng, và tối đa N mỗi giờ. Nếu Astra Scout không xác định được có issue trùng hay không, nó không gửi gì: bản nháp chờ người dùng.

Từ terminal ​

Tool MCP report_bug cho phép AI CLI chuẩn bị bản nháp, nhưng CLI không bao giờ nhận được token Jira và không thể tự gửi. Astra Scout hiện một hộp thoại xác nhận native, và yêu cầu được liệt kê là Chờ xác nhận trong Hoạt động từ CLI ở Cài đặt > AI > Kết nối MCP. Xem Plugin scout.

Cài đặt > AI > Kết nối MCP với Hoạt động từ CLI

Sự cố thường gặp ​

Triệu chứngCách xử lý
"Cổng 47219 đang bận…"Đóng chương trình đang dùng nó, hoặc đặt SCOUT_JIRA_CALLBACK_PORT và đăng ký callback tương ứng.
redirect_uri không khớpCallback URL của app phải đúng là http://127.0.0.1:<cổng>/callback.
"Session Jira đã hết hạn hoặc bị thu hồi"Refresh token đã bị thu hồi hoặc quá 90 ngày. Bấm Kết nối lại.
Dự án bị tắtTài khoản có nhiều site Jira và chưa chọn site nào. Chọn Site trước.
Không thấy dự ánTài khoản có thể thiếu quyền Browse project trên site đó.
Tạo issue fail ở issuetype hoặc componentsChọn lại loại issue hoặc bỏ tick component không tồn tại trong dự án.
Video không được đính kèmNó vượt giới hạn đính kèm của site. Cài ffmpeg để cắt đoạn ngắn hơn.

Thử trên dự án test

Chạy một flow fail, gửi bug, chạy lại (dòng đó phải đề nghị thêm comment), rồi ngắt kết nối và xác nhận các bí mật đã mất.

Chi tiết kỹ thuật ​

  • Cổng callback: nếu cổng 47219 bị chiếm, đặt SCOUT_JIRA_CALLBACK_PORT=<cổng> và đăng ký http://127.0.0.1:<cổng>/callback trong Atlassian console thay thế.
  • Đưa Client ID và Secret lúc build: SCOUT_JIRA_CLIENT_ID=… SCOUT_JIRA_CLIENT_SECRET=… ./scripts/build-stage.sh (hoặc build-mac-app.sh --release). Các giá trị được nhúng vào binary server, nên chỉ dùng cho bản phát hành nội bộ.
  • Đưa Client ID và Secret lúc chạy: đặt cùng các biến đó cho tiến trình Astra Scout, ví dụ bằng launchctl setenv. Chúng thắng giá trị lúc build.
  • Token: access token chỉ nằm trong bộ nhớ của server và không bao giờ được gửi tới UI hay CLI. Refresh token được lưu như dòng dưới Tài khoản cho biết: trong file mã hoá bằng key Keychain riêng của app, trong Keychain của macOS, hoặc trong một file riêng trên máy này. Nó xoay vòng mỗi lần làm mới và hết hạn sau 90 ngày không dùng.
  • Lựa chọn nơi nhận bug nằm trong .scout/project.json của workspace.
  • Redaction nhận diện bí mật qua nhiều kiểu mã hoá (JSON, HTML, percent-encoding, dạng Unicode, không phân biệt hoa thường, các đoạn bị cắt).

Astra Scout by Astraler