JSDoc — это инструмент для автоматической генерации документации из комментариев, встроенных в код JavaScript. В процессе тестирования с WebdriverIO использование JSDoc позволяет значительно улучшить понимание тестовых скриптов, их поддержку и взаимодействие в команде разработчиков и тестировщиков. Это особенно важно при работе с большими проектами, где наличие хорошо документированного кода упрощает его понимание и поддержку.
JSDoc использует особую нотацию комментариев, которая позволяет добавлять аннотации к функциям, параметрам, возвращаемым значениям и классам. Аннотации JSDoc не влияют на выполнение программы, но служат для создания документации, а также могут использоваться IDE для предоставления подсказок и автозаполнения.
Пример базового комментария JSDoc для функции:
/**
* Выполняет клик по элементу.
*
* @param {WebdriverIO.Element} element - Элемент, по которому нужно кликнуть.
* @returns {Promise<void>} Возвращает промис.
*/
async function clickElement(element) {
await element.click();
}WebdriverIO предоставляет API для управления браузером и взаимодействия с элементами на веб-странице. Используя JSDoc, можно документировать вызовы методов и команды WebdriverIO, а также описывать сложные взаимодействия в тестах.
Для начала нужно правильно настроить комментарии к методам WebdriverIO, чтобы они были понятны и доступны для анализа.
/**
* Ожидает, пока элемент не станет видимым на странице.
*
* @param {WebdriverIO.Element} element - Элемент, для которого необходимо ожидание.
* @param {number} [timeout=5000] - Время ожидания в миллисекундах (по умолчанию 5 секунд).
* @returns {Promise<boolean>} Возвращает `true`, если элемент стал видимым, иначе `false`.
*/
async function waitForElementToBeVisible(element, timeout = 5000) {
try {
await element.waitForDisplayed({ timeout });
return true;
} catch (e) {
return false;
}
}Здесь используется аннотация @param, чтобы указать тип и
описание параметров, а также @returns, чтобы
документировать возвращаемое значение.
В JSDoc можно указать разные типы данных для аргументов и возвращаемых значений. Это важно для правильного восприятия кода другими разработчиками и тестировщиками.
String — строка.Number — число.Boolean — булевый тип.Object — объект.Array — массив.Promise — промис.Для WebdriverIO также можно использовать типы, специфичные для работы с элементами страницы:
WebdriverIO.Element — элемент, с которым можно
взаимодействовать.WebdriverIO.MultiElement — набор элементов, с которым
можно взаимодействовать.Пример:
/**
* Находит все элементы на странице по заданному селектору.
*
* @param {string} selector - Селектор для поиска элементов.
* @returns {Promise<WebdriverIO.Element[]>} Массив найденных элементов.
*/
async function findElementsBySelector(selector) {
const elements = await $$(selector);
return elements;
}В этом примере указывается, что функция возвращает массив элементов, с которыми можно работать.
Многие IDE (например, Visual Studio Code) поддерживают автозаполнение и подсказки для JSDoc-аннотаций. Это позволяет значительно ускорить процесс разработки, поскольку разработчик может легко узнать, какие параметры и возвращаемые значения ожидаются в тех или иных методах WebdriverIO. Также можно получать подробную информацию о типах данных.
Когда в коде используются JSDoc-выражения, IDE может показывать подсказки по параметрам и возвращаемым значениям:
/**
* Ожидает, пока элемент не станет кликабельным.
*
* @param {WebdriverIO.Element} element - Элемент, который нужно проверять.
* @returns {Promise<boolean>} Возвращает `true`, если элемент стал кликабельным, иначе `false`.
*/
async function waitForElementToBeClickable(element) {
try {
await element.waitForClickable();
return true;
} catch (e) {
return false;
}
}После того как JSDoc-аннотации добавлены в код, можно использовать инструмент JSDoc для автоматической генерации документации. Для этого необходимо установить JSDoc и настроить его для вашего проекта.
Для установки JSDoc используйте npm:
npm install --save-dev jsdocПосле установки можно запустить команду для генерации документации:
npx jsdoc путь/к/файламДокументация будет сгенерирована в формате HTML и сохранена в указанной директории. Это позволяет создавать подробные и доступные руководства для разработчиков и тестировщиков, используя аннотации, уже добавленные в код.
Использование JSDoc при написании тестов с WebdriverIO помогает не только организовать код, но и упростить его сопровождение. Например, если проект включает множество тестов, использование JSDoc позволяет быстро понять, какие методы и функции выполняют те или иные действия. Это помогает в обучении новых членов команды, улучшении качества кода и снижении вероятности ошибок.
В тестах JSDoc полезен для следующих целей:
waitForDisplayed, click, getText
и т. д.)./**
* Тестирует страницу входа.
*
* @param {string} username - Имя пользователя для входа.
* @param {string} password - Пароль для входа.
* @returns {Promise<void>} Возвращает промис.
*/
async function testLogin(username, password) {
const loginButton = await $('#loginButton');
const usernameInput = await $('#username');
const passwordInput = await $('#password');
await usernameInput.setValue(username);
await passwordInput.setValue(password);
await loginButton.click();
const errorMessage = await $('#errorMessage');
await errorMessage.waitForDisplayed({ timeout: 5000 });
expect(await errorMessage.getText()).toBe('Неверный логин или пароль');
}В этом примере добавлены аннотации для входных параметров и возвращаемого значения функции. Это помогает другим разработчикам быстрее понять, как использовать данную функцию и какие параметры ей передавать.
Интеграция JSDoc в процесс разработки тестов с WebdriverIO значительно упрощает поддержку и расширение тестов. Использование аннотаций помогает не только улучшить документацию, но и повысить читаемость кода, минимизировать ошибки и ускорить работу команды. JSDoc является мощным инструментом для создания качественного, понятного и поддерживаемого кода, что особенно важно при работе с автоматизированным тестированием.