Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
jsmock - npm Package Compare versions
Comparing version 0.9.0 to 0.10.0
| { | ||
| "name": "jsmock", | ||
| "version": "0.9.0", | ||
| "version": "0.10.0", | ||
| "description": "Mocking framework for javascript", | ||
@@ -5,0 +5,0 @@ "main": "index.js", |
167
README.md
@@ -12,9 +12,10 @@ [](https://www.npmjs.org/package/jsmock) | ||
| * [Creating Mocks](#creating-mocks) | ||
| * [Defining Expectation](#defining-expectation) | ||
| * [Specifying Matcher](#specifying-matcher) | ||
| * [Specifying Cardinality](#specifying-cardinality) | ||
| * [Adding Actions](#adding-actions) | ||
| * [Defining Expectations](#defining-expectations) | ||
| * [General Syntax](#general-syntax) | ||
| * [Specifying Matcher](#specifying-matcher) | ||
| * [Specifying Cardinality](#specifying-cardinality) | ||
| * [Adding Actions](#adding-actions) | ||
| * [Verifying Mocks](#verifying-mocks) | ||
| * [Cleaning Mocks](#cleaning-mocks) | ||
| * [Examples](#license) | ||
| * [Examples](#examples) | ||
@@ -31,2 +32,11 @@ # Installation | ||
| Mock provides an API to define and verify expectations on all function calls | ||
| performed on reference to original object. A standard unit test involving mocks | ||
| will consist of following steps: | ||
| 1. Mock external dependencies of the test subject | ||
| 2. Define expectations on created mocks | ||
| 3. Execute actual tests on the subject | ||
| 4. Verify mock objects | ||
| 5. Cleanup | ||
| ## Creating Mocks | ||
@@ -52,36 +62,99 @@ ```javascript | ||
| ## Defining Expectation | ||
| Expectation of function call is defined by calling *expectCall* on mock object. | ||
| ## Defining Expectations | ||
| `Expectation` is a main component of a mock oriented test. It describes what kind | ||
| of interactions with mocked object are expected during test execution. In addition | ||
| `Expectation` also defines the actions that should be taken to _mock_ the original | ||
| object behavior. | ||
| `Expectation` for given function is defined by 3 objects: | ||
| * Matcher | ||
| * Cardinality | ||
| * Action List | ||
| __Matcher__ decides if current function call is valid for the expectation. Usually | ||
| it means that function was called with expected argument list. __Cardinality__ | ||
| describes how many times the expected call should occur. Consequently __Action List__ | ||
| provides actions to be performed by mocked object for each call. | ||
| ### General Syntax | ||
| Expectation is created by calling `expectCall` on mock object. Then it can be set up | ||
| with dedicated methods: | ||
| ```javascript | ||
| fooMock.expectCall('bar'); | ||
| fooMock.expectCall('bar') | ||
| .matching(1, 4) | ||
| .times(4) | ||
| .willOnce((a, b) => a + b) | ||
| .willRepeatedly((a, b) => a - b); | ||
| ``` | ||
| By default this will setup an expectation of single call to foo.bar function with | ||
| any arguments. As there is no action specified yet, nothing will be returned and | ||
| no side effects will be observed. | ||
| Above code will create expectation on call to `foo.bar(1,4)` that should happen | ||
| exactly 4 times. On the first call sum of the arguments will be returned, following | ||
| 3 call with return their difference. | ||
| ## Specifying Matcher | ||
| Matcher validates that call of mocked function is valid for given expectation. If | ||
| no explicit matcher is specified expectation will be executed for any call to | ||
| mocked function. Matcher can be specified as a predicate or simply as an arguments | ||
| list to be verified against actual call. | ||
| ### Specifying Matcher | ||
| Matcher is an object checking that call of mocked function is valid for given | ||
| expectation. If no explicit matcher is specified expectation will be executed for | ||
| any call to mocked function. Matcher can be specified as a predicate or simply as | ||
| an arguments list to be verified against actual call. | ||
| In *jsmock* matchers come in 3 flavours: | ||
| * Predicate Matcher - applies call arguments to provided predicate | ||
| * Strict Argument Matcher - call argument list must match exactly matcher argument list | ||
| * Weak Argument Matcher - first `N` call arguments must match matcher argument list | ||
| Matcher can be specified during `Expectation` creation with `expectCall` function, | ||
| or later with one of available `Expectation` methods. | ||
| | Method | Description | | ||
| |--------|-------------| | ||
| | `Mock.expectCall(fn, ...args)` | Creates an expectation with Strict Argument Matcher from `...args`| | ||
| | `Expectation.matching(...args)` | Creates a Strict Argument Matcher from `...args` | | ||
| | `Expectation.with(...args)` | Alias of `Expectation.matching` | | ||
| | `Expectation.matchingAtLeast(...args)` | Creates a Weak Argument Matcher from `...args` | | ||
| | `Expectation.withAtLest(...args)` | Alias of `Expectation.matchingAtLeast` | | ||
| Predicate Matcher is created automatically if one of above methods is called with | ||
| only one argument that happens to be a function. | ||
| ```javascript | ||
| fooMock.expectCall('bar', (a,b) => a > b); | ||
| fooMock.expectCall('bar', (a,b) => a > b); // Predicate Matcher | ||
| foo.bar(3,2); // OK - 3 > 2 | ||
| foo.bar(1,4); // KO | ||
| fooMock.expectCall('bar', 1, 8); | ||
| foo.bar(1, 8); // OK | ||
| foo.bar(1, 0); // KO | ||
| fooMock.expectCall('bar', 1, 8); // Strict Argument Matcher | ||
| foo.bar(1,8); // OK | ||
| foo.bar(1,0); // KO | ||
| fooMock.expectCall('bar').with(5,6); // Strict Argument Matcher | ||
| foo.bar(5,6); // OK | ||
| foo.bar(5,1); // KO | ||
| fooMock.expectCall('bar').matchingAtLeast(3); // Weak Argument Matcher | ||
| foo.bar(3,6); // OK | ||
| foo.bar(3,9); // OK | ||
| foo.bar(1,3); // KO | ||
| ``` | ||
| Matcher can be specified directly in arguments of the *expectCall* method or by | ||
| calling *matching* function on mock object. Note that *expectCall* returns mock | ||
| object making call chain possible: | ||
| #### Argument Type Matchers | ||
| *jsmock* comes with a family of predefined argument type matchers, that can be helpful | ||
| if we care more about the type of argument provided to the call than its actual value. | ||
| | Matcher | Description | | ||
| |---------|-------------| | ||
| | `Matcher.ANY` | Checks only presence of an argument in a call, doesn't care about actual type | | ||
| | `Matcher.OBJECT` | Checks if given argument is an object | | ||
| | `Matcher.NUMBER` | Checks if given argument is a number | | ||
| | `Matcher.STRING` | Checks if given argument is a string | | ||
| | `Matcher.BOOLEAN` | Checks if given argument is a boolean | | ||
| | `Matcher.FUNCTION` | Checks if given argument is a function | | ||
| | `Matcher.ARRAY` | Checks if given argument is an array | | ||
| ```javascript | ||
| fooMock.expectCall('bar').matching((a,b) => a < b); | ||
| fooMock.expectCall('bar').matching(1,4); | ||
| const Matcher = require('jsmock').Matcher; | ||
| fooMock.expectCall('bar').with(Matcher.ANY, Matcher.NUMBER); | ||
| foo.bar(1,2); // OK | ||
| foo.bar('a',2); // OK | ||
| foo.bar([1,2,3], true); // KO | ||
| ``` | ||
| ## Specifying Cardinality | ||
| ### Specifying Cardinality | ||
| Cardinality specifies number of expected calls to given function. *jsmock* provides | ||
@@ -92,2 +165,10 @@ two ways of specifying expectation cardinality. It can be provided explicitly | ||
| over one calculated from action list. | ||
| | Method | Description | | ||
| |--------|-------------| | ||
| | `Expectation.times(N)` | Matching call should occur exactly `N` times | | ||
| | `Expectation.atLeast(N)` | Matching call should occur at least `N` times | | ||
| | `Expectation.atMost(N)` | Matching call should occur at least once and at most `N` times | | ||
| | `Expectation.between(M,N)` | Matching call should occur at least `M` times and at most `N` times | | ||
| ```javascript | ||
@@ -106,6 +187,7 @@ fooMock.expectCall('bar').times(2); // Expect bar to be called twice | ||
| ## Adding Actions | ||
| ### Adding Actions | ||
| Action is an object encapsulating function to be executed instead of the original | ||
| code on mocked object. Each expectation can have multiple actions defined with | ||
| specific cardinality. Actions are executed in the order of creation. | ||
| ```javascript | ||
@@ -132,6 +214,6 @@ fooMock.expectCall('bar') | ||
| In *js* and *nodejs* it's very common to provide callback as the last argument in the | ||
| function call. Often the only purpose of the mock is to execute that callback with some | ||
| In `nodejs` (and `js` in general) it's very common to provide callback as the last argument | ||
| in the function call. Often the only purpose of the mock is to execute that callback with some | ||
| predefined arguments. This kind of action can be created easily using *will...Invoke* versions | ||
| of already presented functions: | ||
| of action create methods | ||
| ```javascript | ||
@@ -143,19 +225,14 @@ fsMock.expectCall('readdir') | ||
| fsMock.expectCall('readdir') | ||
| .willOnceInvoke((path, cb) => cb(null, ['a.js', 'b.js'])); | ||
| .willOnce((path, cb) => cb(null, ['a.js', 'b.js'])); | ||
| ``` | ||
| ### Actions and Cardinality | ||
| Combination of cardinality and action specifiers can build virtually any expectation. | ||
| ```javascript | ||
| fooMock.expectCall('bar') | ||
| .times(5) // Total number of calls expected to be 5 | ||
| .willOnce(3) // First call returns 3 | ||
| .willRepeatedly(0); // Next 4 calls returns 0 | ||
| | Method | Description | | ||
| |--------|-------------| | ||
| | `Expectation.willOnce(k)` | Adds an action to be executed once | | ||
| | `Expectation.willTwice(k)` | Adds an action to be executed twice | | ||
| | `Expectation.willRepeatedly(k)` | Adds an action to be executed until expectation cardinality is fulfilled | | ||
| | `Expectation.willOnceInvoke(...args)` | Adds an invoker action to be executed once | | ||
| | `Expectation.willTwiceInvoke(...args)` | Adds an invoker action to be executed twice | | ||
| | `Expectation.willRepeatedlyInvoke(...args)` | Adds an invoker action to be executed until expectation cardinality is fulfilled | | ||
| fooMock.expectCall('bar') | ||
| .atLeast(8) | ||
| .willRepeatedly(1); // Will always return 1 | ||
| ``` | ||
| ## Verifying Mocks | ||
@@ -201,3 +278,3 @@ Mock object will yield errors directly in case of unexpected calls or violation of | ||
| Some examples of potential "real life" usage can be found in | ||
| [example.js](jsmock/blob/master/test/example.js) test file. | ||
| [example.js](/test/example.js) test file. | ||
| ```javascript | ||
@@ -204,0 +281,0 @@ it('Should perform some fs action', (done) => { |
@@ -433,3 +433,3 @@ 'use strict'; | ||
| it('Should throw expeption if called after at least one action definition', () => { | ||
| it('Should throw exception if called after at least one action definition', () => { | ||
| let exp = new Expectation(); | ||
@@ -436,0 +436,0 @@ exp.willOnce(() => 2); |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Improved metrics
- Total package byte prevSize
- increased by3.22%
70515
- Number of lines in readme file
- increased by36.84%
286
Worsened metrics
- Number of package files
- decreased by-8.7%
21
- Lines of code
- decreased by-3.3%
1612
No dependency changes