TestControl

cats.effect.testkit.TestControl
See theTestControl companion class
object TestControl

Attributes

Companion
class
Source
TestControl.scala
Graph
Supertypes
class Object
trait Matchable
class Any
Self type

Members list

Type members

Classlikes

final class NonTerminationException extends RuntimeException

Attributes

Source
TestControl.scala
Supertypes
class RuntimeException
class Exception
class Throwable
trait Serializable
class Object
trait Matchable
class Any
Show all

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.

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.

Attributes

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.

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.

Attributes

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