browsers

Обзор

Раздел browsers является обязательным в настройках Testplane. В нем задаются все браузеры, в которых будут запускаться тесты.

Настройка

Данный раздел имеет следующий формат:

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    browsers: {
        "<browser-id>": {
            desiredCapabilities: {
                browserName: "<browser-name>",
                // ...
            },
            // ...
        },
    },
} satisfies ConfigInput;

Где <browser-id> — это имя браузера, которое используется для его идентификации.

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

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    sessionsPerBrowser: 10,
    browsers: {
        chrome: {
            /* ... */
        },
        firefox: {
            // ...
            sessionsPerBrowser: 5,
        },
    },
} satisfies ConfigInput;

В этом примере для браузера chrome будет использовано значение 10 для опции sessionsPerBrowser, а для firefox — 5.

Основные настройки браузера

Параметр	Тип	По умолчанию	Описание
desiredCapabilities	DesiredCapabilities	N/A	Обязательный параметр. Определяет свойства, которыми должен обладать браузер. Используется WebDriver'ом, см. DesiredCapabilities.
gridUrl	string	"http://localhost :4444/wd/hub"	URL грида Selenium.
baseUrl	string	"http://localhost"	Базовый URL тестируемого сервиса.
browserWSEndpoint	string	null	Эндпойнт websocket-соединения для подключения к браузеру через Chrome DevTools Protocol (CDP).
automationProtocol	string	"webdriver"	Протокол общения с браузером. См. WebDriver vs CDP.
sessionEnvFlags	SessionEnvFlags	{}	Флаги окружения, задающие протокол, который будет использоваться в созданной сессии браузера.
windowSize	string | WindowSize	null	Размеры окна браузера.
headless	boolean | "new" | "old"	depends on browser	Позволяет запускать браузер в headless режиме.

desiredCapabilities

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

Формат объекта desiredCapabilities определяется стандартом WebDriver.

Помимо стандартных опций ряд инструментов предоставляют специфичные в своих неймспейсах.

Опции, специфичные для браузеров:

• Chrome, goog:chromeOptions — документации по опциям ChromeDriver
• Firefox, moz:firefoxOptions — документации по Geckodriver
• Edge, ms:edgeOptions — документации по EdgeDriver

Опции, специфичные для браузерных гридов:

• Sauce Labs, sauce:options — документация
• BrowserStack, bstack:options — документация
• TestingBot, tb:options — документация

Опции, специфичные для некоторых инструментов автоматизации:

• Appium, appium:* — документация
• Selenoid, selenoid:options — документация

Пример расширенного задания desiredCapabilities:

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    browsers: {
        chrome: {
            desiredCapabilities: {
                browserName: "chrome",
                browserVersion: "125.0",
                "goog:chromeOptions": {
                    args: ["--hide-scrollbars", "--headless=new"],
                },
            },
        },
    },
} satisfies ConfigInput;

gridUrl

URL грида (адрес, на котором слушает ChromeDriver/Selenium Standalone/Sauce Labs/и т.д.).

По умолчанию: http://localhost:4444/wd/hub.

к сведению

Также можно использовать значение "local", чтобы запускать тесты на локальных браузерах, управляемых Testplane. Читайте больше в рецепте Как запустить Testplane в локальном браузере.

baseUrl

Базовый URL тестируемого сервиса. Позволяет более удобно использовать команды browser.url:

• если целевой адрес начинается с /, в начало будет добавлен baseUrl без path-части.
• если целевой адрес не начинается с /, в начало будет добавлен весь baseUrl.
• важно наличие или отсутствие / в конце. [Подробнее][url-resolve].

По умолчанию: http://localhost.

browserWSEndpoint

Эндпойнт websocket-соединения для подключения к браузеру через Chrome DevTools Protocol (CDP). Например, вы указываете browserWSEndpoint: "ws://YOUR_HOST/devtools", к которому в конце будет добавлен идентификатор сеанса браузера: ws://YOUR_HOST/devtools/12345, где 12345 — это идентификатор сеанса.

