# Testing Words

## Stack Testing

Stack testing involves checking the stack pointer before and after the code being tested is executed, and testing for the change in the stack pointer as well as matching the values put on the stack by the code being tested against the values expected. By its very nature this code is applied a task-specific level but can be used in different tasks simultaneously. This code is not part of the prebuilt binaries, but rather is in `test/common/stack.fs` and may be used both compiled to flash and compiled to RAM.

### `forth`

The following words are in `forth`.

##### `stack-fail-hook`

`stack-fail-hook` specifies an xt to be executed, if set to a value other than 0, when a stack test fails. By default this is set to 0.

##### `x-stack-fail`
( -- )

`x-stack-fail` is an exception raised when `}t` detects a stack position mismatch relative to the stack pointer recorded by `t{` and the number of cells on the stack passed into it. The purpose of this exception is that the stack pointer is unknown, so the only way to recover from it is by raising an exception.

##### `t{`
( -- ) ( R: -- sp )

This word saves the current stack pointer on the return stack for it to be used later by `}t`.

##### `}t`
( x1 ... xn y1 ... yn u -- ) ( R: old-sp -- )

This word checks that the current stack position is two times *u* cells greater than the old stack position recorded on the return stack; if this is not the case the xt stored in `stack-fail-hook` is executed, if it is not 0, and then `x-stack-fail` is raised. If this is the case each value *xi* is matched against its corresponding value *yi*, if any one of these does not match, then the xt stored in `stack-fail-hook` is executed if it is not 0.

## Emit Capture Testing

Emit capture testing involves installing a hook into `emit` transparently, and using this to capture and test each byte emitted against specified rules without interfering with the operation of the system. This is done in a transparently multitasking-friendly manner, and can be used to test behavior spread across multiple tasks without any extra work being needed on the programmer's part. This code is not part of the prebuilt binaries, but rather is in `test/common/capture.fs` and may be used both compiled to flash and compiled to RAM.

### `forth`

The following words are in `forth`.

##### `capture-fail-hook`

`capture-fail-hook` specifies an xt to be executed, if set to a value other than 0, when an emit capture test fails. By default this is set to 0.

##### `enable-capture`
( -- )

This word enables emit capture testing.

##### `disable-capture`
( -- )

This word disables emit capture testing.

##### `no-capture`
( xt -- )

This word temporarily disables emit capture testing, and then executes *xt*, afterwards enabling emit capture testing if it had been previously enabled.

##### `x-capture-full`
( -- )

This word is the exception raised when the emit capture test buffer is full and the user attempts to add another emit capture test.

##### `clear-capture`
( -- )

This word clears the emit capture test buffer, effectively disabling emit capture test until another emit capture test is added.

##### `add-match-capture`
( b-addr bytes xt -- )

This word adds a matching emit capture test, which fails unless each character in the specified string is matched in order. *xt* is an xt which is executed when either the matching emit capture test fails, where then it is passed `false`, or when the matching emit capture test is successfully completed, where then it is passed `true`, unless it is set to 0, where then it is ignored.

##### `add-skip-capture`
( b-addr bytes limit xt -- )

This word adds a skipping emit capture test, which fails if more than *limit* characters are emitted without the specified string having been matched in full. *xt* is an xt which is executed when either the skipping emit capture test fails, where then it is passed `false`, or when the skipping emit capture test is successfully completed, where then it is passed `true`, unless it is set to 0, where then it is ignored.

##### `add-ignore-capture`
( b-addr bytes limit xt -- )

This word adds an ignoring emit capture test, which fails if more than *limit* characters are emitted without having matched the specified string fully 0 or more times. *xt* is an xt which is executed when either the ignoring emit capture test fails, where then it is passed `false`, or when the ignoring emit capture test is successfully completed, where then it is passed `true`, unless it is set to 0, where then it is ignored.