Sandbox

Sandbox

A Sandbox is a container for all your wrappers. It gives you a convenient way to track them, and unwrap everything when you are done with your wrappers. This is convenient for test suites, which may be wrapping and unwrapping the same objects on a regular basis.

Sandbox also has a singleton -- a single instance of a Sandbox that can be used across multiple contexts.

// create a new sandbox
sb = new Sandbox();

// create a new wrapper in the sandbox
var wrapper = sb.newWrapper(obj, method);

// destroy the sandbox, which unwraps the object
sb.destroy();

// also works with tests
it("does a test", Sandbox.test(function() {
    var wrapper = this.sandbox.newWrapper(obj, method);
}))

// the singleton is a convenient way of accessing your sandbox anywhere
function init() {
    var sb = Sandbox.singletonStart();
    sb.newWrapper(obj, method);
}

// get the same sandbox as the one in init
var sb = Sandbox.singletonGetCurrent();
sb.newWrapper(obj, method);

// unwrap all the wrappers created on the singleton
Sandbox.singletonEnd();

Constructor

new Sandbox()

Source:

Creates a new Sandbox

Methods

(static) singletonEnd() → {Sandbox}

Source:

Destroys the current sandbox singleton

Throws:

If the Sandbox Singleton hasn't been created yet (i.e. - through singletonStart)

Type
Error
Returns:

The current sandbox singleton

Type
Sandbox

(static) singletonGetCurrent() → {Sandbox}

Source:

Retreives the current sandbox singleton

Throws:

If the Snadbox Singleton hasn't been created yet (i.e. - through singletonStart)

Type
Error
Returns:

The current sandbox singleton

Type
Sandbox

(static) singletonStart() → {Sandbox}

Source:

Creates a Sandbox singleton. Future calls to Sandbox.singletonGetCurrent will retrieve the singletone. Makes it easy to work with the same Sandbox across multiple contexts.

Throws:

If the Sandbox Singleton has already been created.

Type
Error
Returns:

The Sandbox singleton, a single global singleton.

Type
Sandbox

(static) test(fn)

Source:

Creates a testing context, is designed to be passed to something like (Mocha's)[https://mochajs.org/] it() functions. The this context of the callback function will have a .sandbox value that will be a Sandbox for creating new wrappers. Any wrappers created with this.sandbox.newWrapper() will be automatically unwrapped when the test ends.

Example
it("does a test", Sandbox.test(function() {
    this.sandbox.newWrapper(...);
}))
// all wrappers are unwrapped when the sandbox exists
Parameters:
Name Type Description
fn function

The callback function that will be executed.

(static) testAsync(fn)

Source:

This is the same as test, but expects a done callback.

Example
it("does a test", Sandbox.test(function(done) {
    this.sandbox.newWrapper(...);
    done();
}))
// all wrappers are unwrapped when the sandbox exists
Parameters:
Name Type Description
fn function

The callback function that will be executed.

destroy()

Source:

Destroys a Sandbox, unwrapping all the wrappers that belong to it.

newWrapper()

Source:

The same as new Wrapper() for creating a Wrapper, but the Wrapper will be contained in the Sandbox, guaranteeing that it will be unwrapped when the Sandbox is done. See Wrapper for details on this function.