Значение по умолчанию: null. Означает, что Testplane попытается самостоятельно определить эндпойнт для веб-сокета.

automationProtocol

Протокол общения с браузером. Доступные значения: webdriver и devtools. См. также WebDriver vs CDP. По умолчанию: webdriver.

sessionEnvFlags

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

Доступные флаги:

Флаг	Протоколы
isW3C	WebDriverProtocol или по умолчанию JsonWProtocol
isChrome	ChromiumProtocol
isMobile	MJsonWProtocol и AppiumProtocol
isSauce	Команды конкретного поставщика Sauce Labs
isSeleniumStandalone	Специальные команды для Selenium при запуске тестов в Selenium Grid или с помощью Selenium Standalone Server.

Например:

testplane.config.ts

import type { ConfigInput } from "testplane";

export default {
    browsers: {
        "chrome-phone": {
            // ...
            sessionEnvFlags: {
                isMobile: true,
            },
        },
    },
} satisfies ConfigInput;

windowSize

Размеры окна браузера. Если не указывать, то размер окна будет зависеть от WebDriver'а. Можно указывать как строку, например, 800x1000 или как объект с ключами width и height, значениями которых нужно указать целые числа.

Например:

const browserOptions = {
    windowSize: "800x1000",
};

и

const browserOptions = {
    windowSize: {
        width: 800,
        height: 1000,
    },
};

эквивалентны между собой.

warning

Настройка разрешения для браузера Opera или для мобильных браузеров не работает, так как эти браузеры используют только полноэкранный режим.

headless

Позволяет управлять запуском браузера в headless режиме (без видимого отображения браузера). Можно задавать как boolean значение, а с Chrome версии 112 — можно задавать как строку "new" | "old". Подробнее про новый headless режим — в блоге Chrome.

По умолчанию: null (определяется на стороне браузера).

Таймауты

Параметр	Тип	По умолчанию	Описание
waitTimeout	number	3000	Таймаут для событий на веб-странице, в мс.
waitInterval	number	500	Интервал для событий на веб-странице, в мс.
httpTimeout	number	30000	Таймаут для любых запросов к Selenium-серверу, в мс.
urlHttpTimeout	number	= httpTimeout	Таймаут для запроса /url к Selenium-серверу, в мс.
pageLoadTimeout	number	20000	Таймаут для полной загрузки страницы, в мс.
sessionRequestTimeout	number	= httpTimeout	Таймаут запроса сессии браузера, в мс.
sessionQuitTimeout	number	5000	Таймаут для завершения сессии, в мс.
testTimeout	number	null	Таймаут для прогона теста, в мс. Если значение не задано, то будет использован общий таймаут для всех браузеров, который задается настройкой system.mochaOpts.timeout.

waitTimeout

Таймаут для событий на веб-странице, в миллисекундах. По умолчанию: 3000 мс (3 секунды).

Применяется в команде waitUntil, которая используется во всех waitFor*-командах при поиске заданного элемента на странице.

Например, при выполнении команды browser.$('.element').click() подкоманда $('element') будет по умолчанию ждать существования элемента до 3000 мс, прежде чем кликнуть по нему.

waitInterval

Интервал для событий на веб-странице, в миллисекундах. По умолчанию: 500 мс.

Применяется в команде waitUntil, которая используется во всех waitFor*-командах при поиске заданного элемента на странице.

Например, при выполнении команды browser.$('.element').click() подкоманда $('element') будет по умолчанию проверять существование элемента каждые 500 мс.

httpTimeout

Таймаут для любых запросов к Selenium-серверу, в миллисекундах. По умолчанию: 30000 мс.

urlHttpTimeout

Таймаут для запроса /url к Selenium-серверу, в миллисекундах. Иногда при открытии ссылки на стороне сервера выполняется масса логики в мидлварах, из-за чего ссылка долго открывается. Чтобы не поднимать из-за этого таймаут для всех команд, Testplane позволяет настроить отдельный таймаут для запроса /url.

