Pengujian Login OTP Email dengan Playwright dan Mailera

Kapan perlu memakai email sungguhan, bukan OTP simulasi?

Tes login belum selesai hanya karena formulir menerima sebuah kode. Untuk menguji jalur email, Anda perlu memastikan aplikasi mengirim pesan, kotak surat menerimanya, dan aplikasi menerima kode dari pesan tersebut.

OTP adalah kode sekali pakai yang digunakan aplikasi untuk verifikasi. Dalam alur ini, Mailera menghubungkan kotak surat yang sudah ada ke aplikasi melalui REST API. Aplikasi yang diuji tetap menentukan apakah kode boleh digunakan untuk login.

Gunakan simulasi untuk pengujian antarmuka yang tidak membutuhkan email. Sisakan tes menyeluruh dengan email sungguhan untuk jalur login yang ingin Anda pantau. Jangan menyediakan kode simulasi di lingkungan produksi.

Panduan ini memakai satu percobaan login aktif pada satu kotak surat khusus. Untuk dasar pembacaan kode melalui API, lihat panduan mengambil OTP dari kotak surat sendiri.

Apa yang perlu disiapkan sebelum menjalankan tes?

1. Siapkan aplikasi dan kotak surat khusus pengujian

Pastikan proyek Playwright dengan TypeScript, halaman login aplikasi uji, dan akun yang menggunakan kotak surat milik Anda sudah siap digunakan. Jangan memakai kotak surat pribadi yang bercampur dengan pesan sensitif.

Alur ini mengharuskan aplikasi uji menyertakan penanda unik pada subjek email untuk setiap eksekusi. Atur penanda itu pada aplikasi sebelum menjalankan tes, lalu berikan subjek yang sama melalui variabel lingkungan OTP_SUBJECT. Jangan menggunakan kembali penanda dari eksekusi sebelumnya.

2. Hubungkan kotak surat ke Mailera

Admin atau Leader dapat membuka Kotak surat → Tambah kotak surat. Untuk Outlook atau Microsoft 365, pilih Masuk dengan Microsoft dan gunakan OAuth. Ikuti panduan koneksi Microsoft, bukan sandi aplikasi. Jika koneksi lama Anda bergantung pada sandi aplikasi Outlook, baca panduan beralih ke OAuth.

Untuk Gmail, alur koneksi Mailera menggunakan sandi aplikasi (app password). Google mensyaratkan verifikasi 2 langkah untuk fitur tersebut, sebagaimana dijelaskan dalam persyaratan sandi aplikasi Google.

3. Buat kunci dengan izin minimum

Di Pengaturan, buka bagian kunci API dan pilih Buat API key. Batasi Cakupan kotak surat ke grup pengujian, lalu berikan izin read. Pembacaan OTP dan pesan tidak membutuhkan izin mengirim email.

Simpan kunci segera setelah dibuat karena nilainya hanya ditampilkan sekali. Gunakan penyimpanan rahasia lokal atau CI, bukan berkas yang masuk repositori. Halaman developer Mailera menjadi rujukan integrasi API Anda.

4. Tentukan ID kotak surat

Dengan $MAILERA_API_KEY sudah tersedia di lingkungan shell, jalankan:

curl --fail-with-body --silent --show-error \
  'https://mailera.app/api/public/v1/mailboxes?limit=1' \
  -H "Authorization: Bearer $MAILERA_API_KEY"

Respons memuat daftar data, termasuk id, email, status, dan informasi sync. Cocokkan alamatnya dengan kotak surat uji sebelum menyimpan ID sebagai $MAILBOX_ID. Jangan otomatis memilih hasil pertama bila grup Anda berisi beberapa kotak surat.

MAILERA_API_KEY dan MAILBOX_ID adalah nama variabel lingkungan contoh. Keduanya bukan nama parameter kueri API.

Bagaimana menulis tes Playwright yang mengambil OTP?

