Перейти к основному содержимому

Кастомные команды

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

Что вы узнаете
  • Как добавлять пользовательские команды в объект браузера.
  • Как добавлять пользовательские команды в элементы.
  • Способы переопределения существующих команд.
  • Как использовать кастомные команды вместе с TypeScript.

Добавление пользовательских команд в объект браузера​

подсказка

Отличное место для добавления всех ваших пользовательских команд — хук prepareBrowser.

Чтобы добавить пользовательскую команду в объект browser, используйте метод addCommand. Так можно определить команду, которая получает URL и заголовок текущей страницы:

browser.addCommand("getUrlAndTitle", async function () {
    // this в контексте кастомных команд указывает на объект браузера
    return {
        url: await this.getUrl(),
        title: await this.getTitle(),
    };
});

Затем вы можете использовать эту пользовательскую команду в своих тестах:

it("should fetch URL and title", async function () {
    const result = await browser.getUrlAndTitle();
    console.log(result); // { url: 'https://example.com', title: 'Example Domain' }
});

Добавление пользовательских команд к элементам​

Пользовательские команды также можно добавлять к экземплярам элементов. Например, для создания команды, которая получает позицию элемента:

testplane.config.ts
import type { ConfigInput } from "testplane";

export default {
    // ...
    prepareBrowser: function (browser) {
        browser.addCommand(
            "getCoords",
            async function () {
                const { x, y } = await this.getLocation();
                const { width, height } = await this.getSize();

                return {
                    left: x,
                    top: y,
                    right: x + width,
                    bottom: y + height,
                };
            },
            true, // true = element command, false = browser command
        );
    },
} satisfies ConfigInput;

Обратите внимание, что третий параметр установлен в true — это означает, что команда должна быть добавлена к экземплярам элементов.

Переопределение существующих команд​

В некоторых случаях может потребоваться изменить поведение существующих команд. Testplane позволяет переопределять эти команды с помощью метода overwriteCommand. Например, так можно добавить логирование к команде click:

browser.overwriteCommand("click", async function (this: WebdriverIO.Element, origClick, options) {
    console.log("Element clicked:", this.selector);
    await origClick(options);
});

В этом примере перед выполнением оригинальной функции click в консоль выводится сообщение.

Использование пользовательских команд с TypeScript​

Чтобы TypeScript распознавал ваши пользовательские команды, необходимо дополнить типы WebdriverIO. Для этого выполните следующие шаги:

  1. Создайте файл custom-commands.d.ts в своем проекте.

  2. Убедитесь, что компилятор TypeScript "видит" этот файл во время сборки: возможно, потребуется включить его в tsconfig.json.

  3. Определите типы следующим образом. Обратите внимание, что в TypeScript есть два контекста файлов: module и ambient. Если в файле есть хотя бы один import/export, он находится в "module" режиме, иначе — в ambient. Выберите стиль объявления соответственно.

import 'webdriverio'; // Может быть любой импорт, не обязательно webdriverio

declare global {
    declare namespace WebdriverIO {
        interface Browser {
            customCommand: (arg: any) => Promise<void>
        }

        interface Element {
            elementCustomCommand: (arg: any) => Promise<void>
        }
    }
}

Это объявление расширяет интерфейсы Browser и Element, включая ваши пользовательские команды, позволяя TypeScript распознавать их без ошибок.