pageLoadTimeout

Таймаут для полной загрузки страницы, в миллисекундах. По умолчанию: 20000 мс.

sessionRequestTimeout

Таймаут для запроса сессии браузера, в миллисекундах. По умолчанию берет значение настройки httpTimeout.

sessionQuitTimeout

Таймаут для завершения сессии, в миллисекундах. По умолчанию: 5000 мс.

testTimeout

Таймаут для прогона теста, в миллисекундах. При использовании для набора тестов (suite), будет применяться для всех тестов и хуков внутри этого набора тестов.

Если значение не задано, то будет использован общий таймаут для всех браузеров, который задается настройкой system.mochaOpts.timeout.

Запуск тестов

Параметр	Тип	По умолчанию	Описание
sessionsPerBrowser	number	1	Число сессий, которые будут запущены одновременно для конкретного браузера.
testsPerSession	number	Infinity	Сколько тестов можно запускать последовательно в одной сессии браузера. Параметр ограничивает переиспользование сессии, чтобы не допустить падения тестов из-за деградации браузера, и не имеет отношения к параллельному запуску тестов.
retry	number	0	Сколько раз нужно перезапускать падающий тест.
shouldRetry	(data: FailedTestData) => boolean	см. описание	Функция, которая определяет нужен ли ретрай. По умолчанию задается функция, которая возвращает true, если retry > 0, и false, если retry == 0.
strictTestsOrder	boolean	false	Гарантировать строгий порядок тестов. Если true, то функция API testplane.readTests будет всегда возвращать один и тот же результат.
passive	boolean	false	Позволяет сделать браузер пассивным. В пассивных браузерах тесты не запускаются по умолчанию. Доступна с testplane@8.16.0. Внимание: есть ограничения, см. ниже.
openAndWaitOpts	OpenAndWaitOpts	см. описание	Позволяет задать дефолтные опции для команды browser.openAndWait.
isolation	boolean	true для Chrome 93+	Включает режим изоляции с помощью браузерных контекстов.

sessionsPerBrowser

Число сессий, которые будут запущены одновременно для конкретного браузера. По умолчанию: 1.

testsPerSession

Параметр определяет сколько тестов можно запускать последовательно в одной сессии браузера. Может быть полезно, чтобы ограничить переиспользование сессии. Если одну и ту же сессию браузера использовать много раз для прогона различных тестов, то в какой-то момент браузер может начать деградировать. И это начнет влиять на прогон тестов, приводя к их падениям. После того как будет достигнут лимит тестов, сессия будет закрыта и запустится новая сессия.

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

warning

Будьте внимательны: данный параметр не имеет отношения к параллельному запуску тестов.

retry

Сколько раз нужно запустить тест снова, если он будет падать. По умолчанию: 0.

shouldRetry

Функция, которая определяет нужен ли ретрай. Должна возвращать значение типа Boolean. По умолчанию задается функция, которая возвращает true, если ещё остались доступные ретраи, и false, если достигнут предел ретраев для теста (см. настройку retry).

Аргументом данной функции является объект со следующими полями:

interface FailedTestData {
    ctx: {
        id(): string;
        browserId: string;
        sessionId: string;
    };
    retriesLeft: number;
    error?: Error;
}

strictTestsOrder

Данная опция включает гарантию строгого порядка чтения тестов. По умолчанию: false.

passive

warning

Доступна с testplane@8.16.0.

В данный момент эта опция не работает с html-reporter. В данный момент мы рекомендуем продолжить использовать плагин hermione-passive-browsers. Обратите внимание, что нельзя использовать плагин и эту опцию одновременно. Мы уже работаем над исправлением проблемы.

Позволяет сделать браузер пассивным. В пассивных браузерах тесты не запускаются по умолчанию. С помощью хелпера testplane.also.in можно включить тест или сьют, перед которым он указан.

