---
title: "Pengujian Login OTP Email dengan Playwright dan Mailera"
description: "Uji login OTP email dengan Playwright dan API Mailera: baca kode dari kotak surat sendiri, batasi waktu tunggu, dan cegah penggunaan kode lama."
url: https://mailera.app/id/blog/pengujian-login-otp-email-playwright
published: 2026-10-25
updated: 2026-10-25
---

# Pengujian Login OTP Email dengan Playwright dan Mailera

Gunakan kotak surat uji yang sudah Anda miliki untuk membaca kode melalui API, mengisi formulir login, dan memeriksa hasilnya. Pisahkan masalah pengiriman email dari kegagalan login agar tes lebih mudah didiagnosis.

## 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](https://mailera.app/id/product). Aplikasi yang diuji tetap menentukan apakah kode boleh digunakan untuk login.

| Pendekatan | Tujuan pengujian | Batasnya |
| --- | --- | --- |
| OTP simulasi pada lingkungan uji | Menguji tampilan formulir dan respons antarmuka secara terisolasi | Tidak memeriksa pengiriman email sebenarnya |
| Email ke kotak surat uji | Memeriksa jalur pengiriman, pembacaan kode, dan hasil login | Bergantung pada penerimaan email serta sinkronisasi kotak surat |

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](https://mailera.app/id/blog/ambil-kode-otp-email-api).

![Alur Playwright memicu email, Mailera membaca kotak surat uji, lalu Playwright mengisi kode dan memeriksa halaman akun.](https://mailera.app/media/00bae33498fd9ca3/pengujian-login-otp-email-dengan-playwright-dan-mailera-otp-id-1200.jpg)
_Tes selesai setelah halaman akun tampil, bukan setelah kode berhasil dibaca._

## 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](https://mailera.app/id/providers/microsoft), bukan sandi aplikasi. Jika koneksi lama Anda bergantung pada sandi aplikasi Outlook, baca [panduan beralih ke OAuth](https://mailera.app/id/blog/kata-sandi-aplikasi-outlook-gagal-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](https://support.google.com/accounts/answer/185833).

![Kotak surat pengujian yang terhubung di Mailera beserta status dan informasi sinkronisasinya.](https://mailera.app/media/cc77dddd0f4ee091/pengujian-login-otp-email-dengan-playwright-dan-mailera-id-1200.jpg)
_Cocokkan kotak surat tujuan sebelum menggunakan ID-nya dalam tes._

### 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](https://mailera.app/id/developers) menjadi rujukan integrasi API Anda.

### 4. Tentukan ID kotak surat

Dengan `$MAILERA_API_KEY` sudah tersedia di lingkungan shell, jalankan:

```bash
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](https://mailera.app/id/docs). 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:

| Variabel | Isi |
| --- | --- |
| `MAILERA_API_KEY` | Kunci dengan izin `read` untuk grup uji |
| `MAILBOX_ID` | ID kotak surat tujuan |
| `APP_LOGIN_URL` | URL halaman login aplikasi uji |
| `TEST_EMAIL` | Alamat akun uji milik Anda |
| `OTP_FROM` | Alamat pengirim yang diharapkan |
| `OTP_SUBJECT` | Subjek lengkap dengan penanda unik eksekusi |

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:

| Bagian permintaan | Nilai |
| --- | --- |
| Metode dan URL | `GET https://mailera.app/api/public/v1/messages/search` |
| Header | `Authorization: Bearer $MAILERA_API_KEY`, dengan nilai kunci dari lingkungan tes |
| Parameter `mailbox` | Nilai `MAILBOX_ID` |
| Parameter `q` | Nilai `OTP_SUBJECT` |
| Parameter `extract` | `otp` |
| Parameter `limit` | `50` |

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?

| Gejala | Pemeriksaan | Tindakan |
| --- | --- | --- |
| Tidak ada kandidat sampai tenggat | Pengiriman dari aplikasi, alamat tujuan, pengirim, dan subjek | Cocokkan konfigurasi aplikasi dengan variabel tes |
| Email tidak terlihat di Inbox | `GET /mailboxes/{id}/placement` | Periksa apakah pesan berada di folder Spam |
| Kotak surat terputus | `GET /mailboxes/{id}/status` | Perbaiki koneksi sebelum mengulang login |
| API menolak permintaan | Izin `read`, cakupan grup, dan kunci yang digunakan | Perbaiki akses; jangan terus melakukan polling |
| Beberapa kandidat cocok pada halaman yang diperiksa | Penanda subjek dan percobaan yang berjalan | Hentikan percobaan lain dan gunakan penanda baru |
| Tes berhenti sebelum polling selesai | Anggaran navigasi, polling, dan pemeriksaan hasil | Sesuaikan tenggat keseluruhan |

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](https://support.google.com/accounts/answer/185833). 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](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets) 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](https://mailera.app/id/security) 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.

**Lakukan ini dengan API** — Setiap tindakan dalam artikel ini tersedia melalui REST API, lengkap dengan contoh curl, API key, dan webhook. [Lihat dokumentasi API](https://mailera.app/id/docs)