Playwright ईमेल OTP टेस्ट: अपने इनबॉक्स से सही कोड पढ़ें

ईमेल OTP टेस्ट में आपका ऐप कोड भेजता है और टेस्ट उसी ईमेल से कोड पढ़ता है। यह TOTP बनाने की प्रक्रिया से अलग है। Mailera मौजूदा मेलबॉक्स को REST API से जोड़ता है; सामान्य प्रक्रिया के लिए अपने इनबॉक्स से OTP पढ़ने की गाइड देखें।

शुरू करने से पहले क्या चाहिए?

आपके पास अपना परीक्षण ऐप, अपने नियंत्रण वाला मेलबॉक्स और Playwright वाला Node.js/TypeScript प्रोजेक्ट होना चाहिए। वास्तविक उपयोगकर्ताओं के खातों पर यह उदाहरण न चलाएँ।

1. मेलबॉक्स जोड़ें। मेलबॉक्स → मेलबॉक्स जोड़ें खोलें। इसके लिए Admin या Leader भूमिका चाहिए। Outlook और Microsoft 365 में Microsoft से साइन इन करें वाला OAuth मार्ग अपनाएँ। Microsoft कनेक्शन पेज में पूरा तरीका है; app password की समस्या हो तो Outlook में OAuth अपनाने की गाइड देखें।
2. Gmail का सही कनेक्शन चुनें। Mailera में Gmail के लिए ऐप पासवर्ड (app password) इस्तेमाल होता है। Google के अनुसार इसके लिए दो-चरणीय सत्यापन चालू होना चाहिए। Gmail कनेक्शन पेज और ऐप पासवर्ड की गाइड में संबंधित जानकारी है।
3. कनेक्शन और पहचानकर्ता जाँचें। GET /mailboxes की data सूची में अपना परीक्षण ईमेल पता खोजें और उसके id, status तथा last_sync_at देखें। सूची का पहला मेलबॉक्स अपने आप न चुनें।
4. सीमित key बनाएँ। सेटिंग्स के API key भाग में API key बनाएँ चुनें। मेलबॉक्स का दायरा केवल परीक्षण समूह तक रखें और read अनुमति चुनें। इस प्रक्रिया में send, move या sync की जरूरत नहीं है।

नई key केवल एक बार दिखाई जाती है। उसे CI के सुरक्षित चर MAILERA_API_KEY में रखें और मेलबॉक्स पहचानकर्ता MAILBOX_ID में। समाप्ति भी अपने परीक्षण काम के अनुसार चुनें। ऐप का URL अलग परीक्षण कॉन्फ़िगरेशन में रखें, Mailera API base में नहीं।

Playwright से नया OTP कैसे मँगाएँ और पढ़ें?

अनुरोध से ठीक पहले टेस्ट का समय दर्ज करें। न्यूनतम सेटअप में इस मेलबॉक्स पर एक ही सक्रिय OTP अनुरोध रखें। यदि आपका परीक्षण ऐप अनुमति देता है, तो हर अनुरोध के ईमेल subject में अलग पहचान जोड़ें। यही पहचान पुराने ईमेल से इस अनुरोध को अलग करेगी।

Mailera में GET /mailboxes/{id}/otp नवीनतम OTP लेने के लिए है और इसे read अनुमति चाहिए। इसके फ़िल्टर हैं:

नीचे का उदाहरण GET /messages/search के साथ extract=otp इस्तेमाल करता है। इससे OTP के साथ उसी संदेश का mailbox_id, from, subject और received_at मिलते हैं। कोड और संदेश का संबंध एक ही परिणाम में जाँचा जा सकता है। डेवलपर पेज API का परिचय देता है और API दस्तावेज़ में endpoint संदर्भ है।

1. API helper की तैयारी करें

इन तीन TypeScript खंडों को क्रम से email-otp.ts में रखें। key और मेलबॉक्स पहचानकर्ता वातावरण से आते हैं; किसी असली पते या OTP को कोड में लिखने की जरूरत नहीं है।

import { expect, type APIRequestContext, type Locator } from '@playwright/test';
type OtpMail = {
  mailbox_id: string; from: { address: string }; subject: string;
  received_at: string; otp?: { code?: string };
};
type OtpPage = { data: OtpMail[]; next_cursor?: string | null };
const base = 'https://mailera.app/api/public/v1';
const key = process.env.MAILERA_API_KEY;
const mailbox = process.env.MAILBOX_ID;
if (!key || !mailbox) throw new Error('Mailera configuration missing');

2. एक पेज पढ़ने वाला फ़ंक्शन जोड़ें

