National Puppy Menace

    js-mock

    2.0.0 • Public • Published

    JsMock

    Build Status Dependency Status Coverage Status

    A JavaScript mocking framework, which can be used with any test framework. JsMock is inspired by jMock and Sinon.js with its interface being very similar to Sinon in order to make it easy to switch between those two frameworks.

    JsMock should work with any test framework.

    How is JsMock different from other mock frameworks?

    JsMock only supports mock objects where the expectations have to be defined before the mock objects are used by the function/module under test. This may require a bit more effort when writing a test case, but the outcome should be that the interactions of the unit under test with the mock object are very clearly defined through the tests. This should expose bugs or unintended behavior that would otherwise remain hidden if stubs or spies are used, but not evaluated properly.

    JsMock also has the goal to simplify the setup and validation of mocks by monitoring them for you. This will make it easy to evaluate that all expected calls have been made at the end of a test.

    Installation

    Install JsMock via npm

    $ npm install js-mock --save-dev
    

    and include node_modules/js-mock/dist/js-mock.js in your project.

    Or install it using Bower

    $ bower install js-mock --save-dev
    

    and include bower_components/js-mock/dist/js-mock.js in your project.

    Getting Started

    The following list highlights some simple use cases of JsMock and includes some best practices. For a full reference, please check out the API docs or take a look at the unit tests.

    Include JsMock in Your Tests

    //ES6 module import
    import JsMock from 'js-mock';
    
    //ES5 module import
    var JsMock = require('js-mock').default;
    

    JsMock.mock()

    JsMock can create mock functions or objects.

    var mockFunc = JsMock.mock("nameOfFunction");
    
    var objectToMock = {
      doSomething: function () {
        // does something
      }
    };
    
    // Note: Returns a mock clone, the original object will not be modified.
    var mockObject = JsMock.mock("nameOfObject", objectToMock);
    
    // It's possible to also pass in other libraries, but the original will not be replaced in this case
    var jqueryMock = JsMock.mock("$", $);
    

    JsMock.mockGlobal()

    JsMock can also replace global variables with a mock object and restore the original at any time. The global mock will automatically be activated, meaning that the global reference was replaced with the mock object. Like any other mock object, the global mock can be verfied at any time with a single call.

    var jqueryMock = JsMock.mockGlobal("$");
    
    jqueryMock.expect().ajax.once();
    
    // Fulfill the expectation
    $.ajax();
    
    // Restore jQuery to be the original API and not the mock anymore.
    // This will also verify that all expectations have been fulfilled
    jqueryMock.restore();
    

    More examples on how to use JsMock.mockGlobal() can be found in its test file.

    JsMock.watch()

    When testing a module or file, the best way is to define a set of global mocks using the watch() function, which can be shared between the test cases. All mocks created inside the factory function will be added to the current test context and can be verified with a single call to JsMock.assertWatched().

    var mockFunction1, mockFunction2;
    JsMock.watch(function () {
      mockFunction1 = JsMock.mock("name1");
      mockFunction2 = JsMock.mock("name2");
    });
    

    JsMock.assertWatched()

    Calling this function will go through the list of all mocks that are currently monitored and will call .verify() on each of them. Should a mock fail the validation, an ExpectationError will be thrown. The functions returns true if all mocks were satisfied, which can be used to pass a simple assertion. Any monitored global mock will also be restored when .assertWatched() is called.

    var mockFunction1, mockFunction2, jQueryMock;
    JsMock.watch(function () {
      mockFunction1 = JsMock.mock("name1");
      mockFunction2 = JsMock.mock("name2");
    
      jQueryMock = JsMock.mockGlobal("$");
    });
    
    // Verify all monitored mocks and restore globals
    JsMock.assertWatched();
    

    If the test case requires an assertion, the following could be done:

    var mockFunction1;
    JsMock.watch(function () {
      mockFunction1 = JsMock.mock("name1");
    });
    
    // Verify all monitored mocks
    assert.ok(JsMock.assertWatched());
    

    mock.exactly()

    Set the expectation for the mock to be called N number of times.

    var mock = JsMock.mock("aMock");
    
    // Expect the mock to be invoked 4 times
    mock.exactly(4);
    

    mock.with(...)

    Set the expectation to be called with the exact arguments provided. Any of the given arguments can be a Hamjest style matcher. If a matcher is provided as an argument, the actual argument will be passed on to the matches() function of the matcher object.

    var mock = JsMock.mock("aMock");
    
    // Expect to be called like this: mock("foo", "bar");
    mock.once().with("foo", "bar");
    

    mock.returns()

    Set the expectation for the mock to return a given value.

    var mock = JsMock.mock("aMock");
    
    // Expect the mock to be invoked once with no arguments, returning "foo"
    mock.once().with().returns("foo")
    
    var x = "foo" === mock(); // true
    

    mock.throws()

    Set the expectation for the mock to the given exception.

    var mock = JsMock.mock("aMock");
    
    // Expect the mock to be invoked once with no arguments
    mock.once().with().throws(new Error("foo"))
    
    mock(); // will throw an Error with the message "foo"
    

    mock.will()

    Will execute the given function once the mock was successfully called. The arguments passed to the mock function will be forwarded to the provided function and the value returned by the given function will also be returned by the mock.

    var mock = JsMock.mock("aMock");
    
    // Expect the mock to be invoked once with any arguments
    mock.once().will(function (arg) {
      var x = arg; // x == "foo"
      return x + "bar";
    });
    
    var y = mock("foo"); // y == "foobar"
    

    mock.willThrow()

    Executes a function if the mock was successfully matched. All arguments passed in to the mock function will be passed on to the function defined in here. The function will be executed immediately and is expected to throw an exception. If it does not throw and expection, an ExpectationError will be thrown.

    var mock = JsMock.mock("aMock");
    
    mock.once().willThrow(function (arg) {
      var x = arg; // x == "foo"
      return new Error("bar");
    });
    
    mock("foo"); // will throw an Error with the message "bar"
    

    mock.onCall()

    Will set all following expectations for the given call.

    var mock = JsMock.mock("aMock");
    
    // Expect the mock to be invoked 2 times
    mock.exactly(2);
    
    // On the first call, expect "foo" to be the argument and return 1
    mock.onCall(1).with("foo").returns(1);
    
    // On the second call, expect "bar" to be the argument and return 2
    mock.onCall(2).with("bar").returns(2);
    

    mock.allowing()

    Converts this mock into a stub, which will never throw a missing invocation error. As a stub, it cannot have different behaviors for different calls. If withExactArgs is defined, any invocation other than the defined one will throw an unexpected invocation error. Note: Verifying the stub will reset the object into mocking mode with 0 calls expected.

    var mock = JsMock.mock("aMock");
    
    // Allows the mock to be invoked as often as possible
    mock.allowing();
    
    mock("foo");
    mock("bar");
    
    // will always succeed and reset the mock
    mock.verify();
    

    mock.verify()

    Verifies that all expectations of this mock have been fulfilled. If any expectation was not fullfiled, an ExpectationError will be thrown.

    var mock = JsMock.mock("aMock");
    
    // Expect the mock to be invoked once
    mock.once();
    
    // will throw an ExpectationError
    mock.verify();
    

    If the test case requires an assertion, the following could be done:

    var mock = JsMock.mock("aMock");
    
    // Expect the mock to be invoked once
    mock.once();
    
    mock();
    
    // Verify all expectations of this mock
    assert.ok(mock.verify());
    

    Aliases and Helpers

    The following functions are helpers that will map their calls to the API functions above.

    mock.never() // instead of .exactly(0)
    mock.once() // instead of .exactly(1)
    mock.twice() // instead of .exactly(2)
    mock.thrice() // instead of .exactly(3)
    
    mock.onFirstCall() // instead of .onCall(1)
    mock.onSecondCall() // instead of .onCall(2)
    mock.onThirdCall() // instead of .onCall(3)
    
    mock.withExactArgs(<anything>...) // instead of .with(<anything>...)
    

    Frameworks and Best Practices

    While JsMock is test framework independent, there are best practices when using it with a framework. In general, it is important to understand how the test framework loads and executes its tests. Especially when JsMock.watch() is used, it is crucial to ensure that it governs the context of the current test file, otherwise your tests may pass with unfulfilled expecations. Below are some examples on how to use JsMock with Jasmine and QUnit.

    Jasmine

    describe("A Test", function {
    
      var mockFunc, jQueryMock;
    
      beforeEach(function () {
        JsMock.watch(function () {
          mockFunc = JsMock.mock("mockFunc");
          jQueryMock = JsMock.mockGlobal("$");
        }
      });
    
      afterEach(JsMock.assertWatched);
    
      it ("test 1", function() {
        // set expectations and test
      });
    
      it ("test 2", function() {
        // set expectations and test
      });
    });
    

    QUnit

    var mockFunc, jQueryMock;
    
    QUnit.module("A test", {
      beforeEach: function () {
        JsMock.watch(function () {
          mockFunc = JsMock.mock("mockFunc");
          jQueryMock = JsMock.mockGlobal("$");
        }
      },
      afterEach: function (assert) {
        assert.ok(JsMock.assertWatched());
      }
    });
    
    QUnit.test("test 1", function(assert) {
      // set expectations and test
    });
    
    QUnit.test("test 2", function(assert) {
      // set expectations and test
    });
    

    Hamjest

    While JsMock does not have any dependencies, it does support Hamjest for the matching of arguments when using with() or withExactArgs(). Hamjest has a vast number of existing matchers that can be used to validate an argument. And should there not be the right matcher available, you can easily write your own implementation.

    var mock = JsMock.mock("aMock");
    
    mock.once().with(hamjest.contains("foo", "bar"));
    
    mock(["foo", "bar"]);
    mock.verify();
    
    mock.thrice().with(hamjest.greaterThan(3));
    
    mock(4);
    mock(6);
    mock(7);
    
    mock.verify();
    

    API Docs

    The full API documentation can be found here.

    License

    BSD 3-clause, see License.txt

    js-api generator

    Changelog

    2.0.0

    • Removed built-in dependency on JsHamcrest, it can still be used to pass a Matcher as an argument
    • Removed Mock.withEquivalentArray()
    • Removed Mock.withEquivalentObject()
    • HamJest matchers are now supported
    • Improved error messages for unexpected invocations of a Mock
    • Added ES6 support through Babel compiler

    For older versions, please read the CHANGELOG.md file.

    Install

    npm i js-mock

    DownloadsWeekly Downloads

    137

    Version

    2.0.0

    License

    BSD-3-Clause

    Unpacked Size

    101 kB

    Total Files

    6

    Last publish

    Collaborators

    • jfischer