TestHelper
Per unit test class that provides control, logging and assertion functions.
Each unit test is given a TestHelper when it is run. This is val and so can be passed between methods and actors within the test without restriction.
The assertion functions check the relevant condition and mark the test as a failure if appropriate. The success or failure of the condition is reported back as a Bool which can be checked if a different code path is needed when that condition fails.
All assert functions take an optional message argument. This is simply a string that is printed as part of the error message when the condition fails. It is intended to aid identifying what failed.
class val TestHelper
Public fields
let env: Env val
The process environment.
This is useful for getting the root authority in order to access the filesystem (See files) or the network (See net) in your tests.
Public Functions
log
Log the given message.
The verbose parameter allows messages to be printed only when the --verbose command line option is used. For example, by default assert failures are logged, but passes are not. With --verbose both passes and fails are reported.
Logs are printed one test at a time to avoid interleaving log lines from concurrent tests.
fun box log( msg: String val, verbose: Bool val = false) : None val
Parameters
Returns
- None val
fail
Flag the test as having failed.
fun box fail( msg: String val = "Test failed") : None val
Parameters
- msg: String val = "Test failed"
Returns
- None val
assert_true
Assert that the given expression is true.
fun box assert_true( actual: Bool val, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
assert_false
Assert that the given expression is false.
fun box assert_false( actual: Bool val, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
assert_error
Assert that the given test function throws an error when run.
fun box assert_error( test: ITest box, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
assert_no_error
Assert that the gived test function does not throw an error when run.
fun box assert_no_error( test: ITest box, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
assert_is[A: A]
Assert that the 2 given expressions resolve to the same instance
fun box assert_is[A: A]( expect: A, actual: A, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
assert_eq[A: (Equatable[A] #read & Stringable #read)]
Assert that the 2 given expressions are equal.
fun box assert_eq[A: (Equatable[A] #read & Stringable #read)]( expect: A, actual: A, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
assert_isnt[A: A]
Assert that the 2 given expressions resolve to different instances.
fun box assert_isnt[A: A]( not_expect: A, actual: A, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
assert_ne[A: (Equatable[A] #read & Stringable #read)]
Assert that the 2 given expressions are not equal.
fun box assert_ne[A: (Equatable[A] #read & Stringable #read)]( not_expect: A, actual: A, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
assert_array_eq[A: (Equatable[A] #read & Stringable #read)]
Assert that the contents of the 2 given ReadSeqs are equal.
The type parameter of this function is the type parameter of the elements in both ReadSeqs. For instance, when comparing two Array[U8], you should call this method as follows:
fun apply(h: TestHelper) => let a: Array[U8] = [1; 2; 3] let b: Array[U8] = [1; 2; 3] h.assert_array_eq[U8](a, b)
fun box assert_array_eq[A: (Equatable[A] #read & Stringable #read)]( expect: ReadSeq[A] box, actual: ReadSeq[A] box, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
assert_array_eq_unordered[A: (Equatable[A] #read & Stringable #read)]
Assert that the contents of the 2 given ReadSeqs are equal ignoring order.
The type parameter of this function is the type parameter of the elements in both ReadSeqs. For instance, when comparing two Array[U8], you should call this method as follows:
fun apply(h: TestHelper) => let a: Array[U8] = [1; 2; 3] let b: Array[U8] = [1; 3; 2] h.assert_array_eq_unordered[U8](a, b)
fun box assert_array_eq_unordered[A: (Equatable[A] #read & Stringable #read)]( expect: ReadSeq[A] box, actual: ReadSeq[A] box, msg: String val = "", loc: SourceLoc val = __loc) : Bool val
Parameters
Returns
- Bool val
long_test
Indicate that this is a long running test that may continue after the test function exits. Once this function is called, complete() must be called to finish the test, unless a timeout occurs. The timeout is specified in nanseconds.
fun box long_test( timeout: U64 val) : None val
Parameters
- timeout: U64 val
Returns
- None val
complete
MUST be called by each long test to indicate the test has finished, unless a timeout occurs.
The "success" parameter specifies whether the test succeeded. However if any asserts fail the test will be considered a failure, regardless of the value of this parameter.
Once this is called tear_down() may be called at any time.
fun box complete( success: Bool val) : None val
Parameters
- success: Bool val
Returns
- None val
expect_action
Can be called in a long test to set up expectations for one or more actions that, when all completed, will complete the test.
This pattern is useful for cases where you have multiple things that need to happen to complete your test, but don't want to have to collect them all yourself into a single actor that calls the complete method.
The order of calls to expect_action don't matter - the actions may be completed in any other order to complete the test.
fun box expect_action( name: String val) : None val
Parameters
- name: String val
Returns
- None val
complete_action
MUST be called for each action expectation that was set up in a long test to fulfill the expectations. Any expectations that are still outstanding when the long test timeout runs out will be printed by name when it fails.
Completing all outstanding actions is enough to finish the test. There's no need to also call the complete method when the actions are finished.
Calling the complete method will finish the test immediately, without waiting for any outstanding actions to be completed.
fun box complete_action( name: String val) : None val
Parameters
- name: String val
Returns
- None val
fail_action
Call to fail an action, which will also cause the entire test to fail immediately, without waiting the rest of the outstanding actions.
The name of the failed action will be included in the failure output.
Usually the action name should be an expected action set up by a call to expect_action, but failing unexpected actions will also fail the test.
fun box fail_action( name: String val) : None val
Parameters
- name: String val
Returns
- None val
dispose_when_done
Pass a disposable actor to be disposed of when the test is complete. The actor will be disposed no matter whether the test succeeds or fails.
If the test is already tearing down, the actor will be disposed immediately.
fun box dispose_when_done( disposable: DisposableActor tag) : None val
Parameters
- disposable: DisposableActor tag
Returns
- None val
© 2016-2020, The Pony Developers
© 2014-2015, Causality Ltd.
Licensed under the BSD 2-Clause License.
https://stdlib.ponylang.io/ponytest-TestHelper