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
Выполняет итерацию по тестам для заданного браузера.