Заглушки

Что такое заглушки?

Тестовые заглушки — это функции (шпионы) с предварительно запрограммированным поведением.

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

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

Когда использовать заглушки?

Используйте заглушку, когда вы хотите:

1. Управлять поведением метода из теста, чтобы заставить код пойти по определенному пути. Примеры включают принудительное выброс ошибки методом для тестирования обработки ошибок.

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

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

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

Определение поведения заглушки при последовательных вызовах

Вызов методов определения поведения, таких как returns или throws, несколько раз перезаписывает поведение заглушки. Начиная с версии Sinon 1.8, вы можете использовать метод onCall, чтобы заглушка реагировала по-разному на последовательные вызовы.

Обратите внимание, что в версиях Sinon с 1.5 по 1.7 несколько вызовов методов семейства yields* и callsArg* определяют последовательность поведения для последовательных вызовов. Начиная с версии 1.8, эта функциональность была удалена в пользу API onCall.

API заглушки

Свойства

var stub = sinon.stub();

Создает анонимную функцию-заглушку

var stub = sinon.stub(object, "method");

Заменяет object.method функцией-заглушкой. Если свойство не является функцией, выбрасывается исключение.

Исходную функцию можно восстановить, вызвав object.method.restore(); (или stub.restore();).

var stub = sinon.stub(object, "method", func);

Это было удалено из v3.0.0. Вместо этого вы должны использовать

stub(obj, 'meth').callsFake(fn)

Доступен инструмент перевода кода для обновления вашего кода.

var stub = sinon.stub(obj);

Заглушает все методы объекта.

Обратите внимание, что обычно лучше заглушать отдельные методы, особенно для объектов, которые вы не понимаете или не контролируете все методы (например, зависимости библиотек).

Заглушение отдельных методов более точно тестирует намерение и менее подвержено неожиданному поведению по мере развития кода объекта.

Если вы хотите создать объект заглушки MyConstructor, но не хотите вызывать конструктор, используйте эту вспомогательную функцию.

var stub = sinon.createStubInstance(MyConstructor, overrides);

overrides — это необязательная карта, переопределяющая созданные заглушки, например:

var stub = sinon.createStubInstance(MyConstructor, {
  foo: sinon.stub().returnsThis(),
});

эквивалентно:

var stub = sinon.createStubInstance(MyConstructor);
stub.foo.returnsThis();

Если предоставленное значение не является заглушкой, оно будет использоваться в качестве возвращаемого значения:

var stub = sinon.createStubInstance(MyConstructor, {
  foo: 3,
});

эквивалентно:

var stub = sinon.createStubInstance(MyConstructor);
stub.foo.returns(3);

stub.withArgs(arg1[, arg2, ...]);

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

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

Использует глубокое сравнение для объектов и массивов. Используйте stub.withArgs(sinon.match.same(obj)) для строгого сравнения (см. сопоставители).

stub.onCall(n); Добавлен в v1.8

Определяет поведение заглушки при n-ом вызове. Полезно для тестирования последовательных взаимодействий.

Существуют методы onFirstCall, onSecondCall, onThirdCall, чтобы определения заглушки читались более естественно.

onCall может быть объединен со всеми методами определения поведения в этом разделе. В частности, он может использоваться вместе с withArgs.

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

stub.onFirstCall();

Псевдоним для stub.onCall(0);

stub.onSecondCall();

Псевдоним для stub.onCall(1);

stub.onThirdCall();

Псевдоним для stub.onCall(2);

stub.reset();

Сбрасывает поведение и историю заглушки.

Эквивалентно вызову stub.resetBehavior() и stub.resetHistory()

Обновлено в sinon@2.0.0

С sinon@5.0.0

Для удобства вы можете применить stub.reset() ко всем заглушкам, используя sinon.reset()

stub.resetBehavior();

Сбрасывает поведение заглушки к стандартному поведению

С sinon@5.0.0

Вы можете сбросить поведение всех заглушек, используя sinon.resetBehavior()

stub.resetHistory();

С sinon@2.0.0

Сбрасывает историю заглушки

С sinon@5.0.0

Вы можете сбросить историю всех заглушек, используя sinon.resetHistory()