По умолчанию: false.

openAndWaitOpts

Позволяет задать опции, которые нужно использовать при вызове команды browser.openAndWait.

По умолчанию:

const defaultOpenAndWaitOpts = {
    waitNetworkIdle: true,
    waitNetworkIdleTimeout: 500,
    failOnNetworkError: true,
    ignoreNetworkErrorsPatterns: [],
};

isolation

Включает запуск тестов в изолированных браузерных контекстах. Это означает, что testsPerSession может быть задан Infinity, чтобы запускать все тесты в одной сессии и значительно ускорить прогон тестов.

Работает начиная с Chrome 93 и выше.

По умолчанию: true для Chrome 93 и выше, false иначе.

Информация о тесте и падении

Параметр	Тип	По умолчанию	Описание
meta	Record<string, any>	N/A	Дополнительные данные, которые будут возвращаться командой getMeta().
takeScreenshotOnFails	ScreenshotOnFails	{ testFail: true, assertViewFail: true }	Определяет снимать ли скриншот страницы браузера (Page Screenshot) при падении теста, а также при падении команды assertView.
takeScreenshotOnFailsMode	"viewport" | "fullpage"	"fullpage"	Режим снятия скриншота при падении теста.
takeScreenshotOnFailsTimeout	number	5000	Таймаут для снятия скриншота страницы браузера (Page Screenshot) при падении теста, в мс.
saveHistoryMode	"all" | "none" | "onlyFailed"	"all"	Сохранять историю всех выполненных команд.

meta

Дополнительные данные, которые будут возвращаться командой getMeta(). Данные можно добавлять также «на лету» с помощью команды setMeta(): до, во время или после завершения прогона теста.

takeScreenshotOnFails

Опция задается в виде объекта:

interface ScreenshotOnFails {
    testFail: boolean;
    assertViewFail: boolean;
}

Данные ключи определяют нужно ли снимать скриншот страницы браузера (Page Screenshot) при падении теста и при падении команды assertView соответственно. В случае testFail учитываются все падения тестов кроме падений из-за команд assertView.

По умолчанию: { testFail: true, assertViewFail: true }.

takeScreenshotOnFailsMode

Режим снятия скриншота страницы браузера при падении теста. Доступные значения: viewport и fullpage:

• viewport — снять скриншот текущего вьюпорта.
• fullpage — снять скриншот всей страницы браузера.

По умолчанию: fullpage.

takeScreenshotOnFailsTimeout

Таймаут для снятия скриншота страницы браузера при падении теста, в миллисекундах. По умолчанию: 5000 мс.

saveHistoryMode

warning

Доступна с hermione@7.

Сохранять историю всех выполненных команд. По умолчанию: all.

Доступные значения:

• all — история включена.
• none — история отключена.
• onlyFailed — история сохраняется только для упавших тестов.

Некоторые плагины могут полагаться на эту историю, например, html-reporter.

История доступна из следующих событий — TEST_END, TEST_PASS, TEST_FAIL — через payload. Пример плагина, который использует историю:

exports = testplane => {
    testplane.on(testplane.events.TEST_PASS, async test => {
        console.log(test.history);
    });
};

Подготовка к снятию скриншотов

Параметр	Тип	По умолчанию	Описание
calibrate	boolean	false	Выполнять калибровку перед снятием скриншота.
orientation	string	null	Ориентация окна браузера, которую нужно выставлять перед запуском каждого теста.
waitOrientationChange	boolean	true	Ждать реальной смены ориентации.
resetCursor	boolean	true	Перемещать курсор в точку (0, 0) в координатах body перед каждым запуском теста.
screenshotsDir	string | (test: Test) => string	"./testplane/screens"	Папка для сохранения эталонных скриншотов командой assertView. По умолчанию testplane/screens относительно рабочей папки: process.cwd().

calibrate

