Шпионы

Введение

Что такое шпион для тестирования?

Шпион для тестирования — это функция, которая записывает аргументы, возвращаемое значение, значение this и сгенерированное исключение (если таковое имеется) для всех своих вызовов. Существуют два типа шпионов: некоторые являются анонимными функциями, а другие оборачивают методы, которые уже существуют в тестируемой системе.

Создание шпиона как анонимной функции

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

Использование шпиона для обертывания всех методов объекта

sinon.spy(object)

Шпионит за все методы объекта.

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

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

Следующий пример немного искусственный:

Использование шпиона для обертывания существующего метода

sinon.spy(object, "method") создает шпиона, который оборачивает существующую функцию object.method. Шпион будет вести себя точно так же, как и исходный метод (включая использование в качестве конструктора), но у вас будет доступ к данным обо всех вызовах. Следующий пример немного искусственный:

Использование шпиона для обертывания свойств-геттеров и сеттеров

sinon.spy(object, "property", ["get", "set"]) создаёт шпионов, которые оборачивают геттеры и сеттеры для object.property. Шпионы будут вести себя точно так же, как исходные геттеры и сеттеры, но у вас будет доступ к данным обо всех вызовах. Пример:

var object = {
  get test() {
    return this.property;
  },
  set test(value) {
    this.property = value * 2;
  },
};
var spy = sinon.spy(object, "test", ["get", "set"]);
object.test = 42;
assert(spy.set.calledOnce);
assert.equals(object.test, 84);
assert(spy.get.calledOnce);

Создание шпионов: sinon.spy() Подписи методов

var spy = sinon.spy();

Создаёт анонимную функцию, которая записывает аргументы, this значение, исключения и возвращаемые значения для всех вызовов.

var spy = sinon.spy(myFunc);

Оборачивает функцию в шпиона. Вы можете передать этого шпиона туда, куда обычно передаётся оригинальная функция, чтобы проверить, как используется функция.

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

Создаёт шпиона для object.method и заменяет оригинальный метод шпионом. Если свойство не является функцией, выбрасывается исключение. Шпион ведёт себя точно как оригинальный метод во всех случаях. Оригинальный метод можно восстановить, вызвав object.method.restore(). Возвращаемый шпион — это объект функции, который заменил оригинальный метод. spy === object.method.

var spy = sinon.spy(object, "property", types);

Создаёт шпиона для свойства object.property , который заменяет дескриптор эквивалентом, где каждый указанный аксессор (параметр types) обернут как шпион. Возвращаемый объект, в отличие от обычных шпионов, представляет собой дескриптор свойства, содержащий обернутые аксессоры (шпионы). Оригинальные аксессоры можно восстановить, вызвав spy.get.restore() (где get — аксессор, который вы хотите восстановить).

API шпионов

Шпионы предоставляют богатый интерфейс для проверки их использования. В предыдущих примерах показаны свойство calledOnce типа boolean, метод getCall и свойство args возвращённого объекта. Существует три способа проверки данных вызова.

Предпочтительный подход — использование метода calledWith шпиона (и его аналогов), потому что это позволяет сделать ваш тест менее конкретным относительно того, какой вызов что делал и так далее. Он вернёт true если шпион был вызван с указанными аргументами.

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

Первый пример использует двумерный массив args непосредственно в шпионе, а второй — извлекает объект первого вызова, а затем обращается к массиву args. Какой из них использовать, зависит от предпочтений, но рекомендуемый подход — использовать spy.calledWith(arg1, arg2, ...), если нет необходимости делать тесты очень специфичными.

API

Объекты шпионов — это объекты, возвращаемые из sinon.spy(). При шпионировании существующих методов с помощью sinon.spy(object, method), следующие свойства и методы также доступны для object.method.

Свойства

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

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

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

spy.callCount

Количество записанных вызовов.

spy.called

true если шпион был вызван хотя бы один раз

spy.notCalled

true если шпион не был вызван

spy.calledOnce

true если шпион был вызван ровно один раз

spy.calledTwice

true если шпион был вызван ровно два раза

spy.calledThrice

true если шпион был вызван ровно три раза

spy.firstCall

Первый вызов

spy.secondCall

Второй вызов

spy.thirdCall

Третий вызов

spy.lastCall

Последний вызов

spy.calledBefore(anotherSpy);

Возвращает true если шпион был вызван до anotherSpy

spy.calledAfter(anotherSpy);

Возвращает true если шпион был вызван после anotherSpy

spy.calledImmediatelyBefore(anotherSpy);

Возвращает true если spy был вызван до anotherSpy, и никаких вызовов шпиона не произошло между spy и anotherSpy.

spy.calledImmediatelyAfter(anotherSpy);

Возвращает true если spy был вызван после anotherSpy, и никаких вызовов шпиона не произошло между anotherSpy и spy.