stub.callsFake(fakeFunction);

Заставляет заглушку вызывать предоставленную функцию fakeFunction при вызове.

stub.returns(obj);

Заставляет заглушку возвращать предоставленное значение.

stub.returnsArg(index);

Заставляет заглушку возвращать аргумент в предоставленном индексе.

stub.returnsArg(0); заставляет заглушку возвращать первый аргумент.

Если аргумент в предоставленном индексе недоступен, до sinon@6.1.2, будет возвращено значение undefined; начиная с sinon@6.1.2, будет выброшено исключение TypeError.

stub.returnsThis();

Заставляет заглушку возвращать своё значение this.

Полезно для заглушения интерфейсов jQuery-стиля.

stub.resolves(value);

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

При создании Promise, sinon использует метод Promise.resolve. Вы несёте ответственность за предоставление полифилла в средах, которые не предоставляют Promise. Библиотеку Promise можно переопределить, используя метод usingPromise.

С sinon@2.0.0

stub.resolvesArg(index);

Заставляет заглушку возвращать Promise, который разрешается с аргументом в предоставленном индексе.

stub.resolvesArg(0); заставляет заглушку возвращать Promise, который разрешается с первым аргументом.

Если аргумент в предоставленном индексе недоступен, будет выброшено исключение TypeError.

С sinon@6.1.1

stub.throws();

Заставляет заглушку выбросить исключение (Error).

stub.throws("name"[, "optional message"]);

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

stub.throws(obj);

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

stub.throws(function() { return new Error(); });

Заставляет заглушку выбросить исключение, возвращаемое функцией.

stub.throwsArg(index);

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

stub.throwsArg(0); заставляет заглушку выбросить первый аргумент как исключение.

Если аргумент в предоставленном индексе недоступен, будет выброшено исключение TypeError.

С sinon@2.3.0

stub.rejects();

Заставляет заглушку вернуть Promise, который отклоняется с исключением (Error).

При создании Promise, sinon использует метод Promise.reject. Вы несёте ответственность за предоставление полифилла в средах, которые не предоставляют Promise. Библиотеку Promise можно переопределить, используя метод usingPromise.

С sinon@2.0.0

stub.rejects("TypeError");

Заставляет заглушку вернуть Promise, который отклоняется с исключением указанного типа.

С sinon@2.0.0

stub.rejects(value);

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

С sinon@2.0.0

stub.callsArg(index);

Заставляет заглушку вызывать аргумент в предоставленном индексе как коллбэк-функцию.

stub.callsArg(0); заставляет заглушку вызывать первый аргумент как коллбэк.

Если аргумент в предоставленном индексе недоступен или не является функцией, будет выброшено исключение TypeError.

stub.callThrough();

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

stub.callThroughWithNew();

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

stub.callsArgOn(index, context);

Как stub.callsArg(index);, но с дополнительным параметром для передачи контекста this.

stub.callsArgWith(index, arg1, arg2, ...);

Как callsArg, но с аргументами для передачи коллбэку.

stub.callsArgOnWith(index, context, arg1, arg2, ...);

Как выше, но с дополнительным параметром для передачи контекста this.

stub.usingPromise(promiseLibrary);

Заставляет заглушку возвращать promises, используя определенную библиотеку Promise вместо глобальной, когда используются stub.rejects или stub.resolves. Возвращает заглушку для возможности цепочки.

С sinon@2.0.0

stub.yields([arg1, arg2, ...])

Аналогично callsArg.

Заставляет заглушку вызывать первый полученный коллбэк с предоставленными аргументами (если таковые имеются).

Если метод принимает более одного коллбэка, вам необходимо использовать yieldsRight для вызова последнего коллбэка или callsArg для того, чтобы заглушка вызывала коллбэки, кроме первого или последнего.

stub.yieldsRight([arg1, arg2, ...])

Как yields , но вызывает последний полученный коллбэк.

stub.yieldsOn(context, [arg1, arg2, ...])

Как yields , но с дополнительным параметром для передачи контекста this.

stub.yieldsTo(property, [arg1, arg2, ...])

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

Как yields, yieldsTo берет первый подходящий аргумент, находит коллбэк и вызывает его с (необязательными) аргументами.

