gwt

• Given, when, then

Behaviour driven development for nodejs.

** Declaring steps, building a test, and running the test

*** Steps declaration

The available dictionary of steps has to be created before the order of execution of these steps is declared:

#+BEGIN_SRC coffee assert = require 'assert' gwt = require 'gwt' steps = gwt.steps GIVEN: 'an elevator with open doors and ${n} buttons': ({n}) -> @buttons = new Array(n) @lights = new Array(n) WHEN: 'button ${i} is pressed': ({i}) -> @button[i].press() THEN: 'the button light ${i} goes on': -> assert @lights[i].pressed #+END_SRC

See how this is bound to a context object that is passed between each given/when/then step. Store shared data against this.

NOTE: context is a new object in each step, with each key/value pair copied across to the new context, which is provided to the subsequent step. (See below)

*** Building a test

The order of execution is declared using the dictionary of steps. Steps can be used multiple times and in any order.

${...} strings are placeholders for values passed into steps. They are used to generate descriptions for it blocks.

#+BEGIN_SRC coffee myTest = steps .given 'elevator with open doors and ${n} buttons', {n: 10} .when 'button ${i} is pressed', {i: 4} .then 'the button light ${i} goes on', {i: 4} #+END_SRC

*** Running a test directly

**** Using a callback

#+BEGIN_SRC coffee myTest.run (err) -> ... #+END_SRC

**** Returning a promise

#+BEGIN_SRC coffee myTest.run() .then -> ... .fail (err) -> ... #+END_SRC

*** Running a test using mocha #+BEGIN_SRC coffee

done() registers with it

myTest.done() #+END_SRC

*** Override it

#+BEGIN_SRC coffee

done() registers with it

myTest.done(it: (description, testFn) -> ...) #+END_SRC

** Context

Each step has access to a context object, via this, which is copied from step to step.

CAVEAT: Each step has its own context object, with values from previous contexts copied across. This creates unexpected behaviour when trying to set values inside the context from inside a closure.

If you create a function within a step, and call it later, its lexical scope points to an old context. You can retrieve the latest context through the function getContext held within each context object.

*** Normal use of context, without lexical closures:

#+BEGIN_SRC coffee steps = gwt.steps GIVEN: 'a given': -> @bar = 'x'

WHEN: 'an action is taken': ->
  assert.equal @bar, 'x', 'Set in the wrong context' # -> PASS

steps .given 'a given' .when 'an action is taken' .run (err) -> ... #+END_SRC

*** Writing to a previous context object does not carry over to the rest:

#+BEGIN_SRC coffee steps = gwt.steps GIVEN: 'a given': -> context = this @setBar = -> context.bar = 'x'

WHEN: 'an action is taken': ->
  @setBar()
  assert.equal @bar, 'x', 'Set in the wrong context' # -> ERROR

steps .given 'a given' .when 'an action is taken' .run (err) -> ... #+END_SRC

*** Using getContext from within closures to retrieve the current context

To get this to work, use getContext, which returns the current context.

#+BEGIN_SRC coffee steps = gwt.steps GIVEN: 'a given': -> context = this @setBar = -> context.getContext().bar = 'x'

WHEN: 'an action is taken': ->
  @setBar()
  assert.equal @bar, 'x', 'Set in the wrong context' # -> PASS

steps .given 'a given' .when 'an action is taken' .run (err) -> ... #+END_SRC ** Asynchronous steps

*** Steps can return promises:

If the return value of a step is a promise, it will be used to chain onto the following steps.

#+BEGIN_SRC coffee Q = require 'q' steps = gwt.steps GIVEN: 'a precondition': -> deferred = Q.defer() setTimeout (-> deferred.resolve()), 1000 return deferred.promise

steps.run() #+END_SRC

*** Steps can use callbacks:

If the return value of a step is a function, it is assumed to be an asynchronous function and called with a callback which will resume execution of following steps when it is called.

#+BEGIN_SRC coffee steps = gwt.steps GIVEN: 'a precondition': -> (cb) -> setTimeout (-> cb()), 1000

steps.run() #+END_SRC ** Results can be retrieved from and passed back into steps

gwt.result() produces a placeholder that carries information via the context across steps, but provides us with an external reference.

*** Single results can be returned from and passed into steps

#+BEGIN_SRC coffee baz = gwt.result()

steps = gwt.steps WHEN: 'baz is created': -> return baz: 'xyz'

THEN: 'baz can be used': ({baz}) ->
  assert.deepEqual baz, baz: 'xyz'

steps .when('baz is created').resultTo(baz) .then('baz can be used', {baz}) .run (err) -> #+END_SRC

*** Multiple results can be passed into steps

#+BEGIN_SRC coffee baz = gwt.result() foo = gwt.result()

steps = gwt.steps WHEN: 'baz is created': -> return 'xyz'

  'foo is created': -> (cb) ->
    cb null, 'foo'

THEN: 'results can be used': ({baz, foo}) ->
  assert.equal baz, 'xyz'
  assert.equal foo, 'foo'

steps .when('baz is created').resultTo(baz) .then('results can be used', {baz, foo}) .run (err) -> ... #+END_SRC

*** Multiple results can be returned from steps

#+BEGIN_SRC coffee baz = gwt.result() foo = gwt.result()

steps = gwt.steps WHEN: 'foo and baz are created': -> return foo: 'foo', baz: 'xyz'

THEN: 'results can be used': ({baz, foo}) ->
  assert.equal baz, 'xyz'
  assert.equal foo, 'foo'

steps .when('foo and baz are created').resultTo({baz, foo}) .then('results can be used', {baz, foo}) .run (err) -> ... #+END_SRC

*** Results can be permanently overriden with set

If you call result.set with a value, any time it is passed to a step, it will be substituted with the given value.

You can call set inside or outside a step.

#+BEGIN_SRC coffee value = gwt.result() value.set 'xyz'

steps = gwt.steps THEN: 'result can be used': ({value}) -> assert.equal baz, 'xyz'

steps .then('result can be used', {value}) .run (err) -> ... #+END_SRC

*** Use tap() instead of result.set

Using tap() provides a less permanent way of setting a result placeholder value.

#+BEGIN_SRC coffee baz = gwt.result()

steps = gwt.steps THEN: 'baz has been set': ({baz}) -> assert.equal baz, 'xyz'

steps .tap(({baz} -> return 'xyz'), {baz}) .then 'baz has been set', {baz} .run (err) -> ... #+END_SRC

** Steps can be combined from multiple declarations using gwt.combine(...)

Calls to gwt.steps(...).given().when().then() produce a runner, which can be combined with other runners using gwt.combine(runner1, runner2, ...) to produce another runner, so that any level of nesting is possible.

NOTE: Context does not get copied between combined runners. However, result placeholders do carry values across combined runners.

#+BEGIN_SRC coffee steps1 = gwt.steps GIVEN: 'one': -> THEN: 'two': ->

steps2 = gwt.steps GIVEN: 'three': -> WHEN: 'four': -> THEN: 'five': ->

gwt.combine( steps1 .given 'one' .then 'two'

steps2
  .given 'three'
  .when 'four'
  .then 'five'

).run (err) -> ...

#+END_SRC

** Insert a custom function call without a step declaration (debugging)

You can access context and result values by providing a function instead of a description to the steps.tap() function

#+BEGIN_SRC coffee baz = gwt.result()

steps = gwt.steps WHEN: 'baz is created': -> return 'xyz'

steps .when('baz is created').resultTo(baz) .tap(({baz} -> console.log baz), {baz}) .run (err) -> ... #+END_SRC