spy.calledOn(obj);

Возвращает true если шпион был вызван хотя бы один раз с obj в качестве this. calledOn также принимает матчер spyCall.calledOn(sinon.match(fn)) (см. матчеры).

spy.alwaysCalledOn(obj);

Возвращает true если шпион всегда вызывался с obj в качестве this.

spy.calledWith(arg1, arg2, ...);

Возвращает true если шпион был вызван хотя бы один раз с указанными аргументами.

Может использоваться для частичного соответствия, Sinon проверяет только указанные аргументы по фактическим аргументам, поэтому вызов, получивший указанные аргументы (в тех же местах) и, возможно, другие, также вернёт true.

spy.calledOnceWith(arg1, arg2, ...);

Возвращает true если шпион был вызван ровно один раз в целом, и этот один вызов использовал указанные аргументы.

spy.alwaysCalledWith(arg1, arg2, ...);

Возвращает true если шпион всегда вызывался с указанными аргументами (и, возможно, другими).

spy.calledWithExactly(arg1, arg2, ...);

Возвращает true если шпион был вызван хотя бы один раз с указанными аргументами и без других.

spy.calledOnceWithExactly(arg1, arg2, ...);

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

spy.alwaysCalledWithExactly(arg1, arg2, ...);

Возвращает true если шпион всегда вызывался с точными указанными аргументами.

spy.calledWithMatch(arg1, arg2, ...);

Возвращает true если шпион был вызван с соответствующими аргументами (и, возможно, другими).

Это работает так же, как и spy.calledWith(sinon.match(arg1), sinon.match(arg2), ...).

spy.alwaysCalledWithMatch(arg1, arg2, ...);

Возвращает true если шпион всегда вызывался с соответствующими аргументами (и, возможно, другими).

Это работает так же, как и spy.alwaysCalledWith(sinon.match(arg1), sinon.match(arg2), ...).

spy.calledWithNew();

Возвращает true если шпион/заглушка был вызван с оператором new.

Обратите внимание, что это определяется на основе значения объекта this и функции шпиона prototype, поэтому он может давать ложноположительные результаты, если вы активно возвращаете нужный тип объекта.

spy.neverCalledWith(arg1, arg2, ...);

Возвращает true если шпион/заглушка никогда не был вызван с указанными аргументами.

spy.neverCalledWithMatch(arg1, arg2, ...);

Возвращает true если шпион/заглушка никогда не был вызван с соответствующими аргументами.

Это работает так же, как и spy.neverCalledWith(sinon.match(arg1), sinon.match(arg2), ...).

spy.threw();

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

spy.threw("TypeError");

Возвращает true если шпион выбросил исключение указанного типа хотя бы один раз.

spy.threw(obj);

Возвращает true если шпион выбросил указанный объект исключения хотя бы один раз.

spy.alwaysThrew();

Возвращает true если шпион всегда выбросил исключение.

spy.alwaysThrew("TypeError");

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

spy.alwaysThrew(obj);

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

spy.returned(obj);

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

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

spy.alwaysReturned(obj);

Возвращает true если шпион всегда возвращал предоставленное значение.

var spyCall = spy.getCall(n);

Возвращает n-ый вызов.

Если n отрицательно, возвращается n-ый вызов с конца. Например, spy.getCall(-1) возвращает последний вызов, а spy.getCall(-2) возвращает предпоследний вызов.

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

var spyCalls = spy.getCalls();

Возвращает Array всех вызовов, зарегистрированных шпионом.

spy.thisValues

Массив объектов this, spy.thisValues[0] — это объект this для первого вызова.

spy.args

Массив полученных аргументов, spy.args[0] — это массив аргументов, полученных при первом вызове.

spy.exceptions

Массив объектов исключений, spy.exceptions[0] — это исключение, выброшенное первым вызовом.

Если вызов не сгенерировал ошибку, значение в позиции вызова в .exceptions будет undefined.

spy.returnValues

Массив возвращаемых значений, spy.returnValues[0] — это возвращаемое значение первого вызова.

Если вызов не явно вернул значение, значение в позиции вызова в .returnValues будет undefined.

spy.resetHistory();

Сбрасывает состояние шпиона.

spy.restore();

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

spy.printf("format string", [arg1, arg2, ...]);

Возвращает переданную строку формата с выполненными следующими заменями:

%n

имя шпиона "spy" по умолчанию

%c

количество вызовов шпиона в словах ("один раз", "дважды" и т.д.)

%C

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

%t

список значений this, на которых был вызван шпион, через запятую

%n

отформатированное значение n-го аргумента, переданного в printf

%*

список аргументов (кроме строки формата) передаваемых в printf, через запятую

%D

многострочный список аргументов, полученных всеми вызовами шпиона