Incomplete and incorrect sandbox documentation

[fatso83]

When researching sinonjs/sinon-test#57 I found that the documentation for sandboxes was incomplete and somewhat misleading.

Issues found

Incorrect default config

It says the sandbox is configured with the following config per default, which is incorrect:

sinon.defaultConfig = {
    // ...
    injectInto: null,
    properties: ["spy", "stub", "mock", "clock", "server", "requests"],
    useFakeTimers: true,
    useFakeServer: true
}

I do not think there is something called sinon.defaultConfig and a quick test will show that there is no server configured per default:

        var sandbox = sinonSandbox.create();
        console.log(sandbox.server) // => undefined

References removed fields

sinon.defaultConfig was removed in Sinon 2. Is still used in the docs.

Incomplete list of properties

There is no list of properties one can expose on the sandbox, but a list is given:

properties: ["spy", "stub", "mock", "clock", "server", "requests"]

One important field that is missing is sandbox which will expose the actual sandbox object, along with all of its methods. This is for instance useful when using sinon-test and you want to invoke sandbox.reset().

No example of how to use inject() or the config injectInto

The code and set of tests were pretty useful. No other examples exist in the docs. Not even mention of inject()

Incomplete API description

inject() is missing from the docs

• Sinon version : 2.3.1

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[twin-tigon]

Hi, is this issue still relevant? and if so can I work on it? 🧐

[fatso83]

I think so. And if not, it would be useful to know so that we can close this. That's also helping :-)

[twin-tigon]

Hi @fatso83,

I checked the current version of the master branch (7.5.0) to understand how the sandbox functionality works.

Then I went through the list of issues you mentioned, and I noted the following:

1. Incorrect default config
   This is now explained more in detail in the docs.

2. References removed fields
   I found that defaultConfig is exported inlib/sinon.js.

3. Incomplete list of properties
   Indeed the complete list of properties that can be injected is missing.

4. No example of how to use inject() or the config injectInto
   The injectInto is documented but not inject().

5. Incomplete API description
   See above point.

To address issues 3, 4 and 5, I'll create an example of how injectInto works. I think that will cover how inject() works and how and which properties are exposed.

I'm not sure which files to update though, is it enough if I update the file docs/_releases/latest/sandbox.md? or should I update docs/release-source/release/sandbox.md instead?

[fatso83]

See docs/CONTRIBUTING.md for details on how to contribute to the docs :-)

To address your question, update docs/release-source/release/sandbox.md. Everything under docs/_releases is in the past, so to say.

[twin-tigon]

Oh alright, I should have checked there 🙈. I'll get working on the example then, thanks for the quick reply!