Endpoint GET /mailboxes/{id}/otp mengambil OTP terbaru dengan izin read dan menyediakan parameter from, subject, serta since_minutes. Untuk alur berikut, gunakan GET /messages/search dengan extract=otp: hasilnya menyertakan id, subject, alamat pengirim, dan otp.code, sehingga pemilihan pesan dapat diperiksa di dalam tes.

Rincian endpoint tersedia di dokumentasi API Mailera. Jangan menyalin bentuk respons pencarian ke endpoint OTP; keduanya adalah operasi berbeda.

1. Tetapkan kontrak aplikasi uji

Gunakan empat data-testid: login-email, send-otp, login-otp, dan verify-otp. Setelah login, halaman akun harus menampilkan account-home. Sesuaikan penanda elemen tersebut dengan aplikasi Anda.

Sediakan variabel berikut melalui lingkungan lokal atau CI:

Aplikasi harus benar-benar mengirim subjek tersebut. Variabel OTP_SUBJECT hanya memberi tahu tes pesan mana yang harus dipilih; variabel itu tidak mengubah email yang dikirim aplikasi.

2. Susun pembacaan API dan langkah tes

Pisahkan pembacaan email dari interaksi browser agar kegagalan API tidak tercampur dengan kegagalan formulir. Gunakan kontrak HTTP berikut untuk pembacaan dari proses tes:

Jangan mengirim header otorisasi Mailera ke aplikasi uji. Kunci tersebut hanya digunakan untuk permintaan API Mailera.

1. Periksa bahwa semua variabel lingkungan sudah terisi sebelum membuka halaman login.
2. Buka APP_LOGIN_URL, isi login-email dengan TEST_EMAIL, lalu picu pengiriman melalui send-otp.
3. Kirim permintaan HTTP sesuai tabel di atas.
4. Jika respons HTTP gagal, hentikan tes. Jika berhasil, periksa daftar data dan pilih pesan yang mailbox_id, subject, serta from.address-nya cocok dengan percobaan ini. Kandidat harus memiliki otp.code berupa string yang tidak kosong.
5. Hentikan tes jika lebih dari satu kandidat cocok pada halaman yang diperiksa. Jika tidak ada kandidat, ulangi pembacaan sampai tenggat.
6. Jika ada satu kandidat, isi login-otp dengan otp.code, kirim melalui verify-otp, lalu periksa bahwa account-home terlihat.

Parameter pencarian adalah mailbox, bukan mailbox_id. Nama mailbox_id digunakan pada pesan dalam respons. Subjek dicari melalui q, lalu dicocokkan secara penuh di sisi tes; endpoint pencarian tidak memiliki parameter subject.

3. Periksa pemilihan kandidat dan tenggat

Parameter q membantu pencarian. Pemeriksaan di sisi tes tetap mencocokkan kotak surat, subjek lengkap, dan alamat pengirim. Tes berhenti jika lebih dari satu kandidat cocok ditemukan di halaman respons yang diperiksa. Alur ini hanya memeriksa hingga 50 hasil pada halaman pertama dan tidak memeriksa halaman berikutnya.

Respons pencarian memiliki next_cursor. Tanpa menelusuri halaman lanjutan melalui parameter cursor, pemeriksaan tersebut tidak memastikan bahwa hanya ada satu kandidat di seluruh hasil pencarian.

Respons HTTP gagal juga harus langsung menghentikan pembacaan. Jangan memperlakukan kesalahan akses sebagai kondisi “email belum tiba”.

Sebagai konfigurasi awal, tetapkan anggaran polling 60 detik, interval 2 detik, dan batas permintaan 5 detik. Angka ini adalah pilihan konfigurasi tes, bukan janji waktu penerimaan email. Batasi durasi setiap permintaan dan jeda dengan sisa anggaran polling. Hentikan loop segera setelah mendapat kandidat.

Pastikan hanya ada satu percobaan login aktif. Jangan memakai ulang penanda subjek, termasuk ketika mengulang tes yang gagal. Jangan izinkan job CI lain menggunakan kotak surat yang sama secara bersamaan.

4. Periksa hasil login

