Основные концепции плагинов

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

Этот учебник покажет вам, как получить доступ к API плагинов Chai, использовать флаги для передачи данных по цепочке языка и написать первое утверждение (и исчерпывающие сообщения об ошибках). После этого Создание вспомогательной функции покажет вам, как создавать свойства и методы для использования в цепочке языка Chai.

Доступ к утилитам

Chai поставляется с рядом утилит, которые помогают в составлении утверждений, но они не предоставляются напрямую в chai экспорте. К ним можно получить доступ, используя метод use экспорта chai, который принимает один аргумент — функцию.

chai.use(function (_chai, utils) {
  // ...
});

Функция, которая будет использоваться, получает два параметра в свой области видимости. Первый — это chai экспорт, второй — объект, содержащий ряд утилит (мы рассмотрим их чуть позже).

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

Для нашего файла вспомогательных функций: test/helpers/model.js

module.exports = function (chai, utils) {
  var Assertion = chai.Assertion;

  // your helpers here
};

И, для нашего фактического теста: test/person.js

var chai = require('chai')
  , chaiModel = require('./helpers/model')
  , expect = chai.expect;

chai.use(chaiModel);

В дальнейшем мы будем исходить из этой структуры…

вспомогательные функции в отдельном файле
chai.Assertion присвоено переменной Assertion
все наши вспомогательные функции будут внутри экспортируемой функции, расположенной как указано

Переменная Assertion теперь является конструктором для цепочки утверждений; new Assertion(obj) теперь эквивалентна expect(obj).

Использование флагов

Основной концепцией внутреннего функционирования утверждений является понятие флагов. Каждое утверждение имеет набор в основном произвольных флагов — пар «ключ:значение». Chai использует небольшое количество из них во внутренней работе, но хранилище также доступно для расширения разработчиками.

Использование флагов

Утилита флагов экспортируется как utils.flag внутри нашей функции use. Она может работать как getter, так и setter, в зависимости от количества переданных аргументов.

var myAssert = new Assertion(obj);
utils.flag(myAssert, 'owner', 'me'); // sets key `owner` to `me`
var owner = utils.flag(myAssert, 'owner'); // get key `owner', returns value

Флаг объекта

Самым важным из зарезервированных флагов Chai является флаг object. Это предмет утверждения.

var myAssert = new Assertion('Arthur Dent');
var obj = flag(myAssert, 'object'); // obj === 'Arthur Dent';

Этот флаг используется так часто, что был предоставлен сокращенный способ обращения к нему — свойство _obj построенного утверждения.

var obj = myAssert._obj; // obj === `Arthur Dent`

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

object: (см. выше)
ssfi: запуск функции стека — используется для предотвращения отображения стеков вызовов в сообщениях об ошибках.
message: дополнительная информация для включения в сообщение об ошибке при использовании интерфейса assert.
negate: устанавливается, когда .not включён в цепочку.
deep: устанавливается, когда .deep включён в цепочку. Используется equal и property
contains: устанавливается, когда include или contain используется как свойство. Изменяет поведение keys.
lengthOf: устанавливается, когда length используется как свойство. Изменяет поведение above, below, и within.

Составление утверждения

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

Для этого каждое построенное Assertion имеет метод под названием просто assert. Он принимает множество параметров, и его поведение может меняться в зависимости от того, было ли утверждение отрицательным или нет.

Базовое утверждение

Для начала мы снова построим Артура, а затем можем утверждать, что он тот, за кого себя выдаёт.

var arthur = new Assertion('Arthur Dent');

arthur.assert(
    arthur._obj === 'Arthur Dent'
  , "expected #{this} to be 'Arthur Dent'"
  , "expected #{this} to not be 'Arthur Dent'"
);

Chai проверит первый аргумент; если он true, то утверждение прошло, но если false, то утверждение не выполнилось, и первое сообщение об ошибке будет выброшено в качестве части chai.AssertionError. И наоборот, если цепочка языка была отрицательной, она будет считать false успехом, а true — неудачей. Вместо этого, второе сообщение об ошибке будет включено в выброшенную ошибку.

В целом, метод assert принимает шесть аргументов:

логическое значение (результат проверки истинности)
строковое сообщение об ошибке, которое будет использоваться, если первый аргумент false
строковое сообщение об ошибке, которое будет использоваться, если утверждение отрицательно, и первый аргумент true
(необязательно) ожидаемое значение
(необязательно) фактическое значение, которое по умолчанию _obj
(необязательно) логическое значение, которое указывает, следует ли отображать разницу помимо сообщения, если первый аргумент false

Создание сообщений об ошибках

Как видно из приведённого выше примера, Chai может принимать теги шаблонов для динамического создания сообщения об ошибке. При использовании эти теги шаблонов будут заменены строковым представлением соответствующего объекта. Доступны три тега шаблона.

#{this}: _obj утверждения
#{exp}: ожидаемое значение, если оно было предоставлено в assert
#{act}: фактическое значение, по умолчанию _obj, но может быть переопределено предоставленным значением в assert