From 53cca0fcbde22e05b101354b50110504cc4087c3 Mon Sep 17 00:00:00 2001 From: MrLuje Date: Sat, 25 Aug 2018 22:24:18 +0200 Subject: [PATCH] jsdoc: sinon matchers and sandbox --- types/sinon/index.d.ts | 179 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 179 insertions(+) diff --git a/types/sinon/index.d.ts b/types/sinon/index.d.ts index 5a3f98070b..ea655c610a 100644 --- a/types/sinon/index.d.ts +++ b/types/sinon/index.d.ts @@ -1180,7 +1180,17 @@ declare namespace Sinon { } interface SinonMatcher { + /** + * All matchers implement and and or. This allows to logically combine mutliple matchers. The result is a new matchers that requires both (and) or one of the matchers (or) to return true. + * @example var stringOrNumber = sinon.match.string.or(sinon.match.number); + var bookWithPages = sinon.match.instanceOf(Book).and(sinon.match.has("pages")); + */ and(expr: SinonMatcher): SinonMatcher; + /** + * All matchers implement and and or. This allows to logically combine mutliple matchers. The result is a new matchers that requires both (and) or one of the matchers (or) to return true. + * @example var stringOrNumber = sinon.match.string.or(sinon.match.number); + var bookWithPages = sinon.match.instanceOf(Book).and(sinon.match.has("pages")); + */ or(expr: SinonMatcher): SinonMatcher; test(val: any): boolean; } @@ -1235,19 +1245,62 @@ declare namespace Sinon { } interface SinonMatch { + /** + * Requires the value to be == to the given number. + */ (value: number): SinonMatcher; + /** + * Requires the value to be a string and have the expectation as a substring. + */ (value: string): SinonMatcher; + /** + * Requires the value to be a string and match the given regular expression. + */ (expr: RegExp): SinonMatcher; + /** + * See custom matchers. + */ (callback: (value: any) => boolean, message?: string): SinonMatcher; + /** + * Requires the value to be not null or undefined and have at least the same properties as expectation. + * This supports nested matchers. + */ (obj: object): SinonMatcher; + /** + * Matches anything. + */ any: SinonMatcher; + /** + * Requires the value to be defined. + */ defined: SinonMatcher; + /** + * Requires the value to be truthy. + */ truthy: SinonMatcher; + /** + * Requires the value to be falsy. + */ falsy: SinonMatcher; + /** + * Requires the value to be a Boolean + */ bool: SinonMatcher; + /** + * Requires the value to be a Number. + */ number: SinonMatcher; + /** + * Requires the value to be a String. + */ string: SinonMatcher; + /** + * Requires the value to be an Object. + */ object: SinonMatcher; + /** + * Requires the value to be a Function. + */ func: SinonMatcher; /** * Requires the value to be a Map. @@ -1261,23 +1314,84 @@ declare namespace Sinon { * Requires the value to be an Array. */ array: SinonArrayMatcher; + /** + * Requires the value to be a regular expression. + */ regexp: SinonMatcher; + /** + * Requires the value to be a Date object. + */ date: SinonMatcher; + /** + * Requires the value to be a Symbol. + */ symbol: SinonMatcher; + /** + * Requires the value to strictly equal ref. + */ same(obj: any): SinonMatcher; + /** + * Requires the value to be of the given type, where type can be one of "undefined", "null", "boolean", "number", "string", "object", "function", "array", "regexp", "date" or "symbol". + */ typeOf(type: string): SinonMatcher; + /** + * Requires the value to be an instance of the given type. + */ instanceOf(type: any): SinonMatcher; + /** + * Requires the value to define the given property. + * The property might be inherited via the prototype chain. + * If the optional expectation is given, the value of the property is deeply compared with the expectation. + * The expectation can be another matcher. + * @param property + * @param expect + */ has(property: string, expect?: any): SinonMatcher; + /** + * Same as sinon.match.has but the property must be defined by the value itself. Inherited properties are ignored. + * @param property + * @param expect + */ hasOwn(property: string, expect?: any): SinonMatcher; + /** + * Requires the value to define the given propertyPath. Dot (prop.prop) and bracket (prop[0]) notations are supported as in Lodash.get. + * The propertyPath might be inherited via the prototype chain. + * If the optional expectation is given, the value at the propertyPath is deeply compared with the expectation. + * The expectation can be another matcher. + */ hasNested(path: string, expect?: any): SinonMatcher; + /** + * Requires every element of an Array, Set or Map, or alternatively every value of an Object to match the given matcher. + */ every(matcher: SinonMatcher): SinonMatcher; + /** + * Requires any element of an Array, Set or Map, or alternatively any value of an Object to match the given matcher. + */ some(matcher: SinonMatcher): SinonMatcher; } interface SinonSandboxConfig { + /** + * The sandbox’s methods can be injected into another object for convenience. + * The injectInto configuration option can name an object to add properties to. + */ injectInto: object | null; + /** + * What properties to inject. + * Note that simply naming “server” here is not sufficient to have a server property show up in the target object, + * you also have to set useFakeServer to true. + */ properties: string[]; + /** + * If set to true, the sandbox will have a clock property. + * You can optionally pass in a configuration object that follows the specification for fake timers, such as { toFake: ["setTimeout", "setInterval"] }. + */ useFakeTimers: boolean | Partial; + /** + * If true, server and requests properties are added to the sandbox. Can also be an object to use for fake server. + * The default one is sinon.fakeServer, but if you’re using jQuery 1.3.x or some other library that does not set the XHR’s onreadystatechange handler, + * you might want to do: + */ useFakeServer: boolean | SinonFakeServer; } @@ -1347,12 +1461,25 @@ declare namespace Sinon { } interface SinonSandbox { + /** + * A convenience reference for sinon.assert + * Since sinon@2.0.0 + */ assert: SinonAssert; clock: SinonFakeTimers; requests: SinonFakeXMLHttpRequest[]; server: SinonFakeServer; + /** + * Works exactly like sinon.spy + */ spy: SinonSpyStatic; + /** + * Works exactly like sinon.stub. + */ stub: SinonStubStatic; + /** + * Works exactly like sinon.mock + */ mock: SinonMockStatic; /** @@ -1378,23 +1505,71 @@ declare namespace Sinon { * The native XMLHttpRequest object will be available at sinon.xhr.XMLHttpRequest */ useFakeXMLHttpRequest(): SinonFakeXMLHttpRequestStatic; + /** + * Fakes XHR and binds a server object to the sandbox such that it too is restored when calling sandbox.restore(). + * Access requests through sandbox.requests and server through sandbox.server + */ useFakeServer(): SinonFakeServer; + /** + * Restores all fakes created through sandbox. + */ restore(): void; + /** + * Resets the internal state of all fakes created through sandbox. + */ reset(): void; + /** + * Resets the history of all stubs created through the sandbox. + * Since sinon@2.0.0 + */ resetHistory(): void; + /** + * Resets the behaviour of all stubs created through the sandbox. + * Since sinon@2.0.0 + */ resetBehavior(): void; + /** + * Causes all stubs created from the sandbox to return promises using a specific Promise library instead of the global one when using stub.rejects or stub.resolves. + * Returns the stub to allow chaining. + * Since sinon@2.0.0 + */ usingPromise(promiseLibrary: any): SinonSandbox; + /** + * Verifies all mocks created through the sandbox. + */ verify(): void; + /** + * Verifies all mocks and restores all fakes created through the sandbox. + */ verifyAndRestore(): void; + /** + * Replaces property on object with replacement argument. Attempts to replace an already replaced value cause an exception. + * replacement can be any value, including spies, stubs and fakes. + * This method only works on non-accessor properties, for replacing accessors, use sandbox.replaceGetter() and sandbox.replaceSetter(). + */ replace( obj: T, prop: TKey, replacement: T[TKey]): T[TKey]; + /** + * Replaces getter for property on object with replacement argument. Attempts to replace an already replaced getter cause an exception. + * replacement must be a Function, and can be instances of spies, stubs and fakes. + * @param obj + * @param prop + * @param replacement + */ replaceGetter( obj: T, prop: TKey, replacement: () => T[TKey]): () => T[TKey]; + /** + * Replaces setter for property on object with replacement argument. Attempts to replace an already replaced setter cause an exception. + * replacement must be a Function, and can be instances of spies, stubs and fakes. + * @param obj + * @param prop + * @param replacement + */ replaceSetter( obj: T, prop: TKey, @@ -1426,6 +1601,10 @@ declare namespace Sinon { fakeServer: SinonFakeServerStatic; fakeServerWithClock: SinonFakeServerStatic; + /** + * Creates a new sandbox object with spies, stubs, and mocks. + * @param config + */ createSandbox(config?: Partial): SinonSandbox; defaultConfig: Partial; }