API testplane

С помощью API testplane вы можете использовать её в своих скриптах или сборочных инструментах.

Для этого вы должны подключить модуль testplane и создать её инстанс:

const Testplane = require("testplane");

const config = require("./testplane.conf.js");

const testplane = new Testplane(config);

Далее вам будут доступны следующие параметры и методы:

Имя	Тип	Описание
config	Object или String	Объект с конфигом testplane или путь к конфигурационному файлу, относительно рабочей папки.
events	Object	События testplane, на которые можно подписаться.
errors	Object	Ошибки, которые может возвращать testplane.
intercept	Function	Функция, с помощью которой можно подписаться на перехват событий testplane.
init	Method	Инициализирует инстанс testplane, загружает все плагины и т. д.
run	Method	Запускает прогон тестов, расположенных по указанным путям.
addTestToRun	Method	Добавляет тест к текущему запуску.
readTests	Method	Возвращает объект типа TestCollection.
isFailed	Method	Возвращает true или false в зависимости от того, была ли ошибка или падение теста при запуске тестов.
isWorker	Method	Возвращает true, если метод был вызван из воркера testplane.
halt	Method	Аварийно завершает прогон тестов в случае критической ошибки.

config

Объект с конфигом testplane или путь к конфигурационному файлу, относительно рабочей папки: process.cwd().

events

События testplane, на которые можно подписаться.

Пример использования объекта testplane.events в плагине testplane:

testplane.on(testplane.events.INIT, async () => {
    console.info("Выполняется обработка события INIT...");
});

errors

Testplane может возвращать ошибки следующего типа:

• CoreError
• CancelledError
• ClientBridgeError
• HeightViewportError
• OffsetViewportError
• AssertViewError
• ImageDiffError
• NoRefImageError

CoreError

Ошибка CoreError возвращается в случае неудачной калибровки пустой страницы (about:blank) в браузере.

Ошибка при этом содержит следующее сообщение:

Could not calibrate. This could be due to calibration page has failed to open properly

CancelledError

Ошибка CancelledEror возвращается в случае аварийного завершения по команде halt.

Ошибка при этом содержит следующее сообщение:

Browser request was cancelled

ClientBridgeError

Ошибка ClientBridgeError возвращается в случае неудачной инъекции кода JavaScript на стороне клиента (браузера). Testplane осуществляет инъекцию кода с помощью команды execute WebDriverIO.

Ошибка при этом содержит следующее сообщение:

Unable to inject client script

HeightViewportError

Ошибка HeightViewportError возвращается при попытке снять скриншот для области, чья нижняя граница не влезает в область вьюпорта.

Ошибка при этом содержит следующее сообщение:

Can not capture the specified region of the viewport.
The region bottom bound is outside of the viewport height.
Alternatively, you can test such cases by setting "true" value to option "compositeImage" in the config file
or setting "false" to "compositeImage" and "true" to option "allowViewportOverflow" in "assertView" command.
Element position: <cropArea.left>, <cropArea.top>; size: <cropArea.width>, <cropArea.height>.
Viewport size: <viewport.width>, <viewport.height>.

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

OffsetViewportError

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

Ошибка при этом содержит следующее сообщение:

Can not capture the specified region of the viewport.
Position of the region is outside of the viewport left, top or right bounds.
Check that elements:
- does not overflow the document
- does not overflow browser viewport
Alternatively, you can increase browser window size using
"setWindowSize" or "windowSize" option in the config file.
But if viewport overflow is expected behavior then you can use
option "allowViewportOverflow" in "assertView" command.

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

AssertViewError

Ошибка AssertViewError возвращается при неудачной попытке снять скриншот.

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

duplicate name for "<state>" state

element ("<selector>") still not existing after <this.options.waitforTimeout> ms

element ("<this.selector>") still not existing after <this.options.waitforTimeout> ms

ImageDiffError

Ошибка ImageDiffError возвращается из команды assertView, если при снятии и сравнении скриншота с эталонным скриншотом обнаруживается дифф (разница в изображениях).

Ошибка при этом содержит следующее сообщение:

