@e22m4u/js-spy

Утилита слежения за вызовом функций и методов для JavaScript. Позволяет создавать "шпионов" для функций или методов объектов, отслеживать их вызовы, аргументы, возвращаемые значения, а также управлять группой шпионов.

Содержание

• Установка
• Использование
  • Отслеживание вызова функции
  • Отслеживание вызова метода
  • Подмена реализации метода
  • Управление группой шпионов
• Плагин для Chai
• Справочник API
  • Функция
    createSpy
  • Свойства и методы шпиона
    • spy(...args)
    • spy.calls
    • spy.isCalled
    • spy.callCount
    • spy.restore()
  • Функция
    createSandbox
  • Методы песочницы
    • sandbox.on(...)
    • sandbox.restore()
• Тесты
• Лицензия

Установка

Поддержка ESM и CommonJS стандартов.

ESM

CommonJS

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

Шпионы создаются с помощью функции

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

Отслеживание вызова функции

Для перехвата вызовов отслеживаемая функция передается в качестве первого аргумента утилиты

. Результатом выполнения становится новая функция-шпион, которая используется вместо оригинальной функции.

Отслеживание вызова метода

При отслеживании метода в функцию

передается целевой объект и строковое имя метода. В этом случае оригинальный метод объекта автоматически подменяется функцией-шпионом.

Подмена реализации метода

Чтобы подменить реализацию метода, в функцию

(или

sandbox.on

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

Управление группой шпионов

Создание изолированной среды осуществляется с помощью функции

. В результате возвращается объект с методом

on

для регистрации новых шпионов и методом

restore

для их массового сброса.

Плагин для Chai

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

Подключение плагина выполняется через метод

.

Базовый пример:

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

Модификаторы:

• once
  : один раз;
• twice
  : два раза;
• exactly(n)
  : точно n раз;
• min(n)
  или
  at.least(n)
  : минимум n раз;
• max(n)
  или
  at.most(n)
  : максимум n раз;
• above(n)
  или
  gt(n)
  : больше n раз;
• below(n)
  или
  lt(n)
  : меньше n раз;

Проверка аргументов осуществляется методом

. Сравнение производится строго: количество и значения аргументов должны совпадать. Цепочка

always

позволяет утверждать, что все вызовы шпиона соответствовали условию.

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

,

second

,

third

или метод

nth(index)

.

Справочник API

Функция

createSpy

Основная функция для создания шпиона.

Сигнатуры вызова:

1. Отслеживание отдельной функции:
   

   createSpy(targetFn, [customImpl])
   • targetFn
     : Функция, которую требуется отслеживать.
   • customImpl
     (необязательно): Пользовательская функция, которая будет вызываться вместо
     targetFn
     . Должна иметь ту же сигнатуру.

2. Отслеживание метода объекта:
   

   createSpy(targetObject, methodName, [customImpl])
   • targetObject
     : Объект, метод которого будет отслеживаться.
   • methodName
     : Имя метода в
     targetObject
     , который требуется отслеживать.
   • customImpl
     (необязательно): Пользовательская функция, которая будет вызываться вместо оригинального метода. Должна иметь ту же сигнатуру.

Возвращает:

• Функция-шпион с дополнительными свойствами и методами для инспекции.

Свойства и методы шпиона

Каждая функция-шпион, возвращаемая

(или

sandbox.on

), обладает следующими свойствами и методами:

spy(...args)

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

spy.calls

• Тип:
  CallInfo[]
  (только для чтения)
• Описание: Возвращает массив вызовов.

spy.isCalled

• Тип:
  boolean
  (только для чтения)
• Описание: Указывает, был ли шпион вызван хотя бы один раз.

spy.callCount

• Тип:
  number
  (только для чтения)
• Описание: Количество раз, которое шпион был вызван.

spy.restore()

Описание:

• Восстанавливает оригинальный метод, если шпион был создан для метода объекта.
• Сбрасывает историю вызовов шпиона (
  callCount
  становится 0,
  isCalled
  становится
  false
  , и все записи о вызовах очищаются).
• Если шпион был создан для отдельной функции (а не для метода объекта), восстановление метода не происходит (так как нечего восстанавливать), но история вызовов все равно сбрасывается.

Функция

createSandbox

Фабричная функция для создания экземпляра песочницы.

Методы песочницы

Экземпляр

имеет следующие методы:

sandbox.on(...)

Создает шпиона и добавляет его в песочницу.

Сигнатуры вызова:

1. Отслеживание отдельной функции:
   

   sandbox.on(targetFn, [customImpl])

2. Отслеживание метода объекта:
   

   sandbox.on(targetObject, methodName, [customImpl])

Возвращает:

• Созданную функцию-шпион (такую же, как вернул бы
  createSpy
  ).

Пример:

sandbox.restore()

Вызывает метод

для каждого шпиона, содержащегося в песочнице. Это означает, что:

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

Возвращает:

• this
  для возможной цепочки вызовов.

Пример:

Тесты

Лицензия

MIT