Kiểm thử đăng nhập OTP bằng Playwright với hộp thư có sẵn

OTP là mã dùng một lần trong luồng xác thực. Trong bài kiểm thử này, ứng dụng thử gửi và xác thực mã; Playwright thao tác trên giao diện; Mailera kết nối hộp thư hiện có với ứng dụng qua REST API để đọc thư chứa mã.

Cần chuẩn bị gì trước khi chạy?

Bạn cần một dự án Playwright dùng TypeScript, ứng dụng thử do bạn quản lý và hộp thư riêng. Chỉ để một yêu cầu đăng nhập chờ mã trên hộp thư đó.

1. Với quyền Admin hoặc Leader, mở Danh sách hộp thư → Thêm hộp thư. Ưu tiên Đăng nhập Microsoft nếu dùng Outlook hoặc Microsoft 365; kết nối Microsoft bằng OAuth không dùng mật khẩu ứng dụng.
2. Kiểm tra hộp thư đã kết nối và trạng thái đồng bộ. Bạn có thể làm theo hướng dẫn kết nối hộp thư đầu tiên.
3. Trong Cài đặt, chọn Tạo key, giới hạn Phạm vi hộp thư vào nhóm thử và chỉ cấp quyền read.
4. Lưu khóa vào kho bí mật. Khóa mới chỉ hiển thị một lần; không đưa vào mã nguồn.

Nếu dùng Gmail, xem cách kết nối Gmail với Mailera. Luồng này dùng mật khẩu ứng dụng, và Google yêu cầu tài khoản bật xác minh 2 bước theo điều kiện sử dụng app password.

Chuẩn bị cấu hình cho tiến trình chạy kiểm thử:

Đọc OTP qua API nào?

Địa chỉ gốc là https://mailera.app/api/public/v1. Gửi header Authorization: Bearer $MAILERA_API_KEY từ tiến trình kiểm thử, không đặt khóa trong JavaScript của ứng dụng chạy trên trình duyệt.

Endpoint GET /mailboxes/{id}/otp lấy mã mới nhất và cần quyền read:

Các bộ lọc này không gắn mã với một yêu cầu đăng nhập cụ thể. Hai thư từ cùng người gửi, cùng tiêu đề vẫn có thể thuộc hai lượt khác nhau.

Để đối chiếu thư nguồn, dùng GET /messages/search với extract=otp. Kết quả có otp.code cùng id, subject, received_at và thông tin người nhận. Phần đọc OTP từ hộp thư của bạn giải thích tác vụ đọc mã nói chung; ở đây tập trung vào việc nối nó với Playwright.

Yêu cầu tìm thư cho luồng này dùng các tham số sau:

Đọc các thư trong data và tiếp tục phân trang bằng next_cursor. Không giả định thư cần tìm nằm trong trang đầu. Phần đối chiếu tiêu đề và người nhận thuộc logic của bài kiểm thử, không phải một tham số subject gửi tới endpoint tìm kiếm.

Bạn có thể tra các endpoint tại tài liệu API Mailera, hoặc xem các cách tích hợp dành cho lập trình viên.

Thiết kế lượt thử để không chọn nhầm thư

Một cách liên kết thư với yêu cầu đăng nhập là cho ứng dụng thử nhận một mã lượt thử và đưa mã đó vào tiêu đề, theo mẫu Đăng nhập thử <mã lượt thử>. Đây là quy ước bạn triển khai trong ứng dụng thử, không phải tính năng Mailera tự thêm vào thư.

Nếu ứng dụng không hỗ trợ quy ước này, cần dùng cách liên kết thư với yêu cầu đăng nhập của chính ứng dụng. Không bỏ phép đối chiếu rồi lấy mã mới nhất để bài kiểm thử chạy qua.

Luồng thực hiện:

1. Lưu tập mã định danh thư đang có trong hộp thư đến.
2. Tạo mã lượt thử riêng và mở trang đăng nhập.
3. Ghi nhận thời điểm bắt đầu, rồi yêu cầu gửi OTP.
4. Thăm dò API trong thời hạn đã đặt.
5. Chỉ nhận thư mới, đúng người gửi, người nhận, tiêu đề và mốc thời gian.
6. Điền mã, gửi biểu mẫu và kiểm tra màn hình sau đăng nhập.

Mã định danh thư và thời điểm nhận là các lớp kiểm tra bổ sung. Tiêu đề chứa mã lượt thử mới là dấu liên kết với yêu cầu hiện tại trong thiết kế này. Nếu có nhiều thư phù hợp, bài kiểm thử nên dừng thay vì tự chọn một thư.

Nối bước đọc thư với bài kiểm thử Playwright

Bài kiểm thử OTP phải bắt đầu khi chưa đăng nhập. Chọn các ô nhập và nút theo nhãn hoặc vai trò trên giao diện thật của ứng dụng. Nếu dùng mã lượt thử, cơ chế truyền mã đó phải chỉ dành cho môi trường thử và được ứng dụng dùng khi tạo thư.

