Options
All
  • Public
  • Public/Protected
  • All
Menu

TypeScript-friendly utils for Sinon testing

This is a simple library to help create stubs with Sinon when working with TypeScript in order to leverage Sinon stubs and the type system more completely together as one without resorting to ugly, untyped hacks like casting stubbed functions to any or using associative array accesses, neither of which provide IDE-autocompletion of stub properties and methods, nor work well with stricter tsc and tslint rules applied to test sources.

API

The API consists of the following functions:

stubInterface

Used to provide a fully stubbed interface backed by an optional set of member properties which may form a subset of the overall interface. Function properties will be typed as proper SinonStubs along with any other specific type information provided by the interface.

stubObject

Returns a fully stubbed proxy similar to those provided by stubInterface, but backed first by the optionally given members, and finally by a given object. This is useful for stubbing some properties of an existing object while providing test-specific returns for fakes for others.

stubCallable

Like stubObject but works with callable TypeScript function types (i.e., functions with properties).

fromStub

When using stubObject with objects created from classes with non-public members, the resulting StubbedType<T> often needs to be passed to a function or constructor that expects a T, but TypeScript's mapped types (which are the basis of StubbedType) do not capture non-public class members. Since the StubbedType returned from stubObject is backed by a real instance of type T, it can be simply reverted to type T by using fromStub(instance). The implementation of this simply applies a type assertion, but using fromStub is preferred for clarity, especially given that this library exists to reduce the necessity of using type assertions in tests in the first place.

Index

Type aliases

OpenDictionary

OpenDictionary: Dictionary<any>

A convenience for a Dictionary of any values.

OpenFunction

OpenFunction: AnyFunction<any>

A convenience for an AnyFunction that returns any value.

Stub

Stub: V & SinonStub

A stubbed function type that has the properties of both the original function type and a SinonStub.

StubbedCallableType

StubbedCallableType: Stub<StubbedType<T> & OpenFunction>

Any StubbedType who is also a callable TypeScript function type.

StubbedType

StubbedType: object

Any type T whose function property values have been stubbed as Stub.

Type declaration

Functions

fromStub

  • Reverses the type conversion of an instance of a class from a StubbedType<T> to type the original type T. This is sometimes necessary because TypeScript's mapped types don't capture non-public class members -- as a result, StubbedType<T> must be coerced * back to T explicitly when T is a class with non-public members and is being passed to something that expects a real T value. This will typically only be needed when injecting the return of a stubObject call into a function or constructor requiring the original class type T.

    Type parameters

    • T: any

    Parameters

    Returns T

spyMethod

  • spyMethod<T>(sandbox: SinonSandbox, target: T, method: string): SinonSpy
  • Provides the ability to create a spy object on instance and prototype methods. More it specifically provides a mechanism for spying on private functions.

    Type parameters

    • T: any

    Parameters

    • sandbox: SinonSandbox

      The Sinon sandbox in which to perform the relevant stubbing.

    • target: T

      The target object of the stubbing operation.

    • method: string

      The method name of the stub.

    Returns SinonSpy

stubCallable

  • Similar to stubObject but supports callable TypeScript function types that have both a call signature and properties.

    Type parameters

    • T: any

    Parameters

    • sandbox: SinonSandbox

      The Sinon sandbox in which to perform the relevant stubbing.

    • Default value members: OpenDictionary = {}

      Optional overrides of zero or more members of the object.

    • Default value fake: OpenFunction = () => {}

    Returns StubbedCallableType<T>

stubInterface

  • Returns a proxy of an object of type T whose function properties have been replaced by properly typed Sinon stubs if not already otherwise stubbed. If the members object param is provided, the proxy will treat them as the object's real properties and functions. These values become the returns and fakes backing a well-typed mock object. This is particularly valuable when you need to provide a function or class under test with an implementation of a complex interface without having to manually create values for properties not involved in the test, such as extensive configuration interfaces.

    Any interface properties not provided by the members object will be provided by the proxy as a basic SinonStub. If this is not the desired behavior, be sure to provide your own value on the members object.

    Type parameters

    • T: any

    Parameters

    • sandbox: SinonSandbox

      The Sinon sandbox in which to perform the relevant stubbing.

    • Default value members: OpenDictionary = {}

      Optional overrides of zero or more members of the object.

    Returns StubbedType<T>

stubMethod

  • stubMethod<T>(sandbox: SinonSandbox, target: T, method: string): SinonStub
  • Provides the ability to stub methods on object instances and prototypes. More it specifically provides a mechanism for stubbing private functions.

    Type parameters

    • T: any

    Parameters

    • sandbox: SinonSandbox

      The Sinon sandbox in which to perform the relevant stubbing.

    • target: T

      The target object of the stubbing operation.

    • method: string

      The method name of the stub.

    Returns SinonStub

stubObject

  • Returns a proxy of an object of type T whose public function property values have been replaced by properly typed Sinon stubs if not already otherwise stubbed. If the members object param is provided, the proxy will treat them as the object's real properties and functions. These values become the returns and fakes backing a well-typed mock object.

    Note that when stubbing an object created from a class with non-public members, the resulting StubbedType<T> will not be accepted as a stand-in for T. In order to use the result as an instance of T (say, for dependency injection use cases), use fromStub to restore the type to T at the constrained call site.

    Type parameters

    • T: any

    Parameters

    • sandbox: SinonSandbox

      The Sinon sandbox in which to perform the relevant stubbing.

    • target: T

      The target object of the stubbing operation.

    • Default value members: OpenDictionary = {}

      Optional overrides of zero or more members of the object.

    Returns StubbedType<T>