Выполнять калибровку перед снятием скриншота. В некоторых реализациях WebDriver'а при снятии скриншота на изображение могут попадать элементы UI самого браузера. Калибровка позволяет решить данную проблему. По умолчанию: false.

orientation

Ориентация окна браузера, которую нужно выставлять перед запуском каждого теста. Доступные значения: landscape, portrait, null. По умолчанию: null.

Какое значение выбрать для orientation?

Это зависит от того, в какой ориентации у вас выполняется большинство тестов. Если большая часть тестов у вас выполняется в режиме landscape, то и значение orientation нужно выставлять в landscape. Тогда тесты, которым нужна ориентация portrait, будут самостоятельно выставлять нужную им ориентацию. А опция orientation будет гарантировать, что для всех остальных тестов ориентация будет выставлена в landscape автоматически перед их запуском, без необходимости задавать её в каждом тесте самостоятельно.

waitOrientationChange

Ждать реальной смены ориентации. По умолчанию: true. При установке в значение true testplane гарантирует, что команда задания ориентации setOrientation будет завершаться только после реального изменения ориентации на заданную.

resetCursor

Перемещать курсор в точку (0, 0) в координатах body перед каждым запуском теста. По умолчанию: true. Может потребоваться в тех случаях, когда положение курсора по умолчанию влияет на выполнение тестов. Например, когда из-за курсора всплывает какая-нибудь подсказка (hint), которая «портит» снимаемый скриншот.

подсказка

Рекомендуется сбрасывать курсор для десктопных браузеров и не сбрасывать для мобильных.

screenshotsDir

Папка для сохранения эталонных скриншотов командой assertView. По умолчанию это папка testplane/screens относительно рабочей папки: process.cwd(). Значением данной опции может быть также функция, которой передается один аргумент — инстанс теста, внутри которого была вызвана команда assertView, например:

const browserOptions = {
    screenshotsDir: test => `tests/screenshots/${test.parent.title}`,
};

Снятие и сравнение скриншотов

Параметр	Тип	По умолчанию	Описание
tolerance	number	2.3	Максимально разрешенная разница CIEDE2000 между цветами.
antialiasingTolerance	number	4	Задает чувствительность определения антиалиасинга, который будет игнорироваться при сравнении скриншотов.
compareOpts	CompareOpts	см. ниже	Опции для сравнения изображений.
buildDiffOpts	BuildDiffOpts	см. ниже	Опции для построения диффа (изображения с разницей между скриншотами).
assertViewOpts	AssertViewOpts	см. ниже	Опции для команды assertView, которые будут использоваться по умолчанию.
compositeImage	boolean	true	Позволяет тестировать элементы, не влезающие во вьюпорт по высоте.
screenshotMode	"auto" | "fullpage" | "viewport"	"auto"	Режим снятия скриншота.
screenshotDelay	number	0	Задержка перед снятием скриншота, в мс.

tolerance

Максимально разрешенная разница CIEDE2000 между цветами. Используется только в нестрогом режиме. По умолчанию 2.3. Начиная со значения 2.3 разница в цветах становится уже различимой человеческим глазом. Чем меньше это значение, тем строже будет сравнение скриншотов.

Не рекомендуется увеличивать значение tolerance на глобальном уровне. Попробуйте вместо этого задавать tolerance для конкретных наборов тестов или состояний.

Так можно снять скриншот для конкретного состояния с индивидуальной настройкой tolerance:

it("some-test", async function (browser) {
    await browser.assertView("some-state", ".selector1", { tolerance: 10 });
    await browser.assertView("another-state", ".selector1");
});

antialiasingTolerance

Задает чувствительность определения антиалиасинга, который будет игнорироваться при сравнении скриншотов.

Читайте подробнее об этой опции в пакете looks-same.

compareOpts

Дополнительные опции для сравнения изображений. Смотрите в документации пакета looks-same список доступных опций.

По умолчанию:

const defaultCompareOpts = {
    shouldCluster: false,
    clustersSize: 10,
    stopOnFirstFail: false,
};