Playwright का APIRequestContext API अनुरोध भेजता है। header का रूप Authorization: Bearer $MAILERA_API_KEY है। यहाँ timeout हर अनुरोध को सीमित करता है। HTTP अनुरोध विफल होने पर कोड रुक जाता है; इसे खाली इनबॉक्स नहीं मानता।

async function readPage(
  request: APIRequestContext, sender: string, cursor: string, timeout: number
): Promise<OtpPage> {
  const response = await request.get(`${base}/messages/search`, {
    headers: { Authorization: `Bearer ${key}` }, timeout,
    params: { mailbox: mailbox!, from: sender, extract: 'otp', limit: 50,
      ...(cursor ? { cursor } : {}) }
  }).catch(() => { throw new Error('Mailera request failed'); });
  if (!response.ok()) throw new Error(`Mailera HTTP ${response.status()}`);
  try { return await response.json() as OtpPage; }
  catch { throw new Error('Mailera response could not be read'); }
}

3. संबंधित नया कोड मिलने तक जाँचें

यहाँ कुल प्रतीक्षा 60 सेकंड, प्रत्येक अनुरोध की सीमा अधिकतम 5 सेकंड और जाँचों के बीच अंतराल 2 सेकंड चुना गया है। ये उदाहरण की सेटिंग हैं, ईमेल पहुँचने का वादा नहीं। अपने ऐप की OTP अवधि और CI के अनुसार इन्हें तय करें।

async function waitForOtp(request: APIRequestContext, sender: string,
  subject: string, startedAt: number, waitMs = 60_000): Promise<string> {
  const deadline = startedAt + waitMs;
  let cursor = '';
  while (Date.now() < deadline) {
    const result = await readPage(request, sender, cursor,
      Math.max(1, Math.min(5_000, deadline - Date.now())));
    const match = result.data.find(m => m.mailbox_id === mailbox &&
      m.from.address === sender && m.subject === subject &&
      Date.parse(m.received_at) >= startedAt && typeof m.otp?.code === 'string' && m.otp.code.length > 0);
    if (match && Date.now() < deadline) return match.otp!.code!;
    cursor = result.next_cursor || '';
    await new Promise(resolve => setTimeout(resolve, Math.max(0, Math.min(2_000, deadline - Date.now()))));
  }
  throw new Error('OTP deadline exceeded');
}

Helper परिणामों के अगले पेज भी पढ़ता है। पेज समाप्त होने पर अगली जाँच फिर शुरुआत से होती है। वह केवल सबसे ऊपर दिखा कोड लौटाने के बजाय अपेक्षित subject और प्रेषक का मिलान करता है।

4. अपने ऐप के वास्तविक locators जोड़ें

उसी फ़ाइल में यह फ़ंक्शन जोड़ें। इसे बुलाने से पहले परीक्षण ऐप खोलें और परीक्षण ईमेल पता भरें। ui में अपने ऐप के वास्तविक locators दें: OTP मँगाने का बटन, कोड का फ़ील्ड, पुष्टि का बटन और लॉगिन के बाद दिखने वाला संकेत।

export async function loginWithEmailOtp(
  request: APIRequestContext,
  ui: { send: Locator; otp: Locator; verify: Locator; signedIn: Locator },
  sender: string, requestSubject: string
) {
  await expect(ui.signedIn).not.toBeVisible();
  const startedAt = Date.now();
  await ui.send.click();
  const code = await waitForOtp(request, sender, requestSubject, startedAt);
  await ui.otp.fill(code);
  await ui.verify.click();
  await expect(ui.signedIn).toBeVisible();
}

requestSubject वह पूरा, अलग subject होना चाहिए जिसे आपका परीक्षण ऐप इस अनुरोध के ईमेल में भेजता है। केवल helper को अलग string देने से ईमेल का subject नहीं बदलता। बाहरी Playwright टेस्ट की समय-सीमा तय करते समय API की प्रतीक्षा और UI चरणों, दोनों का समय जोड़ें।

ईमेल आने तक कैसे रुकें, बिना पुराना OTP उठाए?

एक लंबा sleep() सही कोड की पहचान नहीं करता। ऊपर का लूप हर बार परिणाम जाँचता है और समय खत्म होने पर स्पष्ट विफलता देता है। UI के तैयार होने की प्रतीक्षा से अलग, ईमेल के लिए यह जाँच रखें।

since_minutes हाल की अवधि चुनने में मदद करता है, लेकिन एक ही अवधि में पुराने और नए अनुरोध के ईमेल हो सकते हैं। इसलिए उदाहरण में subject को इस अनुरोध की पहचान बनाया गया है और received_at की तुलना अनुरोध से पहले दर्ज समय से की गई है।

