Как надёжно тестировать асинхронные почтовые сценарии с помощью Playwright expect.poll вместо фиксированных тайм-аутов.


1. Введение

Автоматизированные сквозные тесты (E2E), связанные с отправкой электронной почты, распространены в SaaS, электронной коммерции и системах управления идентификацией. Тест должен подтвердить, что тестируемая система (SUT) инициирует отправку письма и что содержимое этого письма соответствует критериям приёмки.

Поскольку доставка электронной почты проходит через внешние сервисы — SMTP-ретрансляторы, спам-фильтры и почтовых провайдеров, — момент появления письма в тестовом почтовом ящике непредсказуем. Жёстко заданный page.waitForTimeout(…), то есть фиксированное ожидание, делает тесты нестабильными: они либо напрасно ждут дольше необходимого, либо периодически завершаются сбоем, когда доставка занимает чуть больше заданного времени.

Playwright предоставляет примитив ожидания по условию expect.poll, который повторно вызывает пользовательскую функцию, пока проверка не будет пройдена или не истечёт тайм-аут. Сочетание expect.poll с небольшим адаптером почтового ящика, не зависящим от провайдера, позволяет создать детерминированный шаг проверки, который:

Ниже показано, как спроектировать такой тест, почему он предпочтительнее фиксированных ожиданий и какие практические аспекты — очистку, идемпотентность и интеграцию с CI — необходимо учитывать.


2. Доставка электронной почты как внешняя асинхронная граница

Когда пользователь нажимает «Сбросить пароль» или «Пригласить коллегу», SUT обычно ставит сообщение в очередь внешнего почтового сервиса, например SendGrid или Amazon SES. Затем сервис:

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

Каждый этап вносит задержку, которая не контролируется тест-раннером. Даже при использовании тестового почтового сервиса, например MailHog или Mailosaur, доставка по-прежнему включает асинхронную обработку. Поэтому тест должен ожидать выполнения условия — появления подходящего письма, — а не истечения заранее заданного времени.


3. Почему фиксированные ожидания (page.waitForTimeout) не подходят для рабочих автотестов

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

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

> В официальной документации описано повторное выполнение произвольной функции до успешного прохождения проверки с настраиваемыми интервалами и тайм-аутом.[1]


4. Playwright expect.poll — подходящий инструмент для задачи

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Определяет частоту опроса; интервал в 1 секунду обеспечивает баланс между нагрузкой на 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
Маркетинговая кампания (без влияния на UI)Низкий функциональный риск, но возможное искажение метрик60 с2 сНеобязательный неблокирующий smoke-тест

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


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) в пользу Playwright expect.poll, команды могут:

Адаптер, независимый от провайдера, обеспечивает переносимость тестового кода, а матрица рисков помогает выбирать подходящий тайм-аут. В сочетании с надёжной конфигурацией CI детерминированная проверка электронной почты становится важной частью современной стратегии автоматизации QA.


Источники

  1. Playwright Documentation – 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. Как в приведённом примере разделены проверка доставки и UI-проверка и почему это важно?
  5. Какие диагностические данные Playwright автоматически добавляет в отчёт о тестировании при истечении тайм-аута expect.poll?