package environment
The environment
package contains testable versions of all the standard ZIO
environment types through the TestClock, TestConsole,
TestSystem, and TestRandom modules. See the documentation on the
individual modules for more detail about using each of them.
If you are using ZIO Test and extending RunnableSpec
a
TestEnvironment
containing all of them will be automatically provided to
each of your tests. Otherwise, the easiest way to use the test implementations
in ZIO Test is by providing the TestEnvironment
to your program.
import zio.test.environment._
myProgram.provideLayer(testEnvironment)
Then all environmental effects, such as printing to the console or
generating random numbers, will be implemented by the TestEnvironment
and
will be fully testable. When you do need to access the "live" environment,
for example to print debugging information to the console, just use the
live
combinator along with the effect as your normally would.
If you are only interested in one of the test implementations for your
application, you can also access them a la carte through the make
method
on each module. Each test module requires some data on initialization.
Default data is included for each as DefaultData
.
import zio.test.environment._
myProgram.provideM(TestConsole.make(TestConsole.DefaultData))
Finally, you can create a Test
object that implements the test interface
directly using the makeTest
method. This can be useful when you want to
access some testing functionality without using the environment type.
import zio.test.environment._ for { testRandom <- TestRandom.makeTest(TestRandom.DefaultData) n <- testRandom.nextInt } yield n
This can also be useful when you are creating a more complex environment to provide the implementation for test services that you mix in.
- Alphabetic
- By Inheritance
- environment
- PlatformSpecific
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Type Members
- type Live = Has[Service]
- trait Restorable extends Serializable
- type TestClock = Has[Service]
- type TestConsole = Has[Service]
- type TestEnvironment = zio.ZEnv with Annotations with TestClock with TestConsole with Live with TestRandom with Sized with TestSystem
- Definition Classes
- PlatformSpecific
- type TestRandom = Has[Service]
- type TestSystem = Has[Service]
Value Members
- def live[E, A](zio: ZIO[zio.ZEnv, E, A]): ZIO[Live, E, A]
Provides an effect with the "real" environment as opposed to the test environment.
Provides an effect with the "real" environment as opposed to the test environment. This is useful for performing effects such as timing out tests, accessing the real time, or printing to the real console.
- val liveEnvironment: Layer[Nothing, zio.ZEnv]
- val testEnvironment: Layer[Nothing, TestEnvironment]
- def withLive[R, E, E1, A, B](zio: ZIO[R, E, A])(f: (IO[E, A]) => ZIO[zio.ZEnv, E1, B]): ZIO[R with Live, E1, B]
Transforms this effect with the specified function.
Transforms this effect with the specified function. The test environment will be provided to this effect, but the live environment will be provided to the transformation function. This can be useful for applying transformations to an effect that require access to the "real" environment while ensuring that the effect itself uses the test environment.
withLive(test)(_.timeout(duration))
- object Live
The
Live
trait provides access to the "live" environment from within the test environment for effects such as printing test results to the console or timing out tests where it is necessary to access the real environment.The
Live
trait provides access to the "live" environment from within the test environment for effects such as printing test results to the console or timing out tests where it is necessary to access the real environment.The easiest way to access the "live" environment is to use the
live
method with an effect that would otherwise access the test environment.import zio.clock import zio.test.environment._ val realTime = live(clock.nanoTime)
The
withLive
method can be used to apply a transformation to an effect with the live environment while ensuring that the effect itself still runs with the test environment, for example to time out a test. Both of these methods are re-exported in theenvironment
package for easy availability. - object TestClock extends Serializable
TestClock
makes it easy to deterministically and efficiently test effects involving the passage of time.TestClock
makes it easy to deterministically and efficiently test effects involving the passage of time.Instead of waiting for actual time to pass,
sleep
and methods implemented in terms of it schedule effects to take place at a given wall clock time. Users can adjust the wall clock time using theadjust
andsetTime
methods, and all effects scheduled to take place on or before that wall clock time will automically be run.For example, here is how we can test
ZIO#timeout
usingTestClock:
import zio.ZIO import zio.duration._ import zio.test.environment.TestClock for { fiber <- ZIO.sleep(5.minutes).timeout(1.minute).fork _ <- TestClock.adjust(1.minute) result <- fiber.join } yield result == None
Note how we forked the fiber that
sleep
was invoked on. Calls tosleep
and methods derived from it will semantically block until the wall clock time is set to on or after the time they are scheduled to run. If we didn't fork the fiber on which we called sleep we would never get to set the the wall clock time on the line below. Thus, a useful pattern when usingTestClock
is to fork the effect being tested, then adjust the wall clock time, and finally verify that the expected effects have been performed.Sleep and related combinators schedule events to occur at a specified duration in the future relative to the current fiber time (e.g. 10 seconds from the current fiber time). The fiber time is backed by a
FiberRef
and is incremented for the duration each fiber is sleeping. Child fibers inherit the fiber time of their parent so methods that rely on repeatedsleep
calls work as you would expect.For example, here is how we can test an effect that recurs with a fixed delay:
import zio.Queue import zio.duration._ import zio.test.environment.TestClock for { q <- Queue.unbounded[Unit] _ <- (q.offer(()).delay(60.minutes)).forever.fork a <- q.poll.map(_.isEmpty) _ <- TestClock.adjust(60.minutes) b <- q.take.as(true) c <- q.poll.map(_.isEmpty) _ <- TestClock.adjust(60.minutes) d <- q.take.as(true) e <- q.poll.map(_.isEmpty) } yield a && b && c && d && e
Here we verify that no effect is performed before the recurrence period, that an effect is performed after the recurrence period, and that the effect is performed exactly once. The key thing to note here is that after each recurrence the next recurrence is scheduled to occur at the appropriate time in the future, so when we adjust the wall clock time by 60 minutes exactly one value is placed in the queue, and when we adjust the wall clock time by another 60 minutes exactly one more value is placed in the queue.
- object TestConsole extends Serializable
TestConsole
provides a testable interface for programs interacting with the console by modeling input and output as reading from and writing to input and output buffers maintained byTestConsole
and backed by aRef
.TestConsole
provides a testable interface for programs interacting with the console by modeling input and output as reading from and writing to input and output buffers maintained byTestConsole
and backed by aRef
.All calls to
putStr
andputStrLn
using theTestConsole
will write the string to the output buffer and all calls togetStrLn
will take a string from the input buffer. To facilitate debugging, by default output will also be rendered to standard output. You can enable or disable this for a scope usingdebug
,silent
, or the corresponding test aspects.TestConsole
has several methods to access and manipulate the content of these buffers includingfeedLines
to feed strings to the input buffer that will then be returned by calls togetStrLn
,output
to get the content of the output buffer from calls toputStr
andputStrLn
, andclearInput
andclearOutput
to clear the respective buffers.Together, these functions make it easy to test programs interacting with the console.
import zio.console._ import zio.test.environment.TestConsole import zio.ZIO val sayHello = for { name <- getStrLn _ <- putStrLn("Hello, " + name + "!") } yield () for { _ <- TestConsole.feedLines("John", "Jane", "Sally") _ <- ZIO.collectAll(List.fill(3)(sayHello)) result <- TestConsole.output } yield result == Vector("Hello, John!\n", "Hello, Jane!\n", "Hello, Sally!\n")
- object TestEnvironment
- Definition Classes
- PlatformSpecific
- object TestRandom extends Serializable
TestRandom
allows for deterministically testing effects involving randomness.TestRandom
allows for deterministically testing effects involving randomness.TestRandom
operates in two modes. In the first mode,TestRandom
is a purely functional pseudo-random number generator. It will generate pseudo-random values just likescala.util.Random
except that no internal state is mutated. Instead, methods likenextInt
describe state transitions from one random state to another that are automatically composed together through methods likeflatMap
. The random seed can be set usingsetSeed
andTestRandom
is guaranteed to return the same sequence of values for any given seed. This is useful for deterministically generating a sequence of pseudo-random values and powers the property based testing functionality in ZIO Test.In the second mode,
TestRandom
maintains an internal buffer of values that can be "fed" with methods such asfeedInts
and then when random values of that type are generated they will first be taken from the buffer. This is useful for verifying that functions produce the expected output for a given sequence of "random" inputs.import zio.random._ import zio.test.environment.TestRandom for { _ <- TestRandom.feedInts(4, 5, 2) x <- random.nextInt(6) y <- random.nextInt(6) z <- random.nextInt(6) } yield x + y + z == 11
TestRandom
will automatically take values from the buffer if a value of the appropriate type is available and otherwise generate a pseudo-random value, so there is nothing you need to do to switch between the two modes. Just generate random values as you normally would to get pseudo-random values, or feed in values of your own to get those values back. You can also use methods likeclearInts
to clear the buffer of values of a given type so you can fill the buffer with new values or go back to pseudo-random number generation. - object TestSystem extends Serializable
TestSystem
supports deterministic testing of effects involving system properties.TestSystem
supports deterministic testing of effects involving system properties. Internally,TestSystem
maintains mappings of environment variables and system properties that can be set and accessed. No actual environment variables or system properties will be accessed or set as a result of these actions.import zio.system import zio.test.environment.TestSystem for { _ <- TestSystem.putProperty("java.vm.name", "VM") result <- system.property("java.vm.name") } yield result == Some("VM")