Як надійно тестувати асинхронні процеси надсилання електронної пошти за допомогою expect.poll у Playwright замість фіксованих тайм-аутів.


1. Вступ

Автоматизовані наскрізні тести (E2E), що передбачають надсилання електронного листа, поширені в SaaS, електронній комерції та системах керування ідентифікаційними даними. Тест має перевірити, що тестована система (SUT) ініціює надсилання листа, а його вміст відповідає критеріям приймання.

Оскільки електронна пошта проходить через зовнішні сервіси — SMTP-ретранслятори, спам-фільтри та провайдерів поштових скриньок, — неможливо точно передбачити, коли лист з’явиться в тестовій скриньці. Жорстко заданий виклик page.waitForTimeout(…), тобто фіксована пауза, призводить до нестабільних тестів: вони або марнують час, чекаючи довше, ніж потрібно, або періодично завершуються невдало, якщо доставка триває трохи довше за визначену затримку.

Playwright надає засіб очікування на основі умови — expect.poll. Він повторно виконує передану функцію, доки перевірка не завершиться успішно або не сплине тайм-аут. Поєднавши expect.poll із невеликим адаптером поштової скриньки, який не залежить від конкретного провайдера, можна створити детермінований етап перевірки, що:

У цьому посібнику показано, як спроєктувати такий тест, чому він кращий за фіксовані паузи та які практичні аспекти потрібно враховувати: очищення, ідемпотентність та інтеграцію з CI.


2. Доставка електронної пошти — зовнішня асинхронна межа

Коли користувач натискає «Скинути пароль» або «Запросити колегу», тестована система зазвичай ставить повідомлення в чергу зовнішнього поштового сервісу, наприклад SendGrid або Amazon SES. Після цього сервіс:

  1. Приймає запит через HTTP або SMTP.
  2. Виконує внутрішню постановку в чергу, обмеження частоти запитів і перевірки спам-фільтрів.
  3. Передає повідомлення поштовому провайдеру одержувача.

Кожен етап додає затримку, яка перебуває поза контролем засобу запуску тестів. Навіть у разі використання ізольованої тестової поштової скриньки, наприклад MailHog або Mailosaur, процес доставки все одно передбачає асинхронне оброблення. Тому тест має очікувати на виконання умови — появу відповідного листа, — а не чекати наперед визначений проміжок часу.


3. Чому фіксовані паузи (page.waitForTimeout) не підходять для робочих тестів

Документація Playwright прямо не рекомендує використовувати довільні очікування за часом у робочих тестових наборах, оскільки такі очікування за своєю природою нестабільні. Фіксована пауза:

В офіційній документації зазначено, що page.waitForTimeout — це низькорівневий засіб для налагодження, а не для надійної автоматизації тестування. Натомість Playwright рекомендує очікування на основі умов, зокрема expect.poll: воно чекає лише стільки, скільки потрібно, і в разі невиконання умови в межах тайм-ауту завершується з чітким повідомленням.

> «Використовуйте expect.poll, щоб повторно виконувати довільну функцію, доки перевірка не завершиться успішно, із можливістю налаштувати тайм-аут та інтервали опитування». — документація Playwright щодо перевірок[1]


4. expect.poll у Playwright — належний інструмент для цього завдання

expect.poll працює як традиційний цикл очікування виконання умови, але інтегрується із засобом запуску тестів Playwright:

await expect.poll(async () => {
  // return a value that will be matched
  return await mailboxApi.fetchLatestMessage(correlationId);
}).toMatchObject({
  to: 'alice@example.com',
  subject: /Password reset/,
});

Основні характеристики:

МожливістьОпис
Інтервал опитуванняЗа замовчуванням Playwright використовує інтервали 100, 250, 500 і 1 000 мс; їх налаштовують через { intervals: number[] }.
Загальний тайм-аутДля expect.poll за замовчуванням становить 5 секунд; для поштового процесу явно задайте { timeout: number }.
Інтеграція з матчерамиМожна використовувати будь-який матчер Playwright: toBe, toContain, toMatchObject тощо.
Діагностика помилокПісля спливання тайм-ауту Playwright повідомляє останнє отримане значення, що полегшує налагодження.

Оскільки expect.poll є частиною бібліотеки перевірок Playwright, звіт містить відомості про перевірку та виклики. Якщо потрібна точна історія опитувань, додайте власний лічильник спроб.


5. Проєктування незалежного від провайдера адаптера поштової скриньки

Щоб тест можна було переносити між різними поштовими сервісами, приховайте зовнішній API за невеликим інтерфейсом TypeScript. Контракт має надавати лише операції, потрібні для перевірки:

export interface MailboxAdapter {
  /** Returns the most recent message that matches the supplied correlation identifier. */
  fetchLatestMessage(correlationId: string): Promise<MailMessage | null>;

