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

Constructors

_create

Create a new TestHelper.

new val _create(
  runner: _TestRunner tag,
  env': Env val)
: TestHelper val^

Parameters

Returns


Public fields

  • let env: Env val

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 = seq)
: None val

Parameters

Returns


fail

Flag the test as having failed.

fun box fail(
  msg: String val = seq)
: None val

Parameters

Returns


assert_true

Assert that the given expression is true.

fun box assert_true(
  actual: Bool val,
  msg: String val = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


assert_false

Assert that the given expression is false.

fun box assert_false(
  actual: Bool val,
  msg: String val = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


assert_error

Assert that the given test function throws an error when run.

fun box assert_error(
  test: ITest box,
  msg: String val = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


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 = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


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 = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


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 = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


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 = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


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 = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


assert_array_eq[A: (Equatable[A] #read & Stringable #read)]

Assert that the contents of the 2 given ReadSeqs are equal.

fun box assert_array_eq[A: (Equatable[A] #read & Stringable #read)](
  expect: ReadSeq[A] box,
  actual: ReadSeq[A] box,
  msg: String val = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


assert_array_eq_unordered[A: (Equatable[A] #read & Stringable #read)]

Assert that the contents of the 2 given ReadSeqs are equal ignoring order.

fun box assert_array_eq_unordered[A: (Equatable[A] #read & Stringable #read)](
  expect: ReadSeq[A] box,
  actual: ReadSeq[A] box,
  msg: String val = seq,
  loc: SourceLoc val = seq)
: Bool val

Parameters

Returns


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


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

Returns


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

Returns


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

Returns


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

Returns


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

Returns


Private Functions

_check_is[A: A]

Check that the 2 given expressions resolve to the same instance

fun box _check_is[A: A](
  check: String val,
  expect: A,
  actual: A,
  msg: String val,
  loc: SourceLoc val)
: Bool val

Parameters

Returns


_check_eq[A: (Equatable[A] #read & Stringable)]

Check that the 2 given expressions are equal.

fun box _check_eq[A: (Equatable[A] #read & Stringable)](
  check: String val,
  expect: A,
  actual: A,
  msg: String val,
  loc: SourceLoc val)
: Bool val

Parameters

Returns


_check_isnt[A: A]

Check that the 2 given expressions resolve to different instances.

fun box _check_isnt[A: A](
  check: String val,
  not_expect: A,
  actual: A,
  msg: String val,
  loc: SourceLoc val)
: Bool val

Parameters

Returns


_check_ne[A: (Equatable[A] #read & Stringable)]

Check that the 2 given expressions are not equal.

fun box _check_ne[A: (Equatable[A] #read & Stringable)](
  check: String val,
  not_expect: A,
  actual: A,
  msg: String val,
  loc: SourceLoc val)
: Bool val

Parameters

Returns


_format_loc

fun box _format_loc(
  loc: SourceLoc val)
: String val

Parameters

Returns


_print_array[A: Stringable #read]

Generate a printable string of the contents of the given readseq to use in error messages.

fun box _print_array[A: Stringable #read](
  array: ReadSeq[A] box)
: String val

Parameters

Returns