Export enhanced sandbox as sinon api

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 `[email protected]`, 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,17 +130,16 @@ 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();`
 
 Works almost exactly like `sinon.createStubInstance`, only also adds the returned stubs to the internal collection of fakes for easy restoring through `sandbox.restore()`.
 
 #### `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();`

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 `[email protected]`*
 
+*Since `[email protected]`*
+
+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 `[email protected]`*
+
+You can reset behaviour of all stubs using `sinon.resetBehavior()`
+
 
 #### `stub.resetHistory();`
 
+*Since `[email protected]`*
+
 Resets the stub's history
 
 ```javascript
@@ -213,7 +221,11 @@ stub.resetHistory();
 stub.called // false
 ```
 
-*Since `[email protected]`*
+
+*Since `[email protected]`*
+
+You can reset history of all stubs using `sinon.resetHistory()`
+
 
 #### `stub.callsFake(fakeFunction);`
 Makes the stub call the provided `fakeFunction` when invoked.

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;

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);
     });

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);