यदि ऐप अलग subject नहीं भेज सकता, तो इस helper को स्थिर subject देकर समान सुरक्षा मानकर न चलें। एक सक्रिय अनुरोध तक सीमित रहें और अपने ऐप में अनुरोध तथा संदेश के बीच स्पष्ट संबंध तय करें। अनुरोध से पहले मौजूद संदेशों के id याद रखना उपयोगी अतिरिक्त जाँच है, लेकिन देर से आया पुराने अनुरोध का संदेश फिर भी नया दिखाई दे सकता है।

संदेशों की जाँच के लिए GET /mailboxes/{id}/messages में from और since जैसे फ़िल्टर उपलब्ध हैं। सूची में id, received_at और subject देखें; जरूरत हो तो GET /mailboxes/{id}/messages/{msgId} से उसी संदेश की सामग्री पढ़ें। सबसे नया संदेश मिलना अकेले पर्याप्त नहीं है।

समय खत्म होने पर टेस्ट विफल करें। उसी लूप में बार-बार नया OTP मँगाकर समस्या न छिपाएँ। दोबारा मँगाने का व्यवहार जाँचना हो तो उसे अलग टेस्ट बनाएँ।

आम गलतियाँ: OTP न मिले या लॉगिन विफल हो तो क्या जाँचें?

GET /mailboxes/{id}/placement से Inbox या Spam में पहुँचने की जाँच कर सकते हैं। इसमें from, subject और since_minutes फ़िल्टर हैं। इसके परिणाम से यह न मान लें कि OTP खोज किन फ़ोल्डरों में होती है; संबंधित संदेश की जगह देखें।

GET /mailboxes/{id}/status Microsoft का sign-in सीधे जाँचता है। अन्य प्रदाताओं की स्थिति अंतिम सिंक पर आधारित होती है। मेलबॉक्स विवरण में last_sync_at और sync.state भी देखें। Gmail का Google Account पासवर्ड हाल में बदला हो तो Google ऐप पासवर्ड रद्द कर देता है।

निष्क्रिय मेलबॉक्स स्लीप मोड में जा सकते हैं। जरूरत हो तो अलग निदान के तौर पर POST /mailboxes/{id}/sync चलाएँ; यह सिंक शुरू करता है और सोए मेलबॉक्स को जगाता है। इसके लिए sync अनुमति चाहिए, इसलिए ऊपर की read-only key से इसे न चलाएँ।

उदाहरण HTTP विफलता पर रुकता है। अनुरोध सीमा या अस्थायी सेवा विफलता के लिए retry जोड़ें तो उसे कुल समय-सीमा के अंदर रखें। अनुमति की स्थायी समस्या को बार-बार अनुरोध भेजकर ठीक करने की कोशिश न करें। Mailera किसी प्रदाता से प्रेषक पर भरोसा नहीं करवा सकता और Inbox placement की गारंटी नहीं देता।

CI में key, OTP और लॉगिन सत्र सुरक्षित कैसे रखें?

key केवल परीक्षण समूह तक सीमित रखें। उसे स्रोत कोड या ब्राउज़र पेज में न डालें। Mailera की सुरक्षा संबंधी जानकारी देखें और अपने CI में secrets और बिल्ड आर्टिफ़ैक्ट तक पहुँच भी तय करें।

GitHub Actions इस्तेमाल करते हैं तो MAILERA_API_KEY को secret के रूप में सहेजें और secrets context से वातावरण के चर में दें; GitHub की secrets इस्तेमाल करने की गाइड में इसका तरीका है।

वास्तविक OTP, पूरी API प्रतिक्रिया या ईमेल सामग्री लॉग न करें। विफलता में इतना लिखना पर्याप्त है कि समय-सीमा खत्म हुई, API अनुरोध विफल हुआ या लॉगिन assertion नहीं मिला। निदान के नाम पर पूरा response छापना जरूरी नहीं है।

जाँचें कि स्क्रीनशॉट, वीडियो, trace, नेटवर्क रिकॉर्ड और रिपोर्ट में कोड, Authorization header या सत्र डेटा दिखाई तो नहीं दे रहा है। केवल CI लॉग masking पर निर्भर न रहें। संवेदनशील चरणों की रिकॉर्डिंग बंद रखें, या उन्हें सहेजने से पहले साफ़ करने की व्यवस्था करें। यह भी तय करें कि उन्हें कौन देख सकता है और कितने समय तक रखा जाएगा।

सहेजी हुई प्रमाणीकरण स्थिति को भी secret की तरह रखें और रिपॉज़िटरी में न जोड़ें। OTP प्रवाह जाँचने वाले टेस्ट में वास्तविक लॉगिन रखें; दूसरे टेस्टों के लिए सत्र का पुनः उपयोग चुनें तो उसका संग्रह अलग और सुरक्षित रखें। key उजागर हो जाए तो उसे रद्द करें; रद्द key के अनुरोध तुरंत अस्वीकार होते हैं।