Заглушки

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

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

Они поддерживают полный 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-подобных флюидных API.

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 с указанными аргументами.

Если заглушка никогда не вызывалась с аргументом-функцией, 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 обратный вызов откладывается с помощью 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

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