Given
Given is a lazy-evaluation system for use in your specs.
Variables are defined within an environment object and are lazily computed on demand. A variable can hold either a value, function or object. If the variable is a function it used for computing the value of the variable when it is accessed from the environment.
Variables are accessed from the environment as if they are plain JS properties. Under the hood, the properties are defined using Object.defineProperty with a 'get' accessor in order that their value can be computed on demand.
Installation
Add it to your package.json or npm install given
.
Usage
Javascript
Given = ; expect = ;
Coffee
Given = require '../build/given'expect = require 'expect.js' ddescribe "Given"-> given = undefined beforeEach -> given = Given @ it "can define a variable"-> given 'name''James Sadler' expect@nametoequal "James Sadler" it "can define a variable that is depends on another and is computed on demand"-> given 'name''James Sadler' given 'message'-> "Hello, !" expect@messagetoequal 'Hello, James Sadler!' it 'can define variables in bulk'-> given name: 'James Sadler' age: 36 expect@nametoequal 'James Sadler' expect@agetoequal 36 it 'provides a way to explicitly clear the environment'-> given 'name''James Sadler' givenclear expect@nametobe undefined it 'can define variable in terms of the existing value'-> given 'array'-> 1 given 'array'-> @arrayconcat 2 given 'array'-> @arrayconcat 3 expect@arraytoeql 123 it 'supports the definition of variables that depend on a variable that is not yet defined'-> given : -> @bar given : -> 'Bar' expect@footoequal 'Bar' it 'supports forward definitions'-> given : -> "James" given : -> " and " given : -> "Kellie" expect@messagetoequal 'James and Kellie' it 'memoizes variables when they are evaluated'-> count = 0 given : -> count += 1 'James' @name expectcounttoequal 1 @name expectcounttoequal 1 it 'uses memoized variables when variables are defined in terms of others'-> count = 0 given : -> count += 1 count given : -> @val1 expect@val1toequal 1 expect@val2toequal 1 it 'uses memoized variables when variables are defined in terms of their previous values'-> count1 = 0 given : -> count1 += 1 1 count2 = 0 given : -> count2 += 1 @val1 + 1 expect@val1toequal 2 expectcount1toequal 1 expectcount2toequal 1 it 'forgets the memoization for all variables when any variable is redefined'-> count = 0 given : -> count += 1 'James' expect@nametoequal 'James' expectcounttoequal 1 given : -> 36 expect@nametoequal 'James' expectcounttoequal 2 it 'exposes all defined properties as enumerable'-> env = given = Given env given : -> 'James' given : -> 36 given : -> 'programmer' expectJSONparse JSONstringify envtoeql name: 'James' age: 36 occupation: 'programmer' describe 'is well-behaved and'-> it 'does not allow redefinition of "given"'-> expect-> given 'given''anything'tothrowException expectemessagetoequal 'cannot redefine given' it 'gives a meaningful error when recursive definitions blow the stack'-> given : -> @b given : -> @a expect=> @atothrowException expectemessagetomatch /recursive definition of variable '' detected/ describe 'to avoid hard to track down bugs prevents the environment being referenced in a definition'-> it 'when the environment is not *this*'-> env = given = Given env given : -> 'foo' given : -> @foo # 'this' is not used to reference values - the top most Given # environment is used instead. given : -> envfoo expect=> envviaThisnottothrowException expect=> envviaEnvtothrowException expectemessagetoequal " Illegal attempt to use the Given environment object in the definition of 'viaEnv'; Use 'this' within value definitions. " it 'wnen the environment is *this*'-> given = Given @ given : -> 'foo' given : -> @foo # 'this' is bound to the *this* of the spec itself instead of the # environment under the control of Given. given : => @foo expect=> @viaThisnottothrowException expect=> @viaEnvtothrowException expectemessagetoequal " Illegal attempt to use the Given environment object in the definition of 'viaEnv'; Use 'this' within value definitions. "
Caveats
To set a variable with a value that is a function, nest it within another function (to avoid ambiguity with dynamically computing a value), like so:
env;
Running the specs
Run make spec
.
Install the wach
node module if you would like to have the specs run
automatically when the source or specs are modified.
npm install -g wach
make watch
Contributing
- Fork it ( https://github.com/freshtonic/given/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Licence
Copyright (c) 2014, given is developed and maintained by James Sadler, and is released under the open MIT Licence.