Sau thao tác yêu cầu gửi mã, chuyển sang vòng thăm dò API. Mỗi vòng đọc thư cần đối chiếu id, from.address, các địa chỉ trong to, subject và received_at với lượt thử hiện tại. Chỉ lấy otp.code khi tìm được đúng một thư phù hợp có mã.

Đặt riêng thời hạn cho từng yêu cầu API, thời hạn chờ email và thời hạn toàn bài kiểm thử. Yêu cầu API cuối cùng không nên được phép kéo dài quá thời gian chờ còn lại. Khoảng nghỉ giữa hai lần thăm dò chỉ để điều chỉnh tần suất gọi, không phải bằng chứng thư đã đến.

Khi hết thời hạn, dừng với thông báo cho biết cần kiểm tra kết nối, bộ lọc và Thư rác. Không đưa OTP, nội dung thư hoặc khóa API vào thông báo lỗi. Cũng không tự yêu cầu gửi lại mã sau mỗi vòng chờ.

Sau khi điền mã và gửi biểu mẫu, kiểm tra dấu hiệu chỉ xuất hiện khi xác thực thành công, chẳng hạn tiêu đề trang tài khoản của ứng dụng. Không coi bài kiểm thử là đạt chỉ vì ô OTP đã được điền.

Giữ một yêu cầu OTP đang chờ trên mỗi hộp thư thử. Khi mở rộng chạy song song, hãy tách hộp thư hoặc thiết kế cơ chế tương quan riêng. Việc ứng dụng từ chối mã hết hạn hay đã sử dụng cũng cần bài kiểm thử riêng; đọc đúng thư không thay thế kiểm thử xác thực mã.

Những lỗi hay gặp cần kiểm tra ở đâu?

GET /mailboxes/{id}/status cần quyền read. Với Microsoft, endpoint kiểm tra đăng nhập trực tiếp; với nhà cung cấp khác, trạng thái dựa trên lần đồng bộ gần nhất.

Nếu Gmail mất kết nối sau khi bạn đổi mật khẩu tài khoản, Google cho biết mật khẩu ứng dụng bị thu hồi khi mật khẩu tài khoản thay đổi.

Yêu cầu tìm kiếm ở trên chỉ đọc inbox. Để chẩn đoán thư rác, dùng GET /mailboxes/{id}/placement hoặc tìm riêng thư mục junk. Không coi hết thời hạn chờ là bằng chứng ứng dụng chưa gửi thư.

Mailera điều chỉnh tần suất kiểm tra theo hoạt động của hộp thư; hộp thư ít dùng có thể ngủ. POST /mailboxes/{id}/sync chủ động đồng bộ và đánh thức hộp thư, nhưng cần quyền sync, không phải read. Chỉ dùng như bước chẩn đoán có chủ đích, không thêm vào mọi vòng chờ.

Chạy trên CI mà không lộ mã

Lưu khóa trong kho bí mật của hệ thống CI, giới hạn nhóm hộp thư và thu hồi khi không còn dùng. Yêu cầu dùng khóa đã thu hồi sẽ bị từ chối ngay. Xem thêm thông tin bảo mật Mailera.

Nếu dùng GitHub Actions, bạn có thể truyền khóa đã lưu thành biến môi trường qua context secrets, theo hướng dẫn sử dụng secrets trong GitHub Actions.

Không ghi toàn bộ phản hồi API vào nhật ký. Giới hạn thông báo lỗi ở trạng thái HTTP hoặc mô tả bước thất bại, không chứa mã hay nội dung thư. Rà soát cả báo cáo của trình chạy kiểm thử và các lớp ghi nhật ký khác.

Đối với dự án kiểm thử OTP riêng, có thể cấu hình không lưu ảnh, video và trace:

import { defineConfig } from '@playwright/test';
export default defineConfig({
  testDir: './tests',
  workers: 1,
  use: { screenshot: 'off', video: 'off', trace: 'off' },
});

Không chạy nhiều tiến trình CI cùng dùng hộp thư này. Nếu cần ảnh để chẩn đoán, che mã và địa chỉ trước khi chia sẻ.

Chỉ tái sử dụng storageState cho các bài không kiểm tra chính luồng OTP. Bài kiểm thử OTP phải bắt đầu chưa đăng nhập và đi qua bước yêu cầu mã. Không đưa tệp trạng thái xác thực vào kho mã nguồn.

Giới hạn cần giữ trong thiết kế

Mailera không tạo hộp thư hay địa chỉ email mới; bạn phải kết nối hộp thư thử có sẵn.

Đừng thiết kế bài kiểm thử với giả định thư đến tức thì. Mailera không bảo đảm thư vào hộp thư đến: bộ lọc của nhà cung cấp vẫn quyết định vị trí thư. Vì vậy, thời hạn chờ và bước chẩn đoán Thư rác là hai phần riêng của luồng kiểm thử.