Test use options

Урок: use, проекты и test.use — настройки контекста и страницы

Введение

Когда ты пишешь тесты в Playwright, кажется, что всё крутится вокруг page: открыть страницу, кликнуть, проверить. Но довольно быстро возникает вопрос — а в каких условиях эта страница работает?

Например:

  • в каком браузере открывается тест;
  • какой у него размер окна;
  • авторизован ли пользователь;
  • какие заголовки отправляются в запросах;
  • какой базовый URL используется.

Если эти вещи настраивать внутри каждого теста — код быстро превратится в хаос. Тесты станут длинными, повторяющимися и сложными для поддержки.

Именно здесь появляются три важных инструмента Playwright:

  • use — задаёт общие настройки для тестов;
  • projects — позволяет запускать тесты в разных конфигурациях;
  • test.use — позволяет точечно изменить настройки для конкретного теста или файла.

Если упростить:

  • use — базовые условия для всех;
  • projects — разные «варианты окружения»;
  • test.use — локальное переопределение.

Давай разберёмся по шагам.

Что такое use: настройки по умолчанию

use — это раздел в конфигурации, где задаются параметры браузера, контекста и страницы.

Пример:

import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    baseURL: 'http://localhost:3000',
    headless: true,
    viewport: { width: 1280, height: 720 },
  },
});

Что происходит:

  • все тесты автоматически получают эти настройки;
  • Playwright применяет их при создании браузерного контекста и страницы.

Разберём параметры

baseURL Позволяет писать:

await page.goto('/');

вместо полного URL.

headless Определяет, будет ли браузер видимым.

viewport Размер окна браузера.

Почему это важно

Без use:

await page.goto('http://localhost:3000');
await page.setViewportSize({ width: 1280, height: 720 });

С use:

await page.goto('/');

Ты убираешь лишний код из тестов и переносишь его в конфигурацию.

Как use связан с контекстом и страницей

Важно понять, где именно применяются настройки.

Playwright создаёт:

  1. браузер;
  2. браузерный контекст (BrowserContext);
  3. страницу (page).

use применяется именно на уровне контекста и страницы.

Это значит:

  • настройки действуют для каждого теста;
  • каждый тест получает «своё чистое окружение».

Например:

use: {
  storageState: 'storageState.json',
}

Это значит:

  • каждый тест будет начинаться уже с авторизацией;
  • потому что контекст создаётся с этим состоянием.

Что такое projects: разные конфигурации

Теперь представим, что тебе нужно:

  • запускать тесты в Chrome и Firefox;
  • проверять мобильную версию;
  • запускать тесты с авторизацией и без неё.

Один use тут уже не справится.

Для этого есть projects.

Пример

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: { browserName: 'chromium' },
    },
    {
      name: 'firefox',
      use: { browserName: 'firefox' },
    },
  ],
});

Что происходит:

  • Playwright запускает тесты дважды;
  • один раз в Chromium;
  • второй — в Firefox.

Более реальный пример

projects: [
  {
    name: 'desktop',
    use: {
      viewport: { width: 1280, height: 720 },
    },
  },
  {
    name: 'mobile',
    use: {
      ...devices['iPhone 13'],
    },
  },
];

Здесь:

  • один проект — десктоп;
  • второй — мобильный.

Оператор ... (spread) разворачивает готовую конфигурацию устройства.

Как projects и use работают вместе

Очень важный момент:

  • use на верхнем уровне — базовый;
  • use внутри project — переопределяет его.

Пример:

export default defineConfig({
  use: {
    baseURL: 'http://localhost:3000',
  },

  projects: [
    {
      name: 'mobile',
      use: {
        viewport: { width: 375, height: 812 },
      },
    },
  ],
});

Что будет:

  • baseURL возьмётся из глобального use;
  • viewport — из проекта.

То есть настройки наследуются и дополняются.

test.use: локальные изменения

Иногда нужно изменить настройки только для одного теста.

Например:

  • один тест должен быть неавторизованным;
  • другой — с другим viewport;
  • третий — с другим storageState.

Для этого используется test.use.

Пример

import { test } from '@playwright/test';

test.use({
  storageState: 'no-auth.json',
});

test('гость видит страницу логина', async ({ page }) => {
  await page.goto('/profile');
});

Здесь:

  • только этот файл (или блок тестов) использует no-auth;
  • остальные тесты продолжают использовать глобальную настройку.

Локальное изменение внутри одного теста

Можно пойти ещё точнее:

test('другой viewport', async ({ page }) => {
  // обычный тест
});

test.use({
  viewport: { width: 500, height: 800 },
});

test('мобильный тест', async ({ page }) => {
  await page.goto('/');
});

Но чаще используют test.describe.

test.describe + test.use

Очень удобный способ сгруппировать тесты с одинаковыми настройками:

import { test } from '@playwright/test';

test.describe('мобильные тесты', () => {
  test.use({
    viewport: { width: 375, height: 812 },
  });

  test('проверка меню', async ({ page }) => {
    await page.goto('/');
  });

  test('проверка кнопки', async ({ page }) => {
    await page.goto('/');
  });
});

Что здесь важно:

  • test.use применяется только внутри describe;
  • остальные тесты не затрагиваются.

Приоритет настроек (очень важно)

Playwright применяет настройки в таком порядке:

  1. глобальный use
  2. use внутри project
  3. test.use

То есть:

более локальные настройки всегда важнее

Пример:

// config
use: {
  viewport: { width: 1280, height: 720 },
}

// project
use: {
  viewport: { width: 800, height: 600 },
}

// test
test.use({
  viewport: { width: 375, height: 812 },
});

Итог:

  • тест будет использовать 375x812

Это критически важно понимать, иначе можно запутаться, откуда берётся поведение теста.

Практический смысл

Теперь соберём всё вместе.

use:

  • убирает дублирование;
  • задаёт базовые условия;
  • делает тесты чище.

projects:

  • позволяют запускать тесты в разных окружениях;
  • дают масштабирование (браузеры, устройства, роли).

test.use:

  • даёт гибкость;
  • позволяет менять настройки точечно;
  • делает тесты независимыми.

В реальных проектах это используется постоянно:

  • один проект — авторизованный пользователь;
  • второй — гость;
  • третий — мобильный;
  • внутри тестов — точечные изменения.

Итоговое понимание

Главная идея этой темы в том, что Playwright разделяет логику теста и условия его выполнения.

use, projects и test.use — это инструменты управления этими условиями.

Ты один раз задаёшь базовую среду, при необходимости создаёшь разные варианты окружения через проекты и, если нужно, локально переопределяешь настройки для конкретных тестов.

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