Заглушки

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

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

Они поддерживают полный 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);

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

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