  /** Deletes a message by its unique identifier – useful for cleanup. */
  deleteMessage(messageId: string): Promise<void>;

  /** Optionally, purges all test messages for a given run (idempotent). */
  purgeTestMessages(runId: string): Promise<void>;
}

/** Minimal shape of a mail message required for assertions. */
export interface MailMessage {
  id: string;
  to: string[];
  from: string;
  subject: string;
  htmlBody: string;
  textBody: string;
  attachments?: Array<{ filename: string; content: Buffer }>;
}

Чому це важливо:


6. Схема опитування: обмежені інтервали, загальний тайм-аут і кінцевий стан помилки

Нижче наведено повторно використовувану допоміжну функцію, яка поєднує адаптер з expect.poll:

import { expect } from '@playwright/test';
import { MailboxAdapter, MailMessage } from './mailboxAdapter';

export async function waitForEmail(
  adapter: MailboxAdapter,
  correlationId: string,
  {
    timeout = 30_000,          // total wait time (ms)
    interval = 1_000,          // poll every second
    failureMessage = 'Email not received',
  }: { timeout?: number; interval?: number; failureMessage?: string } = {}
): Promise<MailMessage> {
  let message: MailMessage | null = null;

  await expect.poll(
    async () => {
      message = await adapter.fetchLatestMessage(correlationId);
      return message;
    },
    {
      timeout,
      intervals: [interval],
      message: failureMessage,
    }
  ).toBeTruthy();

  // Playwright assertions resolve to void, so return the captured mailbox value.
  return message as MailMessage;
}

Пояснення параметрів

ПараметрПризначення
timeoutВерхня межа очікування, що відповідає допустимому рівню ризику тесту, наприклад 30 секунд для більшості SaaS-процесів.
intervalВизначає частоту опитування; інтервал в одну секунду забезпечує баланс між навантаженням на API поштової скриньки та затримкою виявлення.
failureMessageВласне повідомлення, яке з’являється у звіті Playwright після спливання тайм-ауту.

Якщо тайм-аут спливає, Playwright викидає AssertionError, що містить останнє значення, повернене fetchLatestMessage, зазвичай null. Це кінцевий стан помилки, який одразу підтверджує, що лист так і не надійшов.


7. Повний приклад: перевірка листа для скидання пароля

import { test, expect } from '@playwright/test';
import { waitForEmail } from './emailHelpers';
import { mailboxAdapter } from './mailboxAdapterImpl'; // concrete implementation

test('User can reset password via email link', async ({ page }) => {
  // 1️⃣ Trigger the flow in the UI
  await page.goto('https://app.example.com/login');
  await page.click('text=Forgot password');
  const correlationId = crypto.randomUUID(); // unique per test
  await page.fill('#email', `bob+${correlationId}@mail.test`);
  await page.click('button:has-text("Send reset link")');

  // 2️⃣ Wait for the email to appear
  const email = await waitForEmail(mailboxAdapter, correlationId, {
    timeout: 20_000,
    interval: 500,
  });

  // 3️⃣ Assert delivery metadata
  expect(email.to).toContain(`bob+${correlationId}@mail.test`);
  expect(email.from).toBe('no-reply@example.com');
  expect(email.subject).toMatch(/Password reset/i);

  // 4️⃣ Assert body content
  expect(email.htmlBody).toContain('Click the button below to reset your password');
  const resetLink = /https:\/\/app\.example\.com\/reset\?token=[\w-]+/.exec(email.htmlBody);
  expect(resetLink).not.toBeNull();

  // 5️⃣ Follow the link in a new page (optional UI verification)
  const [resetPage] = await Promise.all([
    page.context().waitForEvent('page'),
    page.evaluate((url) => window.open(url, '_blank'), resetLink![0]),
  ]);
  await expect(resetPage).toHaveURL(/\/reset\?token=/);
  await expect(resetPage.locator('h1')).toHaveText('Set a new password');

  // 6️⃣ Cleanup – delete the test email
  await mailboxAdapter.deleteMessage(email.id);
});

Продемонстровані ключові моменти


8. Оброблення вкладень і посилань

Якщо лист містить вкладення, наприклад рахунок у форматі PDF, або кілька посилань, що передбачають дію, розширте набір перевірок:

// Attachments
expect(email.attachments).toHaveLength(1);
expect(email.attachments![0].filename).toBe('invoice.pdf');

