# cp.spec.Run.This
A token passed to test functions to allow them to indicate if a test [run](cp.spec.Run.md)
will complete asynchronously.
---
## API Overview
**Constants** - _Useful values which cannot be changed_
* [state](#state)
**Functions** - _API calls offered directly by the extension_
* [defaultTimeout](#defaulttimeout)
**Constructors** - _API calls which return an object, typically one that offers API methods_
* [This](#this)
**Methods** - _API calls which can only be made on an object returned by a constructor_
* [abort](#abort)
* [cleanup](#cleanup)
* [done](#done)
* [expectAbort](#expectabort)
* [expectFail](#expectfail)
* [fail](#fail)
* [isActive](#isactive)
* [isDone](#isdone)
* [isWaiting](#iswaiting)
* [log](#log)
* [prepare](#prepare)
* [run](#run)
* [toObserver](#toobserver)
* [wait](#wait)
---
## API Documentation
#### Constants
### [state](#state)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This.state` |
| **Type** | Constant |
| **Description** | A collection of states that a `Run.This` can be in. |
| **Notes** | - States include:
- running - The Run is currently running and will terminate at the end of the function (synchrnonous).
- waiting - The Run is waiting, and will terminate when [done()](#done) is called. (asynchronous).
- done - The Run is done.
|
| **Source** | [src/extensions/cp/spec/Run.lua line 31](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L31) |
---
#### Functions
### [defaultTimeout](#defaulttimeout)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This.defaultTimeout([timeout]) -> number` |
| **Type** | Function |
| **Description** | Gets and/or sets the default timeout for asynchronous tests. Defaults to 60 seconds. |
| **Parameters** | - timeout - (optional) the new timeout, in seconds.
|
| **Returns** | - The current default timeout, in seconds.
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 48](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L48) |
---
#### Constructors
### [This](#this)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This(run, actionFn, index) -> cp.spec.Run.This` |
| **Type** | Constructor |
| **Description** | Creates a new `Run.This` instance for a [Run](cp.spec.Run.md). |
| **Parameters** | - run - The [Run](cp.spec.Run.md).
- actionFn - The action function to execute.
- index - The index of the action in the current phase.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 64](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L64) |
---
#### Methods
### [abort](#abort)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:abort([message]) -> boolean` |
| **Type** | Method |
| **Description** | Indicates the stage has aborted. |
| **Parameters** | - message - The optional message to output.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 403](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L403) |
---
### [cleanup](#cleanup)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:cleanup()` |
| **Type** | Method |
| **Description** | Cleans up This after a step. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 489](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L489) |
---
### [done](#done)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:done()` |
| **Type** | Method |
| **Description** | Indicates that the test is completed. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 346](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L346) |
---
### [expectAbort](#expectabort)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:expectAbort([messagePattern]) -> Run.This` |
| **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.This` 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 207](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L207) |
---
### [expectFail](#expectfail)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:expectFail([messagePattern]) -> Run.This` |
| **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.This` 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 120](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L120) |
---
### [fail](#fail)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:fail([message]) -> boolean` |
| **Type** | Method |
| **Description** | Indicates the run has failed. |
| **Parameters** | - message - The optional message to output.
|
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 427](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L427) |
---
### [isActive](#isactive)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:isActive() -> boolean` |
| **Type** | Method |
| **Description** | Checks if the this is in an active state - either `running` or `waiting`. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 295](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L295) |
---
### [isDone](#isdone)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:isDone() -> boolean` |
| **Type** | Method |
| **Description** | Returns `true` if this is done. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 390](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L390) |
---
### [isWaiting](#iswaiting)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:isWaiting() -> boolean` |
| **Type** | Method |
| **Description** | Checks if the [Run](cp.spec.Run.md) is waiting for this execution to complete via the [done](cp.spec.Run.This.md#done) method. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 333](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L333) |
---
### [log](#log)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:log(message[, ...])` |
| **Type** | Method |
| **Description** | When the current [Run](cp.spec.Run.md) is in [debug](#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** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 713](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L713) |
---
### [prepare](#prepare)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:prepare()` |
| **Type** | Method |
| **Description** | Prepares this to run. |
| **Parameters** | |
| **Returns** | |
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 477](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L477) |
---
### [run](#run)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:run() -> cp.spec.Run` |
| **Type** | Method |
| **Description** | Returns the current [Run](cp.spec.Run.md) |
| **Parameters** | |
| **Returns** | - Returns the current [Run](cp.spec.Run.md)
|
| **Notes** | None |
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 86](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L86) |
---
### [toObserver](#toobserver)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:toObserver([onNext[, onError[, onCompleted]]) -> cp.rx.Observer` |
| **Type** | Method |
| **Description** | Creates an [Observer](cp.rx.Observer.md). |
| **Parameters** | - onNext - The `next` handler.
- onError - The `error` handler.
- onCompleted - The `completed` handler.
|
| **Returns** | |
| **Notes** | - If the `onNext`/`onError`/`onCompleted` functions are
- not provided, then it will provide defaults. `onNext` will be logged, `onError` will throw an error,
- and `onCompleted` will trigger [done](#done).
|
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 272](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L272) |
---
### [wait](#wait)
| | |
| --------------------------------------------|-------------------------------------------------------------------------------------|
| **Signature** | `cp.spec.Run.This:wait([timeout]) -> none` |
| **Type** | Method |
| **Description** | Indicates that the test is continuing asynchronously, and will be completed by calling [done](#done). |
| **Parameters** | - timeout - (optional) The number of seconds to wait before timing out.
|
| **Returns** | |
| **Notes** | - If not provided, [Run.This.defaultTimeout()](cp.spec.Run.This.md#defaultTimeout) is used.
|
| **Examples** | None |
| **Source** | [src/extensions/cp/spec/Run.lua line 308](https://github.com/CommandPost/CommandPost/blob/develop/src/extensions/cp/spec/Run.lua#L308) |
---
---