diff --git a/docs/_releases/v1.17.6/spies.md b/docs/_releases/v1.17.6/spies.md index 2433d97ff..39e0f8be3 100644 --- a/docs/_releases/v1.17.6/spies.md +++ b/docs/_releases/v1.17.6/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -171,7 +171,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -201,22 +201,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -353,29 +353,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -413,90 +413,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v1.17.6/spy-call.md b/docs/_releases/v1.17.6/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v1.17.6/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v1.17.7/spies.md b/docs/_releases/v1.17.7/spies.md index dbe841145..c553f2e7c 100644 --- a/docs/_releases/v1.17.7/spies.md +++ b/docs/_releases/v1.17.7/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -171,7 +171,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -201,22 +201,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -353,29 +353,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -414,89 +414,4 @@ Returns the passed format string with the following replacements performed: -### Individual spy calls - - -##### `var spyCall = spy.getCall(n)` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v1.17.7/spy-call.md b/docs/_releases/v1.17.7/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v1.17.7/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.0.0/spies.md b/docs/_releases/v2.0.0/spies.md index 2fea13a8d..fea2221d6 100644 --- a/docs/_releases/v2.0.0/spies.md +++ b/docs/_releases/v2.0.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -351,29 +351,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -412,89 +412,4 @@ Returns the passed format string with the following replacements performed: -### Individual spy calls - - -##### `var spyCall = spy.getCall(n)` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.0.0/spy-call.md b/docs/_releases/v2.0.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.0.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.1.0/spies.md b/docs/_releases/v2.1.0/spies.md index 45ebe3f0e..32a8cce77 100644 --- a/docs/_releases/v2.1.0/spies.md +++ b/docs/_releases/v2.1.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -351,29 +351,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -411,90 +411,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.1.0/spy-call.md b/docs/_releases/v2.1.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.1.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.2.0/spies.md b/docs/_releases/v2.2.0/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v2.2.0/spies.md +++ b/docs/_releases/v2.2.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.2.0/spy-call.md b/docs/_releases/v2.2.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.2.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.3.0/spies.md b/docs/_releases/v2.3.0/spies.md index 49a41d978..2693764b3 100644 --- a/docs/_releases/v2.3.0/spies.md +++ b/docs/_releases/v2.3.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -424,89 +424,4 @@ Returns the passed format string with the following replacements performed: -### Individual spy calls - - -##### `var spyCall = spy.getCall(n)` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.3.0/spy-call.md b/docs/_releases/v2.3.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.3.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.3.1/spies.md b/docs/_releases/v2.3.1/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v2.3.1/spies.md +++ b/docs/_releases/v2.3.1/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.3.1/spy-call.md b/docs/_releases/v2.3.1/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.3.1/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.3.2/spies.md b/docs/_releases/v2.3.2/spies.md index 49a41d978..2693764b3 100644 --- a/docs/_releases/v2.3.2/spies.md +++ b/docs/_releases/v2.3.2/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -424,89 +424,4 @@ Returns the passed format string with the following replacements performed: -### Individual spy calls - - -##### `var spyCall = spy.getCall(n)` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.3.2/spy-call.md b/docs/_releases/v2.3.2/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.3.2/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.3.3/spies.md b/docs/_releases/v2.3.3/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v2.3.3/spies.md +++ b/docs/_releases/v2.3.3/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.3.3/spy-call.md b/docs/_releases/v2.3.3/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.3.3/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.3.4/spies.md b/docs/_releases/v2.3.4/spies.md index 49a41d978..2693764b3 100644 --- a/docs/_releases/v2.3.4/spies.md +++ b/docs/_releases/v2.3.4/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -424,89 +424,4 @@ Returns the passed format string with the following replacements performed: -### Individual spy calls - - -##### `var spyCall = spy.getCall(n)` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.3.4/spy-call.md b/docs/_releases/v2.3.4/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.3.4/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.3.5/spies.md b/docs/_releases/v2.3.5/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v2.3.5/spies.md +++ b/docs/_releases/v2.3.5/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.3.5/spy-call.md b/docs/_releases/v2.3.5/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.3.5/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.3.6/spies.md b/docs/_releases/v2.3.6/spies.md index 49a41d978..2693764b3 100644 --- a/docs/_releases/v2.3.6/spies.md +++ b/docs/_releases/v2.3.6/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -424,89 +424,4 @@ Returns the passed format string with the following replacements performed: -### Individual spy calls - - -##### `var spyCall = spy.getCall(n)` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.3.6/spy-call.md b/docs/_releases/v2.3.6/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.3.6/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.3.7/spies.md b/docs/_releases/v2.3.7/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v2.3.7/spies.md +++ b/docs/_releases/v2.3.7/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.3.7/spy-call.md b/docs/_releases/v2.3.7/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.3.7/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.3.8/spies.md b/docs/_releases/v2.3.8/spies.md index 49a41d978..e71722484 100644 --- a/docs/_releases/v2.3.8/spies.md +++ b/docs/_releases/v2.3.8/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -510,3 +510,5 @@ Exception thrown, if any. #### `spyCall.returnValue` Return value. + +[call]: ../spy-call diff --git a/docs/_releases/v2.3.8/spy-call.md b/docs/_releases/v2.3.8/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.3.8/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.4.0/spies.md b/docs/_releases/v2.4.0/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v2.4.0/spies.md +++ b/docs/_releases/v2.4.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.4.0/spy-call.md b/docs/_releases/v2.4.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.4.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v2.4.1/spies.md b/docs/_releases/v2.4.1/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v2.4.1/spies.md +++ b/docs/_releases/v2.4.1/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v2.4.1/spy-call.md b/docs/_releases/v2.4.1/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v2.4.1/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v3.0.0/spies.md b/docs/_releases/v3.0.0/spies.md index 49a41d978..e71722484 100644 --- a/docs/_releases/v3.0.0/spies.md +++ b/docs/_releases/v3.0.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -510,3 +510,5 @@ Exception thrown, if any. #### `spyCall.returnValue` Return value. + +[call]: ../spy-call diff --git a/docs/_releases/v3.0.0/spy-call.md b/docs/_releases/v3.0.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v3.0.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v3.1.0/spies.md b/docs/_releases/v3.1.0/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v3.1.0/spies.md +++ b/docs/_releases/v3.1.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v3.1.0/spy-call.md b/docs/_releases/v3.1.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v3.1.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v3.2.0/spies.md b/docs/_releases/v3.2.0/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v3.2.0/spies.md +++ b/docs/_releases/v3.2.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v3.2.0/spy-call.md b/docs/_releases/v3.2.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v3.2.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v3.2.1/spies.md b/docs/_releases/v3.2.1/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v3.2.1/spies.md +++ b/docs/_releases/v3.2.1/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v3.2.1/spy-call.md b/docs/_releases/v3.2.1/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v3.2.1/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v3.3.0/spies.md b/docs/_releases/v3.3.0/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v3.3.0/spies.md +++ b/docs/_releases/v3.3.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v3.3.0/spy-call.md b/docs/_releases/v3.3.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v3.3.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.0.0/spies.md b/docs/_releases/v4.0.0/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.0.0/spies.md +++ b/docs/_releases/v4.0.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.0.0/spy-call.md b/docs/_releases/v4.0.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.0.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.0.1/spies.md b/docs/_releases/v4.0.1/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.0.1/spies.md +++ b/docs/_releases/v4.0.1/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.0.1/spy-call.md b/docs/_releases/v4.0.1/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.0.1/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.0.2/spies.md b/docs/_releases/v4.0.2/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.0.2/spies.md +++ b/docs/_releases/v4.0.2/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.0.2/spy-call.md b/docs/_releases/v4.0.2/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.0.2/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.1.0/spies.md b/docs/_releases/v4.1.0/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.1.0/spies.md +++ b/docs/_releases/v4.1.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.1.0/spy-call.md b/docs/_releases/v4.1.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.1.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.1.1/spies.md b/docs/_releases/v4.1.1/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.1.1/spies.md +++ b/docs/_releases/v4.1.1/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.1.1/spy-call.md b/docs/_releases/v4.1.1/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.1.1/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.1.2/spies.md b/docs/_releases/v4.1.2/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.1.2/spies.md +++ b/docs/_releases/v4.1.2/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.1.2/spy-call.md b/docs/_releases/v4.1.2/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.1.2/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.1.3/spies.md b/docs/_releases/v4.1.3/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.1.3/spies.md +++ b/docs/_releases/v4.1.3/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.1.3/spy-call.md b/docs/_releases/v4.1.3/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.1.3/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.1.4/spies.md b/docs/_releases/v4.1.4/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.1.4/spies.md +++ b/docs/_releases/v4.1.4/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.1.4/spy-call.md b/docs/_releases/v4.1.4/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.1.4/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.1.5/spies.md b/docs/_releases/v4.1.5/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.1.5/spies.md +++ b/docs/_releases/v4.1.5/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.1.5/spy-call.md b/docs/_releases/v4.1.5/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.1.5/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.1.6/spies.md b/docs/_releases/v4.1.6/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.1.6/spies.md +++ b/docs/_releases/v4.1.6/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.1.6/spy-call.md b/docs/_releases/v4.1.6/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.1.6/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.2.0/spies.md b/docs/_releases/v4.2.0/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.2.0/spies.md +++ b/docs/_releases/v4.2.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.2.0/spy-call.md b/docs/_releases/v4.2.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.2.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.2.1/spies.md b/docs/_releases/v4.2.1/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.2.1/spies.md +++ b/docs/_releases/v4.2.1/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.2.1/spy-call.md b/docs/_releases/v4.2.1/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.2.1/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.2.2/spies.md b/docs/_releases/v4.2.2/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.2.2/spies.md +++ b/docs/_releases/v4.2.2/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.2.2/spy-call.md b/docs/_releases/v4.2.2/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.2.2/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.2.3/spies.md b/docs/_releases/v4.2.3/spies.md index 552f60f4a..0c083bba1 100644 --- a/docs/_releases/v4.2.3/spies.md +++ b/docs/_releases/v4.2.3/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -363,29 +363,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -423,90 +423,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.2.3/spy-call.md b/docs/_releases/v4.2.3/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.2.3/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.3.0/spies.md b/docs/_releases/v4.3.0/spies.md index 928919129..8a5323ca9 100644 --- a/docs/_releases/v4.3.0/spies.md +++ b/docs/_releases/v4.3.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -431,90 +431,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.3.0/spy-call.md b/docs/_releases/v4.3.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.3.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.0/spies.md b/docs/_releases/v4.4.0/spies.md index 928919129..8a5323ca9 100644 --- a/docs/_releases/v4.4.0/spies.md +++ b/docs/_releases/v4.4.0/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -431,90 +431,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.0/spy-call.md b/docs/_releases/v4.4.0/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.0/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.1/spies.md b/docs/_releases/v4.4.1/spies.md index 928919129..8a5323ca9 100644 --- a/docs/_releases/v4.4.1/spies.md +++ b/docs/_releases/v4.4.1/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -431,90 +431,4 @@ Returns the passed format string with the following replacements performed:
a comma-delimited list of the (non-format string) arguments passed to printf
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.1/spy-call.md b/docs/_releases/v4.4.1/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.1/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.10/spies.md b/docs/_releases/v4.4.10/spies.md index d1a554d42..40f321c7e 100644 --- a/docs/_releases/v4.4.10/spies.md +++ b/docs/_releases/v4.4.10/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -435,90 +435,4 @@ Returns the passed format string with the following replacements performed:
a multi-line list of the arguments received by all calls to the spy
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.10/spy-call.md b/docs/_releases/v4.4.10/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.10/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.2/spies.md b/docs/_releases/v4.4.2/spies.md index f42e28db1..607f42657 100644 --- a/docs/_releases/v4.4.2/spies.md +++ b/docs/_releases/v4.4.2/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -518,3 +518,5 @@ Exception thrown, if any. #### `spyCall.returnValue` Return value. + +[call]: ../spy-call diff --git a/docs/_releases/v4.4.2/spy-call.md b/docs/_releases/v4.4.2/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.2/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.3/spies.md b/docs/_releases/v4.4.3/spies.md index d1a554d42..40f321c7e 100644 --- a/docs/_releases/v4.4.3/spies.md +++ b/docs/_releases/v4.4.3/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -435,90 +435,4 @@ Returns the passed format string with the following replacements performed:
a multi-line list of the arguments received by all calls to the spy
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.3/spy-call.md b/docs/_releases/v4.4.3/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.3/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.4/spies.md b/docs/_releases/v4.4.4/spies.md index d1a554d42..40f321c7e 100644 --- a/docs/_releases/v4.4.4/spies.md +++ b/docs/_releases/v4.4.4/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -435,90 +435,4 @@ Returns the passed format string with the following replacements performed:
a multi-line list of the arguments received by all calls to the spy
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.4/spy-call.md b/docs/_releases/v4.4.4/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.4/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.5/spies.md b/docs/_releases/v4.4.5/spies.md index d1a554d42..40f321c7e 100644 --- a/docs/_releases/v4.4.5/spies.md +++ b/docs/_releases/v4.4.5/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -435,90 +435,4 @@ Returns the passed format string with the following replacements performed:
a multi-line list of the arguments received by all calls to the spy
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.5/spy-call.md b/docs/_releases/v4.4.5/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.5/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.6/spies.md b/docs/_releases/v4.4.6/spies.md index d1a554d42..40f321c7e 100644 --- a/docs/_releases/v4.4.6/spies.md +++ b/docs/_releases/v4.4.6/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -435,90 +435,4 @@ Returns the passed format string with the following replacements performed:
a multi-line list of the arguments received by all calls to the spy
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.6/spy-call.md b/docs/_releases/v4.4.6/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.6/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.7/spies.md b/docs/_releases/v4.4.7/spies.md index d1a554d42..40f321c7e 100644 --- a/docs/_releases/v4.4.7/spies.md +++ b/docs/_releases/v4.4.7/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -435,90 +435,4 @@ Returns the passed format string with the following replacements performed:
a multi-line list of the arguments received by all calls to the spy
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.7/spy-call.md b/docs/_releases/v4.4.7/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.7/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.8/spies.md b/docs/_releases/v4.4.8/spies.md index d1a554d42..40f321c7e 100644 --- a/docs/_releases/v4.4.8/spies.md +++ b/docs/_releases/v4.4.8/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -435,90 +435,4 @@ Returns the passed format string with the following replacements performed:
a multi-line list of the arguments received by all calls to the spy
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.8/spy-call.md b/docs/_releases/v4.4.8/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.8/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/_releases/v4.4.9/spies.md b/docs/_releases/v4.4.9/spies.md index d1a554d42..40f321c7e 100644 --- a/docs/_releases/v4.4.9/spies.md +++ b/docs/_releases/v4.4.9/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,29 +371,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -435,90 +435,4 @@ Returns the passed format string with the following replacements performed:
a multi-line list of the arguments received by all calls to the spy
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n);` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/_releases/v4.4.9/spy-call.md b/docs/_releases/v4.4.9/spy-call.md new file mode 100644 index 000000000..660eaac56 --- /dev/null +++ b/docs/_releases/v4.4.9/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n);` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue;` + +The call's `this` value. + + +### `spyCall.args;` + +Array of received arguments. + + +### `spyCall.exception;` + +Exception thrown, if any. + + +### `spyCall.returnValue;` + +Return value. diff --git a/docs/api/v1.17.3/spies/index.md b/docs/api/v1.17.3/spies/index.md index bd409acb9..d38b71d8d 100644 --- a/docs/api/v1.17.3/spies/index.md +++ b/docs/api/v1.17.3/spies/index.md @@ -8,7 +8,7 @@ title: Spies - Sinon.JS ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -17,7 +17,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -37,7 +37,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -107,7 +107,7 @@ console.log('callCount:', descriptor.get.callCount); // callCount: 1 Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -127,7 +127,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -154,7 +154,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -171,7 +171,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -191,7 +191,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -221,22 +221,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -373,29 +373,29 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. @@ -522,3 +522,5 @@ Exception thrown, if any. Return value.]}]} [getOwnPropertyDescriptor]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor + +[call]: ../spy-call diff --git a/docs/release-source/release.md b/docs/release-source/release.md index fb8e0ae2d..ba046bbbe 100644 --- a/docs/release-source/release.md +++ b/docs/release-source/release.md @@ -11,6 +11,7 @@ This page contains the entire Sinon.JS API documentation along with brief int * [Spies](./spies) * [Stubs](./stubs) * [Mocks](./mocks) +* [Spy calls](./spy-call) * [Fake timers](./fake-timers) * [Fake XHR and server](./fake-xhr-and-server) * [JSON-P](./json-p) diff --git a/docs/release-source/release/spies.md b/docs/release-source/release/spies.md index 746035f5c..40f321c7e 100644 --- a/docs/release-source/release/spies.md +++ b/docs/release-source/release/spies.md @@ -9,7 +9,7 @@ breadcrumb: spies ### What is a test spy? A test spy is a function that records arguments, return value, the value of -`this` and exception thrown (if any) for all its calls. There are two types of spies: +`this` and exception thrown (if any) for all its [calls][call]. There are two types of spies: Some are anonymous functions, while others wrap methods that already exist in the system under test. @@ -18,7 +18,7 @@ the system under test. When the behavior of the spied-on function is not under test, you can use an anonymous function spy. The spy won't do anything except record information -about its calls. A common use case for this type of spy is testing how a function +about its [calls][call]. A common use case for this type of spy is testing how a function handles a callback, as in the following simplified example: ```javascript @@ -38,7 +38,7 @@ handles a callback, as in the following simplified example: `sinon.spy(object, "method")` creates a spy that wraps the existing function `object.method`. The spy will behave exactly like the original method (including when used as a constructor), but you will have access to data about -all calls. The following is a slightly contrived example: +all [calls][call]. The following is a slightly contrived example: ```javascript { @@ -87,7 +87,7 @@ all calls. The following is a slightly contrived example: Spies provide a rich interface to inspect their usage. The above examples showed the `calledOnce` boolean property as well as the `getCall` method and the -returned object's `args` property. There are three ways of inspecting call data. +returned object's `args` property. There are three ways of inspecting [call][call] data. The preferred approach is to use the spy's `calledWith` method (and friends) because it keeps your test from being too specific about which call did what and @@ -107,7 +107,7 @@ arguments. ``` If you want to be specific, you can directly check the first argument of the -first call. There are two ways of achieving this: +first [call][call]. There are two ways of achieving this: ```javascript "test should call subscribers with message as first argument" : function () { @@ -134,7 +134,7 @@ first call. There are two ways of achieving this: ``` The first example uses the two-dimensional `args` array directly on the spy, -while the second example fetches the first call object and then accesses its +while the second example fetches the first [call][call] object and then accesses its `args` array. Which one to use is a matter of preference, but the recommended approach is going with `spy.calledWith(arg1, arg2, ...)` unless there's a need to make the tests highly specific. @@ -151,7 +151,7 @@ are also available on `object.method`. #### `spy.withArgs(arg1[, arg2, ...]);` -Creates a spy that only records calls when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same call. +Creates a spy that only records [calls][call] when the received arguments match those passed to `withArgs`. This is useful to be more expressive in your assertions, where you can access the spy with the same [call][call]. ```javascript "should call method once with each argument": function () { @@ -169,7 +169,7 @@ Creates a spy that only records calls when the received arguments match those pa #### `spy.callCount` -The number of recorded calls. +The number of recorded [calls][call]. #### `spy.called` @@ -199,22 +199,22 @@ The number of recorded calls. #### `spy.firstCall` -The first call +The first [call][call] #### `spy.secondCall` -The second call +The second [call][call] #### `spy.thirdCall` -The third call +The third [call][call] #### `spy.lastCall` -The last call +The last [call][call] #### `spy.calledBefore(anotherSpy);` @@ -229,13 +229,13 @@ Returns `true` if the spy was called after `anotherSpy` #### `spy.calledImmediatelyBefore(anotherSpy);` -Returns `true` if `spy` was called before `anotherSpy`, and no spy calls +Returns `true` if `spy` was called before `anotherSpy`, and no spy [calls][call] occurred between `spy` and `anotherSpy`. #### `spy.calledImmediatelyAfter(anotherSpy);` -Returns `true` if `spy` was called after `anotherSpy`, and no spy calls +Returns `true` if `spy` was called after `anotherSpy`, and no spy [calls][call] occurred between `anotherSpy` and `spy`. @@ -371,44 +371,44 @@ assertEquals("/stuffs", spyCall.args[0]); #### `var spyCalls = spy.getCalls();` -Returns an `Array` of all [calls](#spycall) recorded by the spy. +Returns an `Array` of all [calls][call] recorded by the spy. #### `spy.thisValues` -Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first call. +Array of `this` objects, `spy.thisValues[0]` is the `this` object for the first [call][call]. #### `spy.args` -Array of arguments received, `spy.args[0]` is an array of arguments received in the first call. +Array of arguments received, `spy.args[0]` is an array of arguments received in the first [call][call]. #### `spy.exceptions` -Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first call. +Array of exception objects thrown, `spy.exceptions[0]` is the exception thrown by the first [call][call]. If the call did not throw an error, the value at the call's location in `.exceptions` will be `undefined`. #### `spy.returnValues` -Array of return values, `spy.returnValues[0]` is the return value of the first call. +Array of return values, `spy.returnValues[0]` is the return value of the first [call][call]. If the call did not explicitly return a value, the value at the call's location in `.returnValues` will be `undefined`. -#### `spy.resetHistory()` +#### `spy.resetHistory();` Resets the state of a spy. -#### `spy.restore()` +#### `spy.restore();` Replaces the spy with the original method. Only available if the spy replaced an existing method. -#### `spy.printf("format string", [arg1, arg2, ...])` +#### `spy.printf("format string", [arg1, arg2, ...]);` Returns the passed format string with the following replacements performed: @@ -435,90 +435,4 @@ Returns the passed format string with the following replacements performed:
a multi-line list of the arguments received by all calls to the spy
- -### Individual spy calls - - -##### `var spyCall = spy.getCall(n)` - -Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. - -```javascript -sinon.spy(jQuery, "ajax"); -jQuery.ajax("/stuffs"); -var spyCall = jQuery.ajax.getCall(0); - -assertEquals("/stuffs", spyCall.args[0]); -``` - - -#### `spyCall.calledOn(obj);` - -Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). - - -#### `spyCall.calledWith(arg1, arg2, ...);` - -Returns `true` if call received provided arguments (and possibly others). - - -#### `spyCall.calledWithExactly(arg1, arg2, ...);` - -Returns `true` if call received provided arguments and no others. - - -#### `spyCall.calledWithMatch(arg1, arg2, ...);` - -Returns `true` if call received matching arguments (and possibly others). -This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - - -#### `spyCall.notCalledWith(arg1, arg2, ...);` - -Returns `true` if call did not receive provided arguments. - - -#### `spyCall.notCalledWithMatch(arg1, arg2, ...);` - -Returns `true` if call did not receive matching arguments. -This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. - -#### `spyCall.returned(value);` - -Returns `true` if spied function returned the provided `value` on this call. - -Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). - -#### `spyCall.threw();` - -Returns `true` if call threw an exception. - - -#### `spyCall.threw("TypeError");` - -Returns `true` if call threw exception of provided type. - - -#### `spyCall.threw(obj);` - -Returns `true` if call threw provided exception object. - - -#### `spyCall.thisValue` - -The call's `this` value. - - -#### `spyCall.args` - -Array of received arguments. - - -#### `spyCall.exception` - -Exception thrown, if any. - - -#### `spyCall.returnValue` - -Return value. +[call]: ../spy-call diff --git a/docs/release-source/release/spy-call.md b/docs/release-source/release/spy-call.md new file mode 100644 index 000000000..2563045b7 --- /dev/null +++ b/docs/release-source/release/spy-call.md @@ -0,0 +1,93 @@ +--- +layout: page +title: Spy call - Sinon.JS +breadcrumb: spy-call +--- + +## Spy call + +A spy call is an object representation of an invididual call to a *spied* function, which could be a [spy](../spies), [stub](../stubs) or [mock method](../mocks). + +### `var spyCall = spy.getCall(n)` + +Returns the *nth* [call](#spycall). Accessing individual calls helps with more detailed behavior verification when the spy is called more than once. + +```javascript +sinon.spy(jQuery, "ajax"); +jQuery.ajax("/stuffs"); +var spyCall = jQuery.ajax.getCall(0); + +assertEquals("/stuffs", spyCall.args[0]); +``` + + +### `spyCall.calledOn(obj);` + +Returns `true` if `obj` was `this` for this call. `calledOn` also accepts a matcher `spyCall.calledOn(sinon.match(fn))` (see [matchers](#matchers)). + + +### `spyCall.calledWith(arg1, arg2, ...);` + +Returns `true` if call received provided arguments (and possibly others). + + +### `spyCall.calledWithExactly(arg1, arg2, ...);` + +Returns `true` if call received provided arguments and no others. + + +### `spyCall.calledWithMatch(arg1, arg2, ...);` + +Returns `true` if call received matching arguments (and possibly others). +This behaves the same as `spyCall.calledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + + +### `spyCall.notCalledWith(arg1, arg2, ...);` + +Returns `true` if call did not receive provided arguments. + + +### `spyCall.notCalledWithMatch(arg1, arg2, ...);` + +Returns `true` if call did not receive matching arguments. +This behaves the same as `spyCall.notCalledWith(sinon.match(arg1), sinon.match(arg2), ...)`. + +### `spyCall.returned(value);` + +Returns `true` if spied function returned the provided `value` on this call. + +Uses deep comparison for objects and arrays. Use `spyCall.returned(sinon.match.same(obj))` for strict comparison (see [matchers](#matchers)). + +### `spyCall.threw();` + +Returns `true` if call threw an exception. + + +### `spyCall.threw("TypeError");` + +Returns `true` if call threw exception of provided type. + + +### `spyCall.threw(obj);` + +Returns `true` if call threw provided exception object. + + +### `spyCall.thisValue` + +The call's `this` value. + + +### `spyCall.args` + +Array of received arguments. + + +### `spyCall.exception` + +Exception thrown, if any. + + +### `spyCall.returnValue` + +Return value.