cp.spec.Scenario.md

docs » cp.spec.Scenario

---

A Definition which describes a specific scenario.

A Scenario is most typically created via the it function, like so:

local spec          = require "cp.spec"
local describe, it  = spec.describe, spec.it

local Rainbow       = require "my.rainbow"

return describe "a rainbow" {
    it "has seven colors"
    :doing(function()
        local rainbow = Rainbow()
        assert(#rainbow:colors() == 7, "the rainbow has seven colors")
    end)
}

Scenarios can be run asynchronously via the Run.This instance passed to the doing function. To indicate a scenario is asynchronous, call this:wait(), then call this:done(), to indicate it has completed. Any assert call which fails will result in the run failing, and stop at that point.

For example:

return describe "a rainbow" {
    it "has a pot of gold at the end"
    :doing(function(this)
        this:wait()
        local rainbow = Rainbow()
        rainbow:goToEnd(function(whatIsThere)
            assert(whatIsThere:isInstanceOf(PotOfGold))
            this:done()
        end)
    end)
}

Definitions can also be data-driven, via the where method:

return describe "a rainbow" {
    it "has ${color} at index ${index}"
    :doing(function(this)
        local rainbow = Rainbow()
        assert(rainbow[this.index] == this.color)
    end)
    :where {
        { "index",  "color"     },
        { 1,        "red"       },
        { 2,        "orange"    },
        { 3,        "yellow"    },
        { 4,        "blue"      },
        { 5,        "green"     },
        { 6,        "indigo"    },
        { 7,        "violet"    },
    },
}

This will do a run for each variation and interpolate the value into the run name for each.

Note: "where" parameters will not override built-in functions and fields in the this instance (such as "async" or "done") so ensure that you pick names that don't clash.

API Overview

• Constructors - API calls which return an object, typically one that offers API methods
• Scenario
• Methods - API calls which can only be made on an object returned by a constructor
• doing
• run
• where

API Documentation

Constructors

Scenario

Signature	cp.spec.Scenario(name[, testFn]) -> cp.spec.Scenario
Type	Constructor
Description	Creates a new Scenario with the specified name.
Parameters	name - The name of the scenario. testFn - (optional) The function which performs the test for in the scenario.
Returns	The new Scenario.
Notes	If the testFn is not provided here, it must be done via the doing method prior to running, an error will occur.

Methods

doing

Signature	cp.spec.Scenario:doing(actionFn) -> self
Type	Method
Description	Specifies the function for the definition.
Parameters	testFn - The function that will do the test.
Returns	The same Definition.

run

Signature	cp.spec.Scenario:run(...) -> cp.spec.Run
Type	Method
Description	Runs the scenario.
Parameters	... - The list of filters. The first one will be compared to this scenario to determine it should be run.

where

Signature	cp.spec.Scenario:where(data) -> cp.spec.Where
Type	Method
Description	Specifies a table of data that will be iterated through as multiple Runs, one row at a time.
Parameters	data - The data table.
Returns	The Where.