This Jasmine extension is intended for browser code.
It runs between each spec and verifies that the global scope (window
object) was not changed by comparing its state
before and after the spec, detecting additions, modifications and deletions of window
properties.
Static code analysis catches a lot of accidental globals, but if the assignment happens indirectly, you'd have to run the code to find what's wrong. This is what jasmine-scope-check does.
jasmine-scope-check is for you if your code runs in a context out of your control. For example:
- Your app is embedded in a third party site.
- Other software uses your library.
- You just want to write damn good code.
Install the scope check before running any specs:
new JasmineScopeCheck({
globalObject: window
}).install(beforeEach, afterEach);
Used like this, a default white list is used that fits a typical browser-Jasmine environment.
See the demo
directory for a real-world example.
The following properties can be passed to the JasmineScopeCheck
constructor:
-
globalObject
(default =window
): The object to check for changes. -
expect
(default =globalObject.expect
): Jasmine'sexpect
function. -
whiteList
(default =[]
): An array of strings and/or regular expressions that specify property paths that may change without causing broken expectations. A property path consists of hierarchical property names from top to bottom, separated by dots. -
maxRecursionDepth
(default =4
): Properties that are this number of steps removed fromglobalObject
are no longer checked for changes, which is necessary for performance. -
useDefaultWhiteList
(default =true
): By setting this tofalse
, onlywhiteList
is used for ignoring properties that may be changed legitimately. Otherwise, the default white list is used in conjunction withwhiteList
.
In an environment where mechanisms such as Jasmine 2's global beforeEach()
and afterEach()
are not available, the
scope check can be invoked manually:
var myScope = {};
var scopeCheck = new JasmineScopeCheck({
globalObject = myScope
});
// Change things in myScope.
scopeCheck.compareGlobalSnapshotWithReality();
// Changes are tracked in: scopeCheck.addedProperties, scopeCheck.changedProperties, scopeCheck.removedProperties.
// Before doing some more changes that should be tracked independently, reset the state:
scopeCheck.reset();
-
dist/jasmine-scope-check.js
if you're not afraid of library conflicts (see TODO below). -
dist/jasmine-scope-check.min.js
if for whatever reason your test helpers need to be smaller. -
jasmine-scope-check.js
if you bring the dependencies (lodash, deep-diff) yourself.
- Currently, properties belonging to functions are not checked for changes due to an upstream issue.
- Dependencies are currently exposed in
dist/*.js
, which may lead to conflicts with other versions of lodash and deep-diff. - The default white-list is rather specific and could do with some enhancements.
# Clone the repo.
git clone git@github.com:findologic/jasmine-scope-check.git
# Install dependencies from NPM.
npm install
# Make sure that the gulp command is installed globally.
npm install -g gulp
# Run builds and tests to check that everything works.
gulp
# (optional) Build documentation.
gulp docs
- Additions, changes and removal of properties are tracked.
-
install()
method to wrap around all specs for comprehensive scope check coverage.
- The author and contributors of flitbit/diff take the pain out of recursive object comparison.
- FINDOLOGIC dedicated manpower to create and publish this initially internal tool.
(The MIT License)
Copyright (c) 2016 FINDOLOGIC GmbH
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.