// Links – ensure they are absolute and point to the expected domain
const urls = Array.from(email.htmlBody.matchAll(/href="([^"]+)"/g), m => m[1]);
for (const url of urls) {
  expect(url).toMatch(/^https:\/\/app\.example\.com\//);
}

Оскільки адаптер поштової скриньки повертає необроблені частини MIME, тест може перевіряти двійковий вміст, наприклад контрольну суму, без використання інтерфейсу користувача.


9. Ізоляція паралельних тестів та ідемпотентність

Конвеєри CI часто виконують багато тестів одночасно. Щоб тести не перехоплювали листи один одного:

  1. Унікальна вхідна скринька для кожного тесту — використовуйте підадресацію (user+{runId}@domain) або окрему тестову поштову скриньку для кожного воркера.
  2. Ідентифікатор кореляції у власному заголовку — якщо поштовий сервіс це дозволяє, додайте X-Test-Id: {correlationId}; адаптер зможе фільтрувати повідомлення за цим заголовком.
  3. Очищення перед тестуванням — викликайте mailboxAdapter.purgeTestMessages(runId) на початку роботи кожного воркера, щоб забезпечити чисте середовище.

Ці кроки роблять тест детермінованим, навіть коли десятки воркерів опитують той самий сервіс поштової скриньки.


10. Матриця тестування поштових процесів з урахуванням ризиків

ПроцесРизик, якщо лист не доставленоРекомендований тайм-аутІнтервал опитуванняДодаткова перевірка
Скидання пароля (один лист)Користувач не може відновити доступ → значний вплив20 с500 мсПеревірити формат токена
Вітальний лист (масове надсилання)Негативне сприйняття бренду та затримка адаптації користувачів30 с1 сПеревірити вибірку одержувачів
Рахунок із вкладенням у форматі PDFРизик порушення фінансових або юридичних вимог45 с1 сПеревірити контрольну суму PDF
Код двофакторної автентифікації (TFA)Блокування облікового запису15 с250 мсТакож перевірити резервне надсилання через SMS
Маркетингова кампанія (без впливу на інтерфейс)Низький функціональний ризик, але можливе спотворення метрик60 с2 сНеобов’язкова неблокувальна смоук-перевірка

Матриця допомагає командам визначити, як довго чекати на кожен процес з огляду на його вплив на бізнес і не витрачати зайвий час на сценарії з низьким ризиком.


11. Особливості CI та діагностика помилок

Приклад додавання діагностичних даних:

test.afterEach(async ({}, testInfo) => {
  if (testInfo.status !== testInfo.expectedStatus) {
    const lastMessage = await mailboxAdapter.fetchLatestMessage(testInfo.title);
    await testInfo.attach('last-email', {
      body: JSON.stringify(lastMessage, null, 2),
      contentType: 'application/json',
    });
  }
});

12. Перелік перевірок для детермінованої перевірки електронної пошти


13. Де допомагає автоматизація

АспектРучний підхідАвтоматизований підхід (Playwright + expect.poll)
Виявлення доставкиРучна перевірка вхідних повідомлень із затримкою через людський чинникДетерміноване опитування та негайний зворотний зв’язок
Перевірка вмістуВізуальна перевірка в поштовому клієнтіПрограмні перевірки точних значень полів
Захист від регресійПропущені крайові випадки та непослідовне покриттяВідтворюваний тестовий набір, збережений у системі контролю версій
МасштабованістьОбмежена кількома тестувальникамиПаралельне виконання численних сценаріїв у CI
ДіагностикаНесистемні скріншоти й нотаткиСтруктуровані вкладення, журнали опитувань і повідомлення про помилки

Автоматизація не замінює ручну перевірку оформлення листів або юридичних текстів, але суттєво зменшує обсяг ручної роботи, потрібної для підтвердження правильної доставки й належного основного вмісту.


14. Висновок

Для тестування процесів, що залежать від електронної пошти, потрібна стратегія, яка враховує асинхронний характер доставки. Відмовившись від фіксованих пауз (page.waitForTimeout) на користь expect.poll у Playwright, команди можуть:

Шаблон адаптера, незалежного від провайдера, забезпечує переносимість тестового коду, а матриця з урахуванням ризиків допомагає вибрати належні тайм-аути. У поєднанні з надійною конфігурацією CI детермінована перевірка електронної пошти стає важливою складовою сучасної стратегії автоматизації QA.


Джерела

  1. Документація Playwright — Assertions — expect.poll. https://playwright.dev/docs/test-assertions#expectpoll

Запитання для рецензента

  1. Чим expect.poll відрізняється від простого циклу while з await new Promise(r => setTimeout(r, …)) з погляду звітності про помилки?
  2. Чому додавання унікального ідентифікатора кореляції до листа необхідне для ізоляції паралельних тестів?
  3. Які параметри expect.poll потрібно налаштувати, якщо API поштової скриньки має суворі обмеження частоти запитів?
  4. Як у наведеному прикладі відокремлено перевірку доставки від перевірки інтерфейсу користувача й чому це важливо?
  5. Які діагностичні дані Playwright автоматично додає до звіту про тестування, коли в expect.poll спливає тайм-аут?