# cp.spec.Run

An individual run of a test Definition or Specification.

# Submodules

cp.spec.Run.This

# API Overview

Constructors - API calls which return an object, typically one that offers API methods

Fields - Variables which can only be accessed from an object returned by a constructor

phase
report
result
shared
source

Methods - API calls which can only be made on an object returned by a constructor

debug
expectAbort
expectFail
isDebugging
isExpectingAbort
isExpectingFail
log
onBefore
onBfter
onRunning
parent
verbose

# API Documentation

# Constructors

# Run


Signature	`cp.spec.Run(name, source) -> cp.spec.Run`
Type	Constructor
Description	Creates a new test run.
Parameters	name - The name of the run. source - The object (typically a Definition) that initiated the run.
Returns	cp.spec.Run
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 573

# Fields

# phase


Signature	`cp.spec.Run.phase <cp.spec.Run.phase>`
Type	Field
Description	The current phase of the run.
Notes	None
Source	src/extensions/cp/spec/Run.lua line 612

# report


Signature	`cp.spec.Run.report <cp.spec.Report>`
Type	Field
Description	The reports of the run.
Notes	None
Source	src/extensions/cp/spec/Run.lua line 585

# result


Signature	`cp.spec.Run.result <cp.spec.Run.result>`
Type	Field
Description	The current result. Defaults to `Run.result.passing`.
Notes	None
Source	src/extensions/cp/spec/Run.lua line 617

# shared


Signature	`cp.spec.Run.shared <table>`
Type	Field
Description	The set of data shared by all phases of the Run. Data from parent Runs will also be available.
Notes	None
Source	src/extensions/cp/spec/Run.lua line 600

# source


Signature	`cp.spec.Run.source`
Type	Field
Description	The object that initiated the run. Typically a Definition.
Notes	None
Source	src/extensions/cp/spec/Run.lua line 593

# Methods

# debug


Signature	`cp.spec.Run:debug() -> cp.spec.Run`
Type	Method
Description	Enables debugging on this `Run`. Any calls to [#log] will be output to the console.
Parameters	None
Returns	The same `Run` instance.
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 670

# expectAbort


Signature	`cp.spec.Run:expectAbort([messagePattern]) -> Run`
Type	Method
Description	Indicates that this spec is expecting an abort/`error` to occur.
Parameters	messagePattern - The pattern to check the fail message against. If not provided, any message will match.
Returns	The same `Run` instance.
Notes	When this is expected, it doesn't log the problem as a 'fail'. In fact, if the it doesn't occur at some point during the run, it will raise a failure at the end of the run. The `messagePattern` can be used to ensure it's the fail you expect. This should be called before the actual abort/`error` would occur.
Examples	None
Source	src/extensions/cp/spec/Run.lua line 186

# expectFail


Signature	`cp.spec.Run:expectFail([messagePattern]) -> Run`
Type	Method
Description	Indicates that this spec is expecting an assert/fail to occur.
Parameters	messagePattern - The pattern to check the fail message against. If not provided, any message will match.
Returns	The same `Run` instance.
Notes	When this is expected, it doesn't log the problem as a 'fail'. In fact, if the fail doesn't occur, it will raise a failure at the end of the run. The `messagePattern` can be used to ensure it's the fail you expect. This should be called before the actual assert/fail would occur.
Examples	None
Source	src/extensions/cp/spec/Run.lua line 99

# isDebugging


Signature	`cp.spec.Run:isDebugging() -> boolean`
Type	Method
Description	Checks if `debug` has been enabled on this or any parent `Run`.
Parameters	None
Returns	A boolean
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 684

# isExpectingAbort


Signature	`cp.spec.Run:isExpectingAbort() -> boolean, string or nil`
Type	Method
Description	Checks if the run is expecting a abort/error to occur. If so, it will return the expected message pattern as the second value, if specified.
Parameters	None
Returns	boolean - `true`, if a fail is expected. string - the message pattern, if specified.
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 226

# isExpectingFail


Signature	`cp.spec.Run:isExpectingFail() -> boolean, string or nil`
Type	Method
Description	Checks if the run is expecting a fail to occur. If so, it will return the expected message pattern, if specified.
Parameters	None
Returns	boolean - `true`, if a fail is expected. string - the message pattern, if specified.
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 139

# log


Signature	`cp.spec.Run:log(message[, ...])`
Type	Method
Description	When the current Run is in debug mode, output the message to the console.
Parameters	message - the text message to output. ... - optional parameters, to be injected into the message, ala `string.format`.
Returns	None
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 697

# onBefore


Signature	`cp.spec.Run:onBefore(actionFn) -> self`
Type	Method
Description	Adds a callback function to run prior to executing the actual test.
Parameters	actionFn - The function to run, passed this `Run.This` as the first parameter.
Returns	self
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 885

# onBfter


Signature	`cp.spec.Run:onBfter(actionFn) -> self`
Type	Method
Description	Adds a callback function to run after to executing the actual test, pass or fail.
Parameters	actionFn - The function to run, passed this `Run` as the first parameter.
Returns	self
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 911

# onRunning


Signature	`cp.spec.Run:onRunning(actionFn) -> self`
Type	Method
Description	Adds a callback function to run during the test.
Parameters	runningFn - The function to run, passed Run.This as the first parameter.
Returns	self
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 898

# parent


Signature	`cp.spec.Run:parent([parent]) -> cp.spec.Run`
Type	Method
Description	Gets and/or sets the parent `Run` for this run.
Parameters	parent - (optional) If set, will set the parent `Run`.
Returns	The current parent `Run`.
Notes	If a `parent` is provided and there is already another Run set as a parent, an error is thrown.
Examples	None
Source	src/extensions/cp/spec/Run.lua line 838

# verbose


Signature	`cp.spec.Run:verbose([isVerbose]) -> boolean \| self`
Type	Method
Description	Either sets the `verbose` value and returns itself for further chaining, or returns the current verbose status.
Parameters	isVerbose - (optional) if `true` or `false` will update the verbose status and return this `Run`.
Returns	The current `verbose` status, or this `Run` if `isVerbose` is provided.
Notes	None
Examples	None
Source	src/extensions/cp/spec/Run.lua line 862