Adapt

TODO: Merge in expect.

The Adapt class (subject, expect) defines an assertion definition language used in Pickle, which provides methods that are easy to use and fast to declare as long as the tests has a clearly defined structure. That is, it is a “pickle”.

Tests can be described as series of premises, that must evaluate to a true state. The outcome of a test can be viewed as a sequence of statements that are conjoined together with an and. Because of the logical conjunction, the first falsy in the sequence will then imply that any further tests can be dismissed. This is the default case.

In some cases it is only necessary that one of a few tests has a true state. Because of the logical disjunction, the first truthy in the sequence will then imply that any further tests can be dismissed.

NOTE: It is not clear how the logical connectives should be set for a logical disjunction of assertions, and if a full description (statement, declaration) of the graph is necessary.

The Case class (describe, context, it) will put data in a bag subject, with last test case on top. This will then be available to expect for inspection.

NOTE: This method of cross-referencing Adapt instances could be dropped in favor of simply accessing the subject, leaving expect for other out-of-order tests.

Usage

Present call works like the following

subject( 'foo' ) -- call as part of test case setup
-- some processing
-- ⋮
-- more processing
expect( 'string' ):first():asType():toBeSame()

The cross-referencing makes the use very opaque, but as most of its use is hidden it does not matter too much.

NOTE: Corrected call would be like the following

subject( obj ) -- call as part of test case setup
-- some processing
-- ⋮
-- more processing
subject:first():asType():toBeSame( 'string' )

Methods

Adapt instances will typically store a set of objects for later retrieval and test on a call graph. Normally the overall outcome should be completely transparent, but the actual result from the method itself will not be available. It is hidden into the overall execution of the call graph.

To load a test instance onto the stack use the table call form, that is subject( ... ). This will store whatever provided on the stack for later retrieval. Those values can be further conditioned and processed with three types of operations; pick a value, transform the value, and evaluate a conditional on the value. The final value is then used for the final outcome of a single premise.

A call graph is used instead of direct execution due to two reasons; out-of-order creation and retrospective inspection.

Out-of-order creation allows parts of the call graph to be created without following any strict order, thus allowing more readable statements. Only when all necessary parts are registered, and a final condition called, then the value will be processed and the outcome returned.

Retrospective inspection allows processing the final outcome, and then inspecting parts of the overall graph. If we get a specific value, was some other value a correct or invalid type? This can make testing possible in some cases where we can't make hard assumptions about the input values. Most common use case is to invalidate an otherwise failing proposition.

Pick

This is delayed actions to chose one of several returned values. The delayed action will only return a single value.

Transform

This is delayed actions to somehow transform a value. The delayed action will return the same value, but somehow transformed.

Condition

This is delayed actions to compare the values. The delayed action will return a boolean value.

generated by LDoc 1.4.6