buildDiffOpts

Дополнительные опции для построения диффа (изображения с разницей между скриншотами). Смотрите в документации пакета looks-same список доступных опций. По умолчанию:

const defaultBuildDiffOpts = {
    ignoreAntialiasing: true,
    ignoreCaret: true,
};

assertViewOpts

Опции для команды снятия и сравнения скриншотов assertView, которые будут использоваться по умолчанию. Могут быть перезаписаны при вызове команды assertView.

Доступны следующие опции для assertView:

Option	Type	Description
ignoreElements	Array or String	Elements (specified as selectors) that will be ignored when comparing screenshots. Ignoring is implemented by painting the listed elements black. In the case of a single element, the parameter can be specified as a string.
tolerance	Number	Sensitivity to color differences.
antialiasingTolerance	Number	Sensitivity to antialiasing.
allowViewportOverflow	Boolean	By default, Testplane throws an error if an element is outside the viewport boundaries. This parameter disables boundary checking, allowing screenshots of elements that do not fit within the viewport. Only the parts of the element that fit within the viewport will be visible in the screenshot. However, if compositeImage is set to true, parts of the element that are below the viewport will also be visible in the screenshot. Similarly, if captureElementFromTop is set to true, parts of the element that are above the viewport will also be included in the screenshot.
captureElementFromTop	Boolean	Capture a screenshot of the element from the very top. If the element is outside the viewport, it will be scrolled into view.
compositeImage	Boolean	If the element does not fit within the viewport, enabling this option will take multiple screenshots of different parts of the element sequentially, and then stitch them together into one image to display the entire element.
screenshotDelay	Number	Delay in milliseconds before taking a screenshot. This can be useful when there are elements on the page that use animation, or a scrollbar that does not disappear immediately and ends up in the resulting screenshot.
selectorToScroll	String	Selector to scroll. This can be useful when you need to take a screenshot of a modal window that does not fit on the screen. Otherwise, without specifying the selector, the scroll will be applied to the window object, and the background will scroll, leaving the popup window in place.
disableAnimation	Boolean	Disable animations and transitions when taking a screenshot. Default is true starting from version 8.0.0.
ignoreDiffPixelCount	`${number}%` or Number	Percentage of pixels to ignore in the diff. Useful for ignoring very small diffs. Default is 0. Available starting from version 8.2.0.
waitForStaticToLoadTimeout	Number	Timeout for waitForStaticToLoad command, which is automatically called before taking screenshot. Waiting is disabled, if value is set to 0. Default is 5000. Available starting from version 8.32.0.

По умолчанию:

const defaultAssertViewOpts = {
    ignoreElements: [],
    captureElementFromTop: true,
    allowViewportOverflow: false,
    disableAnimation: true,
    ignoreDiffPixelCount: 0,
};

compositeImage

Позволяет тестировать элементы, не влезающие во вьюпорт по высоте. По умолчанию: true. Если тестируемый блок по высоте больше вьюпорта, то происходит склеивание изображений нескольких вьюпортов в одно изображение.

screenshotMode

Режим снятия скриншотов. По умолчанию: auto.

Возможные значения:

• "auto" — режим будет определен автоматически.
• "fullpage" — будет снят скриншот всей страницы.
• "viewport" — будет снят скриншот только вьюпорта.

По умолчанию для android-браузеров выставляется режим viewport, чтобы обойти багу в Chromium.

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

screenshotDelay

Задержка в миллисекундах перед снятием скриншота. По умолчанию: 0 мс. Задержка может пригодиться в тех случаях, когда на странице есть элементы, использующие анимацию, или скроллбар, который исчезает не сразу и попадает на результирующий скриншот.

Параметры запросов и ответов

