From 4fc7c65dd1ece5580d698adf9c1282e9f2683417 Mon Sep 17 00:00:00 2001 From: Morgan Roderick Date: Fri, 27 Apr 2018 11:30:08 +0100 Subject: [PATCH] Export enhanced sandbox as sinon api --- docs/release-source/release/sandbox.md | 22 +++---- docs/release-source/release/stubs.md | 18 +++++- lib/sinon.js | 80 ++++++++++++++++---------- test/behavior-test.js | 7 +-- test/sinon-test.js | 32 +++++++++++ 5 files changed, 112 insertions(+), 47 deletions(-) diff --git a/docs/release-source/release/sandbox.md b/docs/release-source/release/sandbox.md index f65ab15a8..b53eeb077 100644 --- a/docs/release-source/release/sandbox.md +++ b/docs/release-source/release/sandbox.md @@ -7,10 +7,8 @@ breadcrumb: sandbox Sandboxes removes the need to keep track of every fake created, which greatly simplifies cleanup. ```javascript -var sinon = require('sinon'); - +var sandbox = require('sinon').sandbox; var myAPI = { hello: function () {} }; -var sandbox = sinon.createSandbox(); describe('myAPI.hello method', function () { @@ -26,23 +24,26 @@ describe('myAPI.hello method', function () { it('should be called once', function () { myAPI.hello(); - sinon.assert.calledOnce(myAPI.hello); + sandbox.assert.calledOnce(myAPI.hello); }); it('should be called twice', function () { myAPI.hello(); myAPI.hello(); - sinon.assert.calledTwice(myAPI.hello); + sandbox.assert.calledTwice(myAPI.hello); }); }); ``` ## Sandbox API -#### `var sandbox = sinon.createSandbox();` +#### Default sandbox -Creates a sandbox object with spies, stubs, and mocks. +Since `sinon@5.0.0`, the `sinon` object is a default sandbox. Unless you have a very advanced setup or need a special configuration, you probably want to just use that one. + +#### `var sandbox = sinon.createSandbox();` +Creates a new sandbox object with spies, stubs, and mocks. #### `var sandbox = sinon.createSandbox(config);` @@ -129,7 +130,7 @@ A convenience reference for [`sinon.assert`](./assertions) #### `sandbox.spy();` -Works exactly like `sinon.spy`, only also adds the returned spy to the internal collection of fakes for easy restoring through `sandbox.restore()` +Works exactly like `sinon.spy` #### `sandbox.createStubInstance();` @@ -137,9 +138,8 @@ Works almost exactly like `sinon.createStubInstance`, only also adds the returne #### `sandbox.stub();` -Works almost exactly like `sinon.stub`, only also adds the returned stub to the internal collection of fakes for easy restoring through `sandbox.restore()`. +Works exactly like `sinon.stub`. -The sandbox `stub` method can also be used to stub any kind of property. This is useful if you need to override an object's property for the duration of a test, and have it restored when the test completes. ##### Stubbing a non-function property ```javascript @@ -159,7 +159,7 @@ console.log(myObject.hello); #### `sandbox.mock();` -Works exactly like `sinon.mock`, only also adds the returned mock to the internal collection of fakes for easy restoring through `sandbox.restore()` +Works exactly like `sinon.mock` #### `sandbox.useFakeTimers();` diff --git a/docs/release-source/release/stubs.md b/docs/release-source/release/stubs.md index 9974a5589..913c3ca58 100644 --- a/docs/release-source/release/stubs.md +++ b/docs/release-source/release/stubs.md @@ -63,8 +63,6 @@ calls. As of 1.8, this functionality has been removed in favor of the ### Stub API -If you need to stub getters/setters or non-function properties, then you should be using [`sandbox.stub`](../sandbox/#sandboxstub) - ### Properties #### `var stub = sinon.stub();` @@ -178,6 +176,10 @@ This is equivalent to calling both `stub.resetBehavior()` and `stub.resetHistory *Updated in `sinon@2.0.0`* +*Since `sinon@5.0.0`* + +As a convenience, you can apply `stub.reset()` to all stubs using `sinon.reset()` + #### `stub.resetBehavior();` Resets the stub's behaviour to the default behaviour @@ -194,9 +196,15 @@ stub.resetBehavior(); stub(); // undefined ``` +*Since `sinon@5.0.0`* + +You can reset behaviour of all stubs using `sinon.resetBehavior()` + #### `stub.resetHistory();` +*Since `sinon@2.0.0`* + Resets the stub's history ```javascript @@ -213,7 +221,11 @@ stub.resetHistory(); stub.called // false ``` -*Since `sinon@2.0.0`* + +*Since `sinon@5.0.0`* + +You can reset history of all stubs using `sinon.resetHistory()` + #### `stub.callsFake(fakeFunction);` Makes the stub call the provided `fakeFunction` when invoked. diff --git a/lib/sinon.js b/lib/sinon.js index 8381a70b0..a40e08d0f 100644 --- a/lib/sinon.js +++ b/lib/sinon.js @@ -1,42 +1,64 @@ "use strict"; -exports.assert = require("./sinon/assert"); -exports.match = require("./sinon/match"); -exports.spy = require("./sinon/spy"); -exports.spyCall = require("./sinon/call"); -exports.stub = require("./sinon/stub"); -exports.mock = require("./sinon/mock"); - +var behavior = require("./sinon/behavior"); +var createSandbox = require("./sinon/create-sandbox"); +var deprecated = require("./sinon/util/core/deprecated"); +var extend = require("./sinon/util/core/extend"); +var fakeTimers = require("./sinon/util/fake_timers"); +var format = require("./sinon/util/core/format"); +var nise = require("nise"); var Sandbox = require("./sinon/sandbox"); -exports.sandbox = new Sandbox(); -exports.createSandbox = require("./sinon/create-sandbox"); +var stub = require("./sinon/stub"); -exports.expectation = require("./sinon/mock-expectation"); -exports.createStubInstance = require("./sinon/stub").createStubInstance; +var apiMethods = { + createSandbox: createSandbox, + assert: require("./sinon/assert"), + match: require("./sinon/match"), + spy: require("./sinon/spy"), + spyCall: require("./sinon/call"), + stub: require("./sinon/stub"), + mock: require("./sinon/mock"), -exports.defaultConfig = require("./sinon/util/core/default-config"); + expectation: require("./sinon/mock-expectation"), + createStubInstance: require("./sinon/stub").createStubInstance, + defaultConfig: require("./sinon/util/core/default-config"), -var fakeTimers = require("./sinon/util/fake_timers"); -exports.useFakeTimers = fakeTimers.useFakeTimers; -exports.clock = fakeTimers.clock; -exports.timers = fakeTimers.timers; + setFormatter: format.setFormatter, -var nise = require("nise"); -exports.xhr = nise.fakeXhr.xhr; -exports.FakeXMLHttpRequest = nise.fakeXhr.FakeXMLHttpRequest; -exports.useFakeXMLHttpRequest = nise.fakeXhr.useFakeXMLHttpRequest; + // fake timers + useFakeTimers: fakeTimers.useFakeTimers, + clock: fakeTimers.clock, + timers: fakeTimers.timers, -exports.fakeServer = nise.fakeServer; -exports.fakeServerWithClock = nise.fakeServerWithClock; -exports.createFakeServer = nise.fakeServer.create.bind(nise.fakeServer); -exports.createFakeServerWithClock = nise.fakeServerWithClock.create.bind(nise.fakeServerWithClock); + // fake XHR + xhr: nise.fakeXhr.xhr, + FakeXMLHttpRequest: nise.fakeXhr.FakeXMLHttpRequest, + useFakeXMLHttpRequest: nise.fakeXhr.useFakeXMLHttpRequest, -var behavior = require("./sinon/behavior"); + // fake server + fakeServer: nise.fakeServer, + fakeServerWithClock: nise.fakeServerWithClock, + createFakeServer: nise.fakeServer.create.bind(nise.fakeServer), + createFakeServerWithClock: nise.fakeServerWithClock.create.bind(nise.fakeServerWithClock), -exports.addBehavior = function (name, fn) { - behavior.addBehavior(exports.stub, name, fn); + addBehavior: function (name, fn) { + behavior.addBehavior(stub, name, fn); + } }; -var format = require("./sinon/util/core/format"); -exports.setFormatter = format.setFormatter; +var legacySandboxAPI = { + sandbox: { + create: deprecated.wrap( + createSandbox, + // eslint-disable-next-line max-len + "`sandbox.create()` is deprecated. Use default sandbox at `sinon.sandbox` or create new sandboxes with `sinon.createSandbox()`" + ) + } +}; + +var sandbox = new Sandbox(); + +var api = extend(sandbox, legacySandboxAPI, apiMethods); + +module.exports = api; diff --git a/test/behavior-test.js b/test/behavior-test.js index 5fb7ac20b..bec06e246 100644 --- a/test/behavior-test.js +++ b/test/behavior-test.js @@ -1,16 +1,15 @@ "use strict"; -var createStub = require("../lib/sinon/stub"); -var addBehavior = require("../lib/sinon").addBehavior; +var sinon = require("../lib/sinon"); var assert = require("@sinonjs/referee").assert; describe("behaviors", function () { it("adds and uses a custom behavior", function () { - addBehavior("returnsNum", function (fake, n) { + sinon.addBehavior("returnsNum", function (fake, n) { fake.returns(n); }); - var stub = createStub().returnsNum(42); + var stub = sinon.stub().returnsNum(42); assert.equals(stub(), 42); }); diff --git a/test/sinon-test.js b/test/sinon-test.js index 82406013f..2e2fa788b 100644 --- a/test/sinon-test.js +++ b/test/sinon-test.js @@ -2,6 +2,7 @@ var assert = require("@sinonjs/referee").assert; var hasPromise = typeof Promise === "function"; +var Sandbox = require("../lib/sinon/sandbox"); if (!hasPromise) { return; @@ -36,7 +37,38 @@ describe("sinon module", function () { }); }); + describe("deprecated methods", function () { + it(".sandbox.create", function () { + // use full sinon for this test as it compares sinon instance + // proxyquire changes the instance, so `actual instanceof Sandbox` returns `false` + // see https://github.com/sinonjs/sinon/pull/1586#issuecomment-354457231 + sinon = require("../lib/sinon"); + + // eslint-disable-next-line max-len + var expectedMessage = "`sandbox.create()` is deprecated. Use default sandbox at `sinon.sandbox` or create new sandboxes with `sinon.createSandbox()`"; + var infoStub = sinon.stub(console, "info"); + var actual = sinon.sandbox.create(); + + sinon.assert.calledWith(infoStub, expectedMessage); + + assert.hasPrototype(actual, Sandbox.prototype); + + infoStub.restore(); + }); + }); + describe("exports", function () { + describe("default sandbox", function () { + it("should be an instance of Sandbox", function () { + // use full sinon for this test as it compares sinon instance + // proxyquire changes the instance, so `actual instanceof Sandbox` returns `false` + // see https://github.com/sinonjs/sinon/pull/1586#issuecomment-354457231 + sinon = require("../lib/sinon"); + + assert.hasPrototype(sinon, Sandbox.prototype); + }); + }); + describe("createSandbox", function () { it("should be a unary Function named 'createSandbox'", function () { assert.isFunction(sinon.createSandbox);