Як надійно тестувати асинхронні процеси надсилання електронної пошти за допомогою expect.poll у Playwright замість фіксованих тайм-аутів.
1. Вступ
Автоматизовані наскрізні тести (E2E), що передбачають надсилання електронного листа, поширені в SaaS, електронній комерції та системах керування ідентифікаційними даними. Тест має перевірити, що тестована система (SUT) ініціює надсилання листа, а його вміст відповідає критеріям приймання.
Оскільки електронна пошта проходить через зовнішні сервіси — SMTP-ретранслятори, спам-фільтри та провайдерів поштових скриньок, — неможливо точно передбачити, коли лист з’явиться в тестовій скриньці. Жорстко заданий виклик page.waitForTimeout(…), тобто фіксована пауза, призводить до нестабільних тестів: вони або марнують час, чекаючи довше, ніж потрібно, або періодично завершуються невдало, якщо доставка триває трохи довше за визначену затримку.
Playwright надає засіб очікування на основі умови — expect.poll. Він повторно виконує передану функцію, доки перевірка не завершиться успішно або не сплине тайм-аут. Поєднавши expect.poll із невеликим адаптером поштової скриньки, який не залежить від конкретного провайдера, можна створити детермінований етап перевірки, що:
- дотримується обмеженого загального тайм-ауту,
- опитує систему з налаштовуваним інтервалом,
- швидко завершується з корисною діагностикою в разі невдачі та
- залишається безпечним для паралельного виконання в CI.
У цьому посібнику показано, як спроєктувати такий тест, чому він кращий за фіксовані паузи та які практичні аспекти потрібно враховувати: очищення, ідемпотентність та інтеграцію з CI.
2. Доставка електронної пошти — зовнішня асинхронна межа
Коли користувач натискає «Скинути пароль» або «Запросити колегу», тестована система зазвичай ставить повідомлення в чергу зовнішнього поштового сервісу, наприклад SendGrid або Amazon SES. Після цього сервіс:
- Приймає запит через HTTP або SMTP.
- Виконує внутрішню постановку в чергу, обмеження частоти запитів і перевірки спам-фільтрів.
- Передає повідомлення поштовому провайдеру одержувача.
Кожен етап додає затримку, яка перебуває поза контролем засобу запуску тестів. Навіть у разі використання ізольованої тестової поштової скриньки, наприклад MailHog або Mailosaur, процес доставки все одно передбачає асинхронне оброблення. Тому тест має очікувати на виконання умови — появу відповідного листа, — а не чекати наперед визначений проміжок часу.
3. Чому фіксовані паузи (page.waitForTimeout) не підходять для робочих тестів
Документація Playwright прямо не рекомендує використовувати довільні очікування за часом у робочих тестових наборах, оскільки такі очікування за своєю природою нестабільні. Фіксована пауза:
- Блокує потік виконання тесту на весь заданий час, навіть якщо лист надійшов раніше.
- Маскує реальні помилки: тест може пройти лише тому, що пауза виявилася достатньо довгою, а не тому, що система спрацювала правильно.
- Збільшує тривалість виконання CI: довгі паузи накопичуються в багатьох тестах і сповільнюють отримання зворотного зв’язку.
В офіційній документації зазначено, що 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 }>;
}Чому це важливо:
- Незалежність від провайдера — той самий тестовий код працює з MailHog, Mailosaur або власною імітацією сервісу.
- Ізоляція — завдяки передаванню унікального
correlationId, наприклад UUID у заголовку листаX-Test-Id, кожен тест отримує лише власне повідомлення, що запобігає взаємному впливу тестів. - Ідемпотентність — методи очищення гарантують, що після невдалого тесту не залишаться сторонні повідомлення, здатні вплинути на наступні запуски.
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);
});Продемонстровані ключові моменти
- Ідентифікатор кореляції (
correlationId) ізолює повідомлення. - Обмежене опитування (
timeout: 20 s,interval: 500 ms). - Окремі перевірки одержувача, відправника, теми, вмісту й отриманого посилання.
- Необов’язкова перевірка інтерфейсу після переходу за посиланням чітко відокремлена від перевірки доставки.
- Очищення підтримує поштову скриньку в чистому стані під час паралельних запусків.
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 часто виконують багато тестів одночасно. Щоб тести не перехоплювали листи один одного:
- Унікальна вхідна скринька для кожного тесту — використовуйте підадресацію (
user+{runId}@domain) або окрему тестову поштову скриньку для кожного воркера. - Ідентифікатор кореляції у власному заголовку — якщо поштовий сервіс це дозволяє, додайте
X-Test-Id: {correlationId}; адаптер зможе фільтрувати повідомлення за цим заголовком. - Очищення перед тестуванням — викликайте
mailboxAdapter.purgeTestMessages(runId)на початку роботи кожного воркера, щоб забезпечити чисте середовище.
Ці кроки роблять тест детермінованим, навіть коли десятки воркерів опитують той самий сервіс поштової скриньки.
10. Матриця тестування поштових процесів з урахуванням ризиків
| Процес | Ризик, якщо лист не доставлено | Рекомендований тайм-аут | Інтервал опитування | Додаткова перевірка |
|---|---|---|---|---|
| Скидання пароля (один лист) | Користувач не може відновити доступ → значний вплив | 20 с | 500 мс | Перевірити формат токена |
| Вітальний лист (масове надсилання) | Негативне сприйняття бренду та затримка адаптації користувачів | 30 с | 1 с | Перевірити вибірку одержувачів |
| Рахунок із вкладенням у форматі PDF | Ризик порушення фінансових або юридичних вимог | 45 с | 1 с | Перевірити контрольну суму PDF |
| Код двофакторної автентифікації (TFA) | Блокування облікового запису | 15 с | 250 мс | Також перевірити резервне надсилання через SMS |
| Маркетингова кампанія (без впливу на інтерфейс) | Низький функціональний ризик, але можливе спотворення метрик | 60 с | 2 с | Необов’язкова неблокувальна смоук-перевірка |
Матриця допомагає командам визначити, як довго чекати на кожен процес з огляду на його вплив на бізнес і не витрачати зайвий час на сценарії з низьким ризиком.
11. Особливості CI та діагностика помилок
- Швидке завершення в разі невдачі — установлюйте загальний тайм-аут настільки низьким, наскільки дозволяє матриця ризиків; тривале очікування приховує регресії.
- Збирання артефактів — після спливання тайм-ауту збережіть останній
MailMessageабоnullі додайте його до звіту про тестування.testInfo.attachmentsу Playwright дає змогу зберігати JSON для подальшого аналізу. - Виявлення нестабільності — фіксуйте кількість спроб опитування. Раптове зростання може свідчити про уповільнення поштового сервісу на наступному етапі й бути підставою для тимчасового поміщення тесту в карантин.
- Обмеження ресурсів — якщо API поштової скриньки обмежує частоту запитів, налаштуйте інтервал опитування так, щоб уникнути відповідей із кодом 429.
Приклад додавання діагностичних даних:
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. Перелік перевірок для детермінованої перевірки електронної пошти
- [ ] Унікальний ідентифікатор кореляції додано до заголовка або вмісту листа.
- [ ] Адаптер поштової скриньки реалізує мінімальний контракт і передається в тест як залежність.
- [ ]
expect.pollвикористовується з явно заданимиtimeoutтаinterval. - [ ] Окремі перевірки охоплюють одержувача, відправника, тему, вміст, посилання та вкладення.
- [ ] Очищення видаляє тестове повідомлення або очищає тестову поштову скриньку після кожного запуску.
- [ ] Стратегію паралельної ізоляції — підадресацію або ідентифікатор запуску — впроваджено.
- [ ] Діагностичні дані про помилку — останнє повідомлення й кількість спроб опитування — додаються після спливання тайм-ауту.
- [ ] Тайм-аут CI узгоджено з тайм-аутом
expect.poll, щоб завдання не завершилося передчасно.
13. Де допомагає автоматизація
| Аспект | Ручний підхід | Автоматизований підхід (Playwright + expect.poll) |
|---|---|---|
| Виявлення доставки | Ручна перевірка вхідних повідомлень із затримкою через людський чинник | Детерміноване опитування та негайний зворотний зв’язок |
| Перевірка вмісту | Візуальна перевірка в поштовому клієнті | Програмні перевірки точних значень полів |
| Захист від регресій | Пропущені крайові випадки та непослідовне покриття | Відтворюваний тестовий набір, збережений у системі контролю версій |
| Масштабованість | Обмежена кількома тестувальниками | Паралельне виконання численних сценаріїв у CI |
| Діагностика | Несистемні скріншоти й нотатки | Структуровані вкладення, журнали опитувань і повідомлення про помилки |
Автоматизація не замінює ручну перевірку оформлення листів або юридичних текстів, але суттєво зменшує обсяг ручної роботи, потрібної для підтвердження правильної доставки й належного основного вмісту.
14. Висновок
Для тестування процесів, що залежать від електронної пошти, потрібна стратегія, яка враховує асинхронний характер доставки. Відмовившись від фіксованих пауз (page.waitForTimeout) на користь expect.poll у Playwright, команди можуть:
- Чекати лише стільки, скільки потрібно, зберігаючи швидкість CI.
- Отримувати в разі невдачі чіткі практичні діагностичні дані, скорочуючи час налагодження.
- Підтримувати ізоляцію паралельних запусків за допомогою ідентифікаторів кореляції та очищення поштових скриньок.
Шаблон адаптера, незалежного від провайдера, забезпечує переносимість тестового коду, а матриця з урахуванням ризиків допомагає вибрати належні тайм-аути. У поєднанні з надійною конфігурацією CI детермінована перевірка електронної пошти стає важливою складовою сучасної стратегії автоматизації QA.
Джерела
- Документація Playwright — Assertions — expect.poll. https://playwright.dev/docs/test-assertions#expectpoll
Запитання для рецензента
- Чим
expect.pollвідрізняється від простого циклуwhileзawait new Promise(r => setTimeout(r, …))з погляду звітності про помилки? - Чому додавання унікального ідентифікатора кореляції до листа необхідне для ізоляції паралельних тестів?
- Які параметри
expect.pollпотрібно налаштувати, якщо API поштової скриньки має суворі обмеження частоти запитів? - Як у наведеному прикладі відокремлено перевірку доставки від перевірки інтерфейсу користувача й чому це важливо?
- Які діагностичні дані Playwright автоматично додає до звіту про тестування, коли в
expect.pollспливає тайм-аут?

Залишити коментар
Поділіться думкою про статтю. Реєстрація не потрібна.
Коментарі
Завантаження коментарів…