Документирование Page Objects

Page Object — это паттерн проектирования, который широко используется в автоматизированном тестировании для разделения логики тестов и взаимодействия с элементами веб-страницы. В WebdriverIO этот паттерн помогает сделать тесты более читаемыми, поддерживаемыми и масштабируемыми. Однако без должного документирования структура Page Object может стать сложной для понимания, что снизит её эффективность. В этой главе рассматриваются подходы к документированию Page Objects для улучшения взаимодействия с командой и поддержания качества тестов.

Структура Page Object

Page Object представляет собой класс, который инкапсулирует все элементы страницы и действия с ними. Такой подход позволяет организовать код таким образом, чтобы тесты использовали абстракцию страницы, а не прямое взаимодействие с элементами DOM. Документирование таких объектов важно для понимания их функциональности другими разработчиками и тестировщиками.

Основная структура Page Object обычно включает в себя:

  • Элементы страницы — это локаторы, с которыми необходимо взаимодействовать. Эти локаторы могут быть представлены в виде переменных или методов для получения доступа к элементам.
  • Действия с элементами — это методы, которые описывают поведение пользователя на странице, такие как клик, ввод текста, проверка видимости и т.д.
  • Проверки состояния — это методы для проверки состояния элементов или страницы, например, проверка текста на кнопке или статус элемента.

Пример структуры Page Object:

class LoginPage {
    // Элементы страницы
    get usernameInput() { return $('#username'); }
    get passwordInput() { return $('#password'); }
    get submitButton() { return $('#submit'); }
    get errorMessage() { return $('#error'); }

    // Действия с элементами
    open() {
        browser.url('/login');
    }

    login(username, password) {
        this.usernameInput.setValue(username);
        this.passwordInput.setValue(password);
        this.submitButton.click();
    }

    // Проверки состояния
    isErrorMessageVisible() {
        return this.errorMessage.isDisplayed();
    }
}

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

Документирование Page Object в WebdriverIO требует соблюдения нескольких принципов:

  1. Ясность и точность: Каждый метод должен быть документирован таким образом, чтобы любой разработчик мог быстро понять его назначение и способ использования.
  2. Чистота и краткость: Описание должно быть лаконичным, избегая излишних деталей, но при этом достаточно информативным, чтобы пояснить логику работы метода.
  3. Поддержка изменений: Документация должна легко обновляться, чтобы отражать изменения в UI или логике взаимодействия с элементами.

Пример документации для метода

Каждый метод, представляющий собой действие с элементом или проверку, должен содержать описание, объясняющее, что именно он делает, какие аргументы принимает и какие возвращаемые значения ожидаются.

Пример:

/**
 * Вводит значение в поле ввода имени пользователя.
 * @param {string} username — имя пользователя, которое будет введено в поле.
 */
login(username, password) {
    this.usernameInput.setValue(username);
    this.passwordInput.setValue(password);
    this.submitButton.click();
}

/**
 * Проверяет, отображается ли сообщение об ошибке.
 * @returns {boolean} true, если сообщение об ошибке отображается, иначе false.
 */
isErrorMessageVisible() {
    return this.errorMessage.isDisplayed();
}

Документирование локаторов

Локаторы элементов страницы — это ключевая часть Page Object. Они должны быть четко определены, чтобы избежать ошибок в тестах. Для каждого локатора важно документировать, что именно он представляет, чтобы улучшить понимание структуры страницы и связи между тестами и UI.

Пример:

// Локатор поля ввода имени пользователя
get usernameInput() {
    return $('#username'); // Поиск по ID элемента с именем 'username'
}

// Локатор кнопки отправки формы
get submitButton() {
    return $('#submit'); // Поиск по ID элемента с именем 'submit'
}

Использование комментариев

Комментарии в коде необходимы для пояснения более сложных участков логики. Это особенно важно, когда взаимодействие с элементами требует дополнительных шагов, например, при учёте динамических изменений UI или синхронизации с асинхронными процессами.

Пример:

/**
 * Открывает страницу авторизации.
 * Ожидает, что страница загрузится в течение 3 секунд.
 */
open() {
    browser.url('/login');
    browser.waitUntil(() => browser.getUrl() === 'https://example.com/login', {
        timeout: 3000,
        timeoutMsg: 'Страница авторизации не загрузилась за 3 секунды.'
    });
}

Документирование асинхронных методов

В WebdriverIO многие действия являются асинхронными, например, взаимодействие с элементами через методы WebDriver. Для асинхронных методов важно указать, как они обрабатывают ожидания, ошибки и тайм-ауты.

Пример документации для асинхронного метода:

/**
 * Вводит имя пользователя и пароль и отправляет форму.
 * Асинхронный метод, который выполняет действия с элементами на странице.
 * @param {string} username — имя пользователя.
 * @param {string} password — пароль пользователя.
 * @returns {Promise<void>} Промис, который разрешается после отправки формы.
 */
async login(username, password) {
    await this.usernameInput.setValue(username);
    await this.passwordInput.setValue(password);
    await this.submitButton.click();
}

Использование документации с примерами

Чтобы помочь другим разработчикам и тестировщикам понять, как использовать Page Object, полезно предоставить примеры. Это может быть полезно для вызова методов Page Object в тестах.

Пример:

const loginPage = new LoginPage();
loginPage.open();
loginPage.login('user123', 'password123');

// Проверка на наличие ошибки
const errorVisible = loginPage.isErrorMessageVisible();
console.log(`Ошибка отображается: ${errorVisible}`);

Автоматизация документации

Для упрощения процесса документирования можно использовать такие инструменты, как JSDoc, которые позволяют генерировать документацию напрямую из комментариев в коде. Это особенно полезно в больших проектах, где документация должна обновляться автоматически.

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

/**
 * Страница авторизации.
 * @class
 */
class LoginPage {
    /**
     * Локатор поля ввода имени пользователя.
     * @returns {WebdriverIO.Element} Элемент ввода имени пользователя.
     */
    get usernameInput() {
        return $('#username');
    }

    /**
     * Вводит имя пользователя в поле ввода.
     * @param {string} username — имя пользователя.
     */
    login(username, password) {
        this.usernameInput.setValue(username);
        this.passwordInput.setValue(password);
        this.submitButton.click();
    }
}

Заключение

Эффективное документирование Page Objects помогает улучшить качество тестов и облегчить работу в команде. Комментарии, примеры использования и четкая структура документации делают взаимодействие с кодом проще, что приводит к уменьшению ошибок и более быстрому освоению кода новыми разработчиками.

Оглавление