"test should fake successful ajax request": function () {
    sinon.stub(jQuery, "ajax").yieldsTo("success", [1, 2, 3]);

    jQuery.ajax({
        success: function (data) {
            assertEquals([1, 2, 3], data);
        }
    });
}

stub.yieldsToOn(property, context, [arg1, arg2, ...])

Как выше, но с дополнительным параметром для передачи контекста this.

stub.yield([arg1, arg2, ...])

Вызывайте переданные в stub колбэки с указанными аргументами.

Если заглушка (stub) никогда не вызывалась с аргументом-функцией, yield выбросит ошибку.

Возвращает массив со всеми значениями возврата колбэков в порядке их вызова, если не возникает ошибок.

Также алиасируется как invokeCallback.

stub.yieldTo(callback, [arg1, arg2, ...])

Вызывает колбэки, переданные как свойство объекта заглушке.

Как и yield, yieldTo захватывает первый соответствующий аргумент, находит колбэк и вызывает его с (необязательными) аргументами.

stub.callArg(argNum)

Как yield, но с явным номером аргумента, определяющим, какой колбэк вызвать.

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

"calling the last callback": function () {
    var callback = sinon.stub();
    callback(function () {
        console.log("Success!");
    }, function () {
        console.log("Oh noes!");
    });

    callback.callArg(1); // Logs "Oh noes!"
}

stub.callArgWith(argNum, [arg1, arg2, ...])

Как callArg, но с аргументами.

Асинхронные вызовы

То же, что и их соответствующие синхронные аналоги, но с отложенным вызовом колбэка после обработки всех инструкций в текущей стеке вызовов.

• В среде Node.js колбэк откладывается с помощью process.nextTick.
• В браузере колбэк откладывается с помощью setTimeout(callback, 0).

Дополнительная информация:

• https://nodejs.org/en/docs/guides/event-loop-timers-and-nexttick,
• https://developer.mozilla.org/en-US/docs/Web/JavaScript/EventLoop,
• https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout.

stub.callsArgAsync(index);

Асинхронная версия stub.callsArg(index). См. также Асинхронные вызовы.

stub.callsArgOnAsync(index, context);

Асинхронная версия stub.callsArgOn(index, context). См. также Асинхронные вызовы.

stub.callsArgWithAsync(index, arg1, arg2, ...);

Асинхронная версия stub.callsArgWith(index, arg1, arg2, …). См. также Асинхронные вызовы.

stub.callsArgOnWithAsync(index, context, arg1, arg2, ...);

Асинхронная версия stub.callsArgOnWith(index, context, arg1, arg2, …). См. также Асинхронные вызовы.

stub.yieldsAsync([arg1, arg2, ...]);

Асинхронная версия stub.yields([arg1, arg2, …]). См. также Асинхронные вызовы.

stub.yieldsOnAsync(context, [arg1, arg2, ...]);

Асинхронная версия stub.yieldsOn(context, [arg1, arg2, …]). См. также Асинхронные вызовы.

stub.yieldsToAsync(property, [arg1, arg2, ...]);

Асинхронная версия stub.yieldsTo(property, [arg1, arg2, …]). См. также Асинхронные вызовы.

stub.yieldsToOnAsync(property, context, [arg1, arg2, ...])

Асинхронная версия stub.yieldsToOn(property, context, [arg1, arg2, …]). См. также Асинхронные вызовы.

sinon.addBehavior(name, fn);

Добавляет пользовательское поведение. Имя будет доступно как функция в заглушках, и механизм цепочки вызовов будет настроен за вас (например, не нужно ничего возвращать из вашей функции, её возвращаемое значение будет проигнорировано). fn будет передан фейковый экземпляр в качестве первого аргумента, а затем аргументы пользователя.

stub.get(getterFn)

Заменяет новый геттер для этой заглушки.

stub.set(setterFn)

Определяет новый сеттер для этой заглушки.

stub.value(newVal)

Определяет новое значение для этой заглушки.

Вы можете восстановить значения, вызвав метод restore:

stub.wrappedMethod

Содержит ссылку на исходный метод/функцию, обернутую этой заглушкой.