prepareBrowser

Обзор

Данный параметр является хуком. Функция, заданная для данного параметра, будет автоматически вызвана перед тем, как запустить в браузере тесты. В качестве аргумента функция получает ссылку на сессию браузера.

Обычно внутри данной функции к браузеру добавляют новые команды, или расширяют поведение уже существующих команд.

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

Пример 1: добавляем новую команду для браузера

Для добавления новой команды воспользуемся функцией browser.addCommand().

testplane.config.ts

import type { ConfigInput } from "testplane";
import querystring from "querystring";

function toStoryKind(value) {
    /* here goes some code */
}
function toStoryId(value) {
    /* here goes some code */
}

export default {
    // ...
    prepareBrowser: function (browser) {
        browser.addCommand("openScenario", function openScenario(rawComponent, rawStory, params) {
            const component = toStoryKind(rawComponent);
            const story = toStoryId(rawStory);
            const queryParams = querystring.stringify(params);
            const url = `/storybook/iframe.html?id=components-${component}-testplane--${story}&${queryParams}`;

            return this.url(url);
        });
    },
} satisfies ConfigInput;

Пример 2: добавляем новую команду для элемента

Можно добавить команду не для браузера, а для элемента. Тогда третьим аргументом функции browser.addCommand() надо указать true.

warning

Если добавляется команда для элемента, а не для браузера, то функция выполняется в контексте элемента!

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;

Внутри функции применяются команды getLocation() и getSize(), которые доступны для элемента.

После добавления команды getCoords(), её можно использовать в тестах следующим образом:

const { left, top, right, bottom } = await browser.$(‘.selector’).getCoords();

Пример 3: меняем уже существующую команду

Чтобы изменить уже существующую команду, воспользуемся командой browser.overwriteCommand().

Например, мы можем захотеть передавать в команду browser.url() отдельным аргументом объект с query-параметрами:

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    // ...
    prepareBrowser: function (browser) {
        browser.overwriteCommand("url", function (origUrlFunction, uri, query) {
            if (!query) {
                return origUrlFunction(uri);
            }

            const parsedUrl = new URL(uri);

            for (const [key, value] of Object.entries(query)) {
                parsedUrl.searchParams.set(key, value);
            }

            return origUrlFunction(parsedUrl.href);
        });
    },
} satisfies ConfigInput;

Пример 4: добавляем набор команд из папки

Если в проекте много своих специфических команд, то их удобно хранить в отдельной папке, а в prepareBrowser добавлять все команды сразу унифицированным образом. Например:

testplane.config.ts

import type { ConfigInput } from "testplane";
import path from "path";
import glob from "fast-glob";

export default {
    // ...
    prepareBrowser: function (browser) {
        const files = glob.sync(["tests/testplane/commands/*.(js|ts)", "!**/*.d.ts"]);

        files.forEach(file => {
            const module = require(path.resolve(process.cwd(), file));
            const name = path.basename(file, path.extname(file));

            browser.addCommand(name, typeof module === "object" ? module[name] : module);
        });
    },
};

tests/testplane/commands/myCheckCookie.js

export default async function (cookieName) {
    const cookies = await this.getCookies(cookieName);

    assert.isTrue(cookies[0], `cookie named ${cookieName} is not set`);
}

Здесь используется команда browser.getCookies.