images are different for "<stateName>" state

Кроме этого, ошибка ImageDiffError содержит следующие данные:

Свойство	Описание
stateName	имя состояния, для которого делался скриншот
currImg	ссылка на актуальное изображение
refImg	ссылка на эталонное изображение
diffOpts	настройки определения диффа
diffBounds	границы областей с диффами на изображении
diffClusters	кластеры с диффами на изображении

Подробнее про diffBounds и diffClusters читайте в документации пакета looks-same.

exports.handleImageDiff = (currImg, refImg, state, opts) => {
    const {tolerance, antialiasingTolerance, canHaveCaret, diffAreas, config} = opts;
    const {buildDiffOpts, system: {diffColor}} = config;
    buildDiffOpts.ignoreCaret = buildDiffOpts.ignoreCaret && canHaveCaret;

    const diffOpts = {
        current: currImg.path, reference: refImg.path,
        diffColor, tolerance, antialiasingTolerance, ...buildDiffOpts
    };

    return Promise.reject(ImageDiffError.create(state, currImg, refImg, diffOpts, diffAreas));
};

NoRefImageError

Ошибка NoRefImageError возвращается из команды assertView, если при снятии и сравнении скриншота testplane не находит эталонный скриншот на файловой системе.

Ошибка при этом содержит следующее сообщение:

can not find reference image at <refImg.path> for "<stateName>" state

Кроме этого, ошибка NoRefImageError содержит следующие данные:

Свойство	Описание
stateName	имя состояния, для которого делался скриншот
currImg	ссылка на актуальное изображение
refImg	ссылка на эталонное изображение

intercept

Функция, с помощью которой можно подписаться на перехват событий testplane.

Первым аргументом функция принимает событие, которое нужно перехватывать, а вторым — обработчик события.

Например:

testplane.intercept(testplane.events.TEST_FAIL, ({ event, data }) => {
    return {};
});

Подробнее о перехвате событий читайте в разделе «Про перехват событий».

init

Инициализирует инстанс testplane, загружает все плагины и т. д.

Пример вызова

await testplane.init();

run

Запускает прогон тестов, расположенных по заданным путям.

Возвращает true, если прогон тестов завершился успешно, и false — если не успешно.

Пример вызова

const success = await testplane.run(testPaths, options);

Параметры вызова

Все параметры метода testplane.run() являются необязательными.

Имя параметра	Тип	Описание
testPaths	String[] или TestCollection	Пути к тестам относительно рабочей папки (process.cwd()) или объект типа TestCollection, который возвращается методом readTests. Если пути не указаны, то будут запущены все тесты.
options	Object	Объект с опциями запуска.
options.reporters	String[]	Репортеры для результатов прогона тестов.
options.browsers	String[]	Браузеры, в которых нужно запустить тесты.
options.sets	String[]	Сеты, в которых нужно запустить тесты.
options.grep	RegExp	Шаблон регулярного выражения, который задает тесты для запуска.

addTestToRun

Добавляет тест к текущему запуску. Возвращает false, если текущий запуск уже закончился или был отменен. Иначе возвращает true.

Пример вызова

const success = testplane.addTestToRun(test, browser);

Параметры вызова

Все параметры являются обязательными.

Имя параметра	Тип	Описание
test	Test	Тест для запуска.
browserId	String	Браузер, в котором нужно запустить тест.

readTests

Асинхронный метод. Возвращает объект типа TestCollection.

Пример вызова

await testplane.readTests(testPaths, options);

Параметры вызова

Имя параметра	Тип	Описание
testPaths	String[]	Пути к тестам относительно рабочей папки (process.cwd()).
options	Object	Объект с настройками режима чтения тестов.
options.browsers	String[]	Прочитать тесты только для указанных браузеров.
options.silent	Boolean	Отключить генерацию событий во время чтения тестов. По умолчанию: false.
options.ignore	String или Glob или String[] или Glob[]	Шаблоны, указывающие какие пути на файловой системе надо исключить при поиске тестов.
options.sets	String[]	Сеты, в которых нужно прочитать тесты.
options.grep	RegExp	Шаблон регулярного выражения, который задает тесты для чтения.

