TestControl

Companion:
class
Source:
TestControl.scala
class Object
trait Matchable
class Any

Type members

Classlikes

final class NonTerminationException extends RuntimeException

Value members

Concrete methods

def execute[A](program: IO[A], config: IORuntimeConfig, seed: Option[String]): IO[TestControl[A]]

Executes a given IO under fully mocked runtime control. Produces a TestControl which can be used to manipulate the mocked runtime and retrieve the results. Note that the outer IO (and the IOs produced by the TestControl) do ''not'' evaluate under mocked runtime control and must be evaluated by some external harness, usually some test framework integration.

Executes a given IO under fully mocked runtime control. Produces a TestControl which can be used to manipulate the mocked runtime and retrieve the results. Note that the outer IO (and the IOs produced by the TestControl) do ''not'' evaluate under mocked runtime control and must be evaluated by some external harness, usually some test framework integration.

A simple example (returns an IO which must, itself, be run) using MUnit assertion syntax:

 val program = for {
   first <- IO.realTime   // IO.monotonic also works
   _ <- IO.println("it is currently " + first)

   _ <- IO.sleep(100.milis)
   second <- IO.realTime
   _ <- IO.println("we slept and now it is " + second)

   _ <- IO.sleep(1.hour).timeout(1.minute)
   third <- IO.realTime
   _ <- IO.println("we slept a second time and now it is " + third)
 } yield ()

 TestControl.execute(program) flatMap { control =>
   for {
     first <- control.results
     _ <- IO(assert(first == None))   // we haven't finished yet

     _ <- control.tick
     // at this point, the "it is currently ..." line will have printed

     next1 <- control.nextInterval
     _ <- IO(assert(next1 == 100.millis))

     _ <- control.advance(100.millis)
     // nothing has happened yet!
     _ <- control.tick
     // now the "we slept and now it is ..." line will have printed

     second <- control.results
     _ <- IO(assert(second == None))  // we're still not done yet

     next2 <- control.nextInterval
     _ <- IO(assert(next2 == 1.minute))   // we need to wait one minute for our next task, since we will hit the timeout

     _ <- control.advance(15.seconds)
     _ <- control.tick
     // nothing happens!

     next3 <- control.nextInterval
     _ <- IO(assert(next3 == 45.seconds))   // haven't gone far enough to hit the timeout

     _ <- control.advanceAndTick(45.seconds)
     // at this point, nothing will print because we hit the timeout exception!

     third <- control.results

     _ <- IO {
       assert(third.isDefined)
       assert(third.get.isError)   // an exception, not a value!
       assert(third.get.fold(false, _.isInstanceOf[TimeoutException], _ => false))
     }
   } yield ()
 }

The above will run to completion within milliseconds.

If your assertions are entirely intrinsic (within the program) and the test is such that time should advance in an automatic fashion, executeEmbed may be a more convenient option.

Source:
TestControl.scala
def executeEmbed[A](program: IO[A], config: IORuntimeConfig, seed: Option[String]): IO[A]

Executes an IO under fully mocked runtime control, returning the final results. This is very similar to calling unsafeRunSync on the program and wrapping it in an IO, except that the scheduler will use a mocked and quantized notion of time, all while executing on a singleton worker thread. This can cause some programs to deadlock which would otherwise complete normally, but it also allows programs which involve IO.sleep s of any length to complete almost instantly with correct semantics.

Executes an IO under fully mocked runtime control, returning the final results. This is very similar to calling unsafeRunSync on the program and wrapping it in an IO, except that the scheduler will use a mocked and quantized notion of time, all while executing on a singleton worker thread. This can cause some programs to deadlock which would otherwise complete normally, but it also allows programs which involve IO.sleep s of any length to complete almost instantly with correct semantics.

Note that any program which involves an IO.async that waits for some external thread (including IO.evalOn) will be detected as a deadlock and will result in the executeEmbed effect immediately producing a NonTerminationException.

Returns:

An IO which runs the given program under a mocked runtime, producing the result or an error if the program runs to completion. If the program is canceled, a scala.concurrent.CancellationException will be raised within the IO. If the program fails to terminate with either a result or an error, a NonTerminationException will be raised.

Source:
TestControl.scala