Locator API

Locator API является центральным инструментом для поиска и взаимодействия с элементами на веб-странице в Playwright. Он отличается от привычного метода page.$ тем, что предоставляет динамическую привязку к элементу, автоматически ожидает появление элемента и обеспечивает высокую стабильность тестов.

Принципы работы Locator

Locator представляет собой объект, который описывает путь к элементу, но не сам элемент. Это позволяет:

  • Отложенно выполнять действия: поиск элемента происходит только в момент взаимодействия.
  • Автоматически ожидать состояния: например, элемент появится или станет видимым.
  • Работать с группой элементов: Locator может представлять несколько совпадающих элементов.

Основные методы получения Locator:

const button = page.locator('button#submit'); 
const items = page.locator('.list-item');

Основные методы Locator

  1. locator.click([options]) Выполняет клик по элементу, ожидая, что он станет доступным.

    await page.locator('button#submit').click();

  2. locator.fill(value) Заполняет поле ввода текстом, очищая его перед этим.

    await page.locator('input[name="email"]').fill('test@example.com');

  3. locator.type(text, [options]) Симулирует ввод текста, оставляя существующее значение.

    await page.locator('input[name="password"]').type('123456');

  4. locator.check() / locator.uncheck() Работа с чекбоксами, автоматически ожидает доступность.

    await page.locator('input[type="checkbox"]').check();

  5. locator.selectOption(value) Выбор значения в селекте. Поддерживает строку, объект или массив.

    await page.locator('SELECT#country').selectOption('RU');

  6. locator.hover() Наведение мыши на элемент с автоматическим ожиданием видимости.

    await page.locator('.menu-item').hover();

  7. locator.scrollIntoViewIfNeeded() Прокрутка страницы до элемента, если он не видим.

    await page.locator('#footer').scrollIntoViewIfNeeded();

Работа с коллекциями элементов

Locator позволяет операции с множеством элементов, сохраняя удобный синтаксис:

  • locator.nth(index) – выбор конкретного элемента по индексу:

    await page.locator('.list-item').nth(2).click();

  • locator.first() / locator.last() – выбор первого или последнего элемента.

    await page.locator('.notification').first().click();

  • locator.count() – получение количества элементов.

    const itemCount = await page.locator('.list-item').count();

  • locator.filter(options) – фильтрация по тексту или видимости.

    await page.locator('.product').filter({ hasText: 'Playwright' }).click();

Локаторы по тексту и CSS

Playwright поддерживает гибкую систему селекторов:

  • CSS-селекторы

    const header = page.locator('header > h1');

  • Текстовые локаторы Автоматически ищут элемент с указанным текстом.

    await page.locator('text=Submit').click();

  • Комбинация селекторов Поддерживаются вложенные и сложные выражения.

    await page.locator('div.card >> text=Learn').click();

  • Атрибутные селекторы

    await page.locator('[data-test-id="login-button"]').click();

Локаторы с ожиданиями

Locator API интегрирован с механизмами ожидания состояний:

  • locator.waitFor() – ожидание появления элемента.

    await page.locator('#loading').waitFor({ state: 'hidden' });

  • Состояния:

    • visible – элемент отображается на странице
    • hidden – элемент скрыт или удалён
    • attached – элемент присутствует в DOM
    • detached – элемент отсутствует в DOM

Это позволяет избегать нестабильных тестов из-за асинхронной загрузки.

Вложенные локаторы

Locator API поддерживает цепочки локаторов:

const card = page.locator('.card').nth(1);
const buttonInCard = card.locator('button.buy');
await buttonInCard.click();

Такой подход повышает читаемость и снижает риск столкновения с другими элементами на странице.

Локаторы и ожидание действий

Locator автоматически ждёт готовности элемента для действия:

  • Клик будет ожидать появление и доступность элемента.
  • Заполнение формы не выполнится, пока поле не станет интерактивным.
  • Метод expect(locator).toHaveText() проверяет текст с ожиданием его появления.

Пример использования с expect:

import { expect } FROM '@playwright/test';

const message = page.locator('.alert');
await expect(message).toHaveText('Успешно сохранено');

Сравнение с page.$ и page.$$

  • page.$ возвращает снимок элемента на момент запроса, не отслеживает изменения DOM.
  • locator создаёт живую привязку, которая автоматически реагирует на динамические изменения страницы.
  • Это делает тесты более устойчивыми и уменьшает количество явных ожиданий (waitForSelector).

Использование в Page Object Model

Locator API идеально подходит для Page Object Model, так как локаторы можно хранить как свойства класса:

class LoginPage {
  constructor(page) {
    this.page = page;
    this.username = page.locator('#username');
    this.password = page.locator('#password');
    this.submitButton = page.locator('#submit');
  }

  async login(user, pass) {
    await this.username.fill(user);
    await this.password.fill(pass);
    await this.submitButton.click();
  }
}

Такой подход делает код тестов более читаемым и поддерживаемым.

Locator API — это мощный инструмент Playwright, который сочетает удобство поиска элементов, автоматическое ожидание и работу с динамическими страницами. Использование локаторов позволяет создавать стабильные, лаконичные и легко поддерживаемые тесты, минимизируя необходимость явных ожиданий и сложных проверок состояния DOM.

Оглавление