isFailed

Возвращает true или false в зависимости от того, была ли ошибка или падение теста при запуске тестов. Может пригодиться в плагинах для того, чтобы определить текущий статус testplane.

Пример вызова

const failed = testplane.isFailed();

isWorker

Возвращает true, если метод был вызван из воркера testplane. Возвращает false, если метод был вызван из мастер-процесса testplane.

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

Пример вызова

// реализация какого-либо плагина
module.exports = testplane => {
    if (testplane.isWorker()) {
        // этот код будет выполняться только в воркерах testplane
    } else {
        // этот код будет выполняться только в мастер-процессе testplane
    }
};

halt

Аварийно завершает прогон тестов в случае критической ошибки. Если процессу не удается корректно завершить работу за заданное контрольное время (timeout), то он будет принудительно завершен, кроме случаев, когда timeout явно установлен в 0.

Пример вызова

testplane.halt(error, [timeout=60000ms]);

Параметры вызова

Имя параметра	Тип	Описание
error	Error	Возникшая критическая ошибка, из-за которой приходится останавливать testplane.
timeout	Number	Необязательный параметр. Контрольное время завершения процесса testplane. По умолчанию: 60000 мс.

Test Collection

Объект типа TestCollection возвращается методом testplane.readTests, а также передается в качестве аргумента в обработчик события AFTER_TESTS_READ.

getBrowsers

Возвращает список браузеров, для которых в коллекции есть тесты.

Пример вызова

const browsers = testCollection.getBrowsers();

mapTests

Строит отображение тестов для заданного браузера.

Пример вызова

const tests = testCollection.mapTests(browserId, (test, browserId) => {
    // ...
});

Если браузер не задан (то есть первым аргументом передан обратный вызов), то будет строиться отображение тестов для всех браузеров.

sortTests

Сортирует тесты для заданного браузера.

Пример вызова

testCollection.sortTests(browserId, (currentTest, nextTest) => {
    // ...
});

Если браузер не задан (то есть первым аргументом передан обратный вызов), то сортировка будет применена ко всем браузерам.

eachTest

Выполняет итерацию по тестам для заданного браузера.

Пример вызова

testCollection.eachTest(browserId, (test, browserId) => {
    // ...
});

Если браузер не задан (то есть первым аргументом передан обратный вызов), то итерация будет происходить по тестам для всех браузеров.

eachTestByVersions

Выполняет итерацию по тестам и версиям браузера для заданного браузера.

Использует наличие у каждого теста свойства browserVersion.

Пример вызова

testCollection.eachTestByVersions(browserId, (test, browserId, browserVersion) => {
    // ...
});

disableAll

Отключает все тесты или тесты для заданного браузера. Возвращает ссылку на инстанс коллекции тестов.

Примеры вызова

disableAll();

или

disableAll(browserId);

Если браузер не задан, то будут отключены все тесты.

enableAll

Включает все тесты или тесты для заданного браузера. Возвращает ссылку на инстанс коллекции тестов.

Примеры вызова

enableAll();

или

enableAll(browserId);

Если браузер не задан, то будут включены все тесты.

disableTest

Отключает указанный тест во всех браузерах или только в заданном браузере. Возвращает ссылку на инстанс коллекции тестов.

Примеры вызова

disableTest(fullTitle);

или

disableTest(fullTitle, browserId);

Идентификатором теста является его полное название: fullTitle.

enableTest

Включает указанный тест во всех браузерах или только в заданном браузере. Возвращает ссылку на инстанс коллекции тестов.

Примеры вызова

enableTest(fullTitle);

или

enableTest(fullTitle, browserId);

getRootSuite

Возвращает корневой suite для заданного браузера. Возвращает undefined, если в коллекции нет тестов для указанного браузера.

Пример вызова

const rootSuite = getRootSuite(browserId);

eachRootSuite

Выполняет итерацию по всем корневым suite в коллекции, в которых есть тесты.

Пример вызова

eachRootSuite((root, browserId) => {
    // ...
});