Параметр	Тип	По умолчанию	Описание
agent	object	null	Позволяет задать свои агенты для запросов по http, https, http2.
headers	Record<string, string>	null	Позволяет настроить заголовки, которые будут передаваться в каждом запросе к WebDriver.
transformRequest	TransformRequestFn	null	Позволяет перехватывать и преобразовывать опции http-запроса перед запросом к WebDriver.
transformResponse	TransformResponseFn	null	Позволяет перехватывать и преобразовывать http-ответ, полученный от WebDriver.
strictSSL	boolean	null	Должен ли SSL-сертификат быть действительным.

agent

Позволяет задать свои агенты для запросов по http, https, http2. По умолчанию: null (в таком случае будут использованы дефолтные http-агенты пакета got).

headers

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

warning

Данные заголовки не передаются в запросы из браузера, в котором выполняются тесты. Они передаются только в запросах к WebDriver.

transformRequest

Позволяет перехватывать и преобразовывать опции http-запроса перед запросом к WebDriver. По умолчанию: null. Если передается функция, то первым аргументом ей будет передан объект RequestOptions. В ответ функция должна будет вернуть модифицированный RequestOptions.

Тип функции:

type TransformRequestFn = (req: RequestOptions) => RequestOptions;

По умолчанию эта функция используется для генерации заголовка X-Request-ID. Этот заголовок имеет формат ${FIRST_X_REQ_ID}__${LAST_X_REQ_ID}, где:

• FIRST_X_REQ_ID - уникальный UUID для каждого теста (разный для каждого ретрая), позволяет найти все запросы, относящиеся к конкретному запуску теста;
• LAST_X_REQ_ID - уникальный UUID для каждого запроса к браузеру в рамках одного теста, в сочетании с FIRST_X_REQ_ID позволяет найти конкретный запрос.

Пример значения: 2f31ffb7-369d-41f4-bbb8-77744615d2eb__e8d011d8-bb76-42b9-b80e-02f03b8d6fe1.

Заголовок X-Request-ID может быть полезен для отладки проблемных запросов, если вы используете собственный браузерный грид и сохраняете логи запросов.

Вы можете генерировать X-Request-ID в своем формате используя transformRequest. Пример:

const transformRequest = req => {
    req.headers["X-Request-ID"] = "my_x_req_id";

    return req;
};

transformResponse

Позволяет перехватывать и преобразовывать http-ответ, полученный от WebDriver. По умолчанию: null. Если передается функция, то первым аргументом ей будет передан объект Response, а вторым — RequestOptions. В ответ функция должна будет вернуть модифицированный Response.

Тип функции:

type TransformResponsetFn = (res: Response, req: RequestOptions) => Response;

strictSSL

Должен ли SSL-сертификат быть действительным. Если не задано, будет использовано значение по умолчанию от WebDriverIO.

Облачные настройки

Следующие настройки могут пригодиться, если вы захотите запускать свои testplane-тесты в браузерах облачных сервисов.

Примером такого облачного сервиса может быть SauceLabs, который может предоставить вам как десктопные, так и мобильные браузеры для запуска тестов в них.

Параметр	Тип	По умолчанию	Описание
user	string	null	Имя пользователя в облачном сервисе.
key	string	null	Ключ доступа или секретный ключ для доступа в облачный сервис.
region	string	null	Позволяет выбрать различные датацентры в облачном сервисе.
headless	string	null	Позволяет запускать headless-браузер в облачном сервисе.

user

Имя пользователя в облачном сервисе. По умолчанию: null.

key

Ключ доступа или секретный ключ для доступа в облачный сервис. По умолчанию: null.

region

Позволяет выбрать различные датацентры в облачном сервисе. По умолчанию: null.

headless

Позволяет запускать headless-браузер в облачном сервисе. По умолчанию: null.

Time Travel

Эти настройки позволяют конфигурировать запись снапшотов прогонов теста для их последующего воспроизведения в плеере. Чтобы узнать больше о возможностях Time Travel, перейдите в руководство по Time Travel.

Параметр	Тип	По умолчанию	Описание
timeTravel	string | TimeTravelSettings	"off"	Настройки Time Travel.

timeTravel

