Wrapper for browser natives to allow stubbing in unit tests
JavaScript Shell
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
lib Support Node.js Sep 15, 2015
scripts Add scripts/run-tests Sep 21, 2015
test
.editorconfig Initial import Mar 3, 2015
.gitignore Initial commit Mar 3, 2015
.jsbeautifyrc Setup tooling Mar 4, 2015
.jscsrc Setup tooling Mar 4, 2015
.travis.yml Add scripts/run-tests Sep 21, 2015
CONTRIBUTING.md Update .md files Mar 23, 2015
Gruntfile.js Setup tooling Mar 4, 2015
README.md Update README.md Sep 20, 2015
bower.json 0.4.0 Jul 21, 2016
package.json
version Add versioning script Mar 4, 2015

README.md

wrapple travis build dependencies dependencies

Dependency free wrapping function for browser natives to allow stubbing in unit tests.

Accessing natives through a thin wrapper makes stubbing possible, where it would otherwise be impossible.

You can use it with pretty much all globals defined on the window object.

Link Seam

In Working Effectively with Legacy Code, Michael Feathers describes Seams. In the vernacular of that book, wrapple would most likely be described as a Link Seam.

Compatibility

wrapple should be able to run in most environments that can execute JavaScript

ES5.1 required

wrapple uses a couple of methods from ES5.1

If you need to support old browsers, you should ensure that these have been polyfilled.

Node.js supported

wrapple can work in Node.js environments just like in browser environments.

Usage

Access browser natives through wrapple

Step 1

// use whatever local name you like
var wrap = require('wrapple');

// ensure that wrapple has wrapped the property you're interested in
// this is idempotent, call it many times with no ill effects
wrap('location');

// directly use the returned global
var hostname = wrap('location').hostname;

Step 2

Now that your application code is using wrapped globals, you can target the wrapper function for stubbing, spying, etc.

var stub = sinon.stub(wrap, 'location', function(){
    return {
        hostname: 'wrapple.example.com'
    };
});

// ...

Step 3

Tidy up your tests

// using sinon
stub.restore();

// or using wrapple.reset
wrap.reset();

Methods

wrap

// wrap - adds a wrapped property method to the wrapple api
// returns a function that returns window.location
// also creates wrap.location method as target for stubbing
wrap('location');

// add and use immediately
var hostname = wrap('location').hostname;

// use via dedicated method
wrap('location');
// ...
var hostname = wrap.location().hostname;

reset

// reset, removes all wrapper methods from wrapple api
wrap.reset();

Unwrappable methods

These globals on the window object are not wrappable, as creating the returning methods on wrapple would interfere with the wrap function.

  • constructor
  • isPrototypeOf
  • length
  • name
  • propertyIsEnumerable
  • toLocaleString
  • toString

That shouldn't be too much of a problem, as they seem unlikely targets for stubbing.

Links

License

MIT: http://mrgnrdrck.mit-license.org

wrapple.jp

In no way affiliated with, but admiring wrapple.jp