Sediakan anggaran waktu untuk navigasi dan pemeriksaan halaman di luar anggaran polling. Tenggat keseluruhan harus tetap terbatas; email yang belum ditemukan tidak boleh membuat tes menunggu tanpa akhir.

Hasil akhir yang diperiksa adalah halaman akun, bukan sekadar kode yang tidak kosong. Jika kode sudah ditemukan tetapi halaman akun tidak tampil, telusuri tahap pengiriman formulir dan penerimaan kode oleh aplikasi, bukan terus membaca email.

Bagaimana mencegah tes memakai OTP lama?

Jangan menyamakan "OTP terbaru" dengan "OTP untuk percobaan ini". Parameter since_minutes bukan pengganti identitas percobaan login.

Alur di atas memakai subjek unik dan satu percobaan aktif. Buat penanda baru untuk setiap eksekusi, termasuk saat Anda menjalankan ulang job yang gagal. Jika aplikasi tidak dapat menyertakan penanda, jangan menghapus pemeriksaan subjek lalu menganggap tes masih memiliki korelasi yang sama.

Untuk menelusuri kandidat, GET /mailboxes/{id}/messages menyediakan filter since dan from, serta hasil dengan received_at. Detail isi tersedia melalui GET /mailboxes/{id}/messages/{msgId}. Cocokkan aturan waktu dan format filter dengan kontrak API sebelum menjadikannya syarat pemilihan kode.

Pembacaan pesan juga bukan pengujian lengkap masa berlaku OTP. Uji penolakan kode kedaluwarsa dan penggunaan ulang sebagai kasus tersendiri pada aplikasi. Jangan mengandalkan pemilihan email untuk menggantikan validasi backend.

Kesalahan apa yang sering membuat tes OTP gagal?

Endpoint status memeriksa login Microsoft secara langsung. Untuk penyedia lain, statusnya berdasarkan sinkronisasi terakhir. Status koneksi bukan bukti bahwa email tertentu sudah diterima.

Mailera menyesuaikan frekuensi pemeriksaan latar belakang dengan aktivitas kotak surat. Kotak surat tidak aktif dapat tidur. Jika diperlukan, POST /mailboxes/{id}/sync memicu sinkronisasi sekaligus membangunkannya, tetapi membutuhkan izin sync. Kunci read pada alur utama tidak cukup.

Untuk koneksi Gmail yang berhenti setelah sandi akun berubah, Google menyatakan bahwa perubahan sandi Akun Google mencabut sandi aplikasi. Periksa koneksi penyedia sebelum mengubah kode Playwright.

Mailera tidak menjamin penempatan di Inbox. Jangan menjadikan pemindahan pesan dari folder Spam sebagai bukti bahwa pengiriman berikutnya akan masuk Inbox.

Bagaimana menjaga rahasia pengujian tetap aman?

Gunakan akun uji sendiri dan batasi kunci ke grup yang diperlukan. Pembacaan email tidak memerlukan izin send, manage, atau sync.

Jika memakai GitHub Actions, simpan kunci sebagai secret dan berikan ke langkah pengujian melalui variabel lingkungan. Dokumentasi penggunaan secrets di GitHub Actions menjelaskan penggunaan konteks secrets untuk memasok nilai rahasia sebagai input atau variabel lingkungan.

Jangan mencetak respons lengkap saat tes gagal. Catat tahap tes, waktu, dan jenis kesalahan tanpa OTP, kunci API, atau isi pesan. Periksa juga trace, video, tangkapan layar kegagalan, dan log jaringan sebelum membagikan artefak. Perlakukan formulir login dan sesi uji sebagai data sensitif.

Batasi akses serta masa penyimpanan artefak CI. Jangan memasukkan status autentikasi ke repositori. Gunakan informasi keamanan Mailera saat meninjau integrasi, lalu cabut kunci yang tidak lagi diperlukan; permintaan dengan kunci yang dicabut langsung ditolak.

Alur ini memakai skrip deterministik, bukan agent yang mengikuti instruksi di dalam email. Isi email adalah data tidak tepercaya: ambil hanya nilai yang dibutuhkan tes dan jangan menjalankan instruksi dari pesan.