prepareBrowser

Overview

This parameter is a hook. The function specified for this parameter will be automatically called before running tests in the browser. The function receives a reference to the browser session as an argument.

Typically, new commands are added to the browser or the behavior of existing commands is extended within this function.

Usage Examples

Example 1: Adding a new command to the browser

To add a new command, use the browser.addCommand() function.

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;

Example 2: Adding a new command to an element

You can add a command not to the browser, but to an element. In this case, the third argument of the browser.addCommand() function should be set to true.

warning

If a command is added to an element, not to the browser, the function is executed in the context of the element!

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;

Inside the function, the commands getLocation() and getSize(), which are available for the element, are used.

After adding the getCoords() command, it can be used in tests as follows:

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

Example 3: Overwriting an existing command

To change an existing command, use the browser.overwriteCommand() command.

For example, we might want to pass an object with query parameters as a separate argument to the browser.url() command:

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;

Example 4: Adding a set of commands from a folder

If the project has many specific commands, it is convenient to store them in a separate folder, and add all commands at once in a unified manner in prepareBrowser. For example:

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`);
}

Here, the browser.getCookies command is used.