Настройки Time Travel. По умолчанию: "off".

Для быстрого задания сюда можно передать строку — один из режимов записи (TimeTravelMode). Полная конфигурация выглядит так:

enum TimeTravelMode {
    // Запись снапшотов включена для всех прогонов
    On = "on",
    // Запись снапшотов выключена
    Off = "off",
    // Запись снапшотов включена для всех ретраев (первый запуск не считается ретраем)
    RetriesOnly = "retries-only",
    // Запись снапшотов включена для всех прогонов, но сохраняются только снапшоты для последнего прогона с ошибкой
    // Например:
    // - если тест запускался 1 раз и упал, снапшот будет записан.
    // - если тест запускался 5 раз и упал все 5 раз, будет записан снапшот для 5-го ретрая.
    // - если тест запускался 2 раза и оба раза успешно прошел, снапшотов не будет.
    LastFailedRun = "last-failed-run",
}

interface TimeTravelConfig {
    mode: TimeTravelMode;
}

Пример валидной конфигурации:

import { TimeTravelMode } from "@testplane/testplane";

export = {
    timeTravel: {
        mode: TimeTravelMode.RetriesOnly,
    },
};

Selectivity

Эта секция позволяет конфигурировать селективность запуска Testplane, избегая запуска тех тестов, для которых ничего не поменялось.

Секция имеет следующие параметры:

Параметр	Тип	По умолчанию	Описание
enabled	boolean	false	Включает селективность запуска тестов.
sourceRoot	string	""	Конфигурирует путь к корню файлов исходного кода.
testDependenciesPath	string	".testplane/selectivity"	Путь к директории, куда будут сохраняться данные о зависимостях тестов.
compression	"none" | "gz" | "br" | "zstd"	"gz"	Тип сжатия, применяемый к данным о зависимостях тестов.
disableSelectivityPatterns	string[]	[]	Список паттернов, при изменении файлов по которым селективность должна отключаться.
mapDependencyRelativePath	null | (dependency: { scope: "browser" | "testplane", relativePath: string }) => string | void	null	Коллбэк, который принимает путь зависимости теста в стиле POSIX и преобразует его в другой путь или полностью игнорирует зависимость, если возвращено falsy значение

Примеры mapDependencyRelativePath

Игнорирование внутренних зависимостей Next.js

{
    selectivity: {
        enabled: true,
        mapDependencyRelativePath({relativePath}) {
            if (relativePath.startsWith("turbopack://")) {
                return;
            }

            return relativePath;
        },
    }
}

Использование с плагином @testplane/storybook

{
    selectivity: {
        enabled: true,
        mapDependencyRelativePath({relativePath}) {
            // Автогенерированные тесты testplane storybook
            if (relativePath.includes("/testplane-storybook-autogenerated/")) {
                return;
            }

            // Фиктивные зависимости Storybook
            if (relativePath === "storybook-stories.js" || relativePath === "storybook-config-entry.js") {
                return;
            }

            return relativePath;
        },
    }
}

к сведению

В disableSelectivityPatterns не стоит указывать node_modules - это приведет к ощутимому замедлению. Вместо этого, рекомендуется указать конфигурационные файлы Testplane и исходный код серверной части приложения.

stateOpts

Available from testplane v8.40.0

Настройки по умолчанию для команд состояния.

Вы можете задать параметры один раз и затем использовать команды состояния (saveState, restoreState, getState) без указания опций. Однако если вы явно укажете параметры для команды, они будут иметь высший приоритет.

Параметр	Тип	По умолчанию	Описание
stateOpts	StateOpts	undefined	Настройки по умолчанию для команд состояния.

type StateOpts = {
    path?: string;
    cookies?: boolean;
    localStorage?: boolean;
    sessionStorage?: boolean;
    cookieFilter?: (cookie: Cookie) => boolean;
    keepFile?: boolean;
};

Пример валидной конфигурации:

export = {
    stateOpts: {
        path: "stateDump.json",
    },
};