or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assertions.mdcore-dsl.mdindex.mdmock-testing.mdproperty-testing.mdspecifications.mdtest-aspects.mdtest-environment.md
tile.json

tessl/maven-dev-zio--zio-test_2-12

ZIO Test is a featherweight testing library for effectful programs with deterministic testing capabilities, property-based testing, assertion combinators, and composable test environments.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/dev.zio/zio-test_2.12@1.0.x

To install, run

npx @tessl/cli install tessl/maven-dev-zio--zio-test_2-12@1.0.0

index.mddocs/

ZIO Test

ZIO Test is a featherweight testing library for effectful programs. Built on ZIO's powerful effect system, it provides tools for testing concurrent, asynchronous, and resource-safe programs with deterministic testing capabilities, property-based testing, assertion combinators, and test environments that can be easily composed and managed.

Package Information

  • Package Name: zio-test
  • Package Type: maven
  • Language: Scala
  • Installation: libraryDependencies += "dev.zio" %% "zio-test" % "1.0.18"

Core Imports

import zio.test._
import zio.test.Assertion._
import zio.test.environment._

For specific modules:

import zio.test.{DefaultRunnableSpec, Gen, TestAspect}
import zio.test.mock.Mock
import zio.test.laws.ZLaws

Basic Usage

import zio.test._
import zio.test.Assertion._
import zio.test.environment.TestEnvironment

object MyTest extends DefaultRunnableSpec {
  def spec = suite("my suite")(
    test("basic assertion") {
      assert(42)(equalTo(42))
    },
    testM("effectful test") {
      for {
        result <- ZIO.effectTotal(1 + 1)
      } yield assert(result)(equalTo(2))
    },
    test("property-based test") {
      check(Gen.int(1, 100)) { n =>
        assert(n * 2)(isGreaterThan(n))
      }
    }
  )
}

Architecture

ZIO Test is built around several key components:

  • Core DSL: Functions for creating tests (test, testM) and organizing them into suites (suite)
  • Assertion System: Rich set of built-in assertions with composition operators
  • Property-Based Testing: Generators (Gen) for creating test data and property verification functions
  • Test Environment: Testable versions of ZIO services (TestClock, TestConsole, TestRandom, TestSystem)
  • Test Aspects: Cross-cutting concerns like timeouts, retries, and conditional execution
  • Mock Framework: Service mocking with expectation-based testing
  • Spec Framework: Base classes for runnable test specifications

Capabilities

Core Testing DSL

Essential functions for creating and organizing tests with ZIO's effect system integration.

def test(label: String)(assertion: => TestResult): ZSpec[Any, Nothing]
def testM[R, E](label: String)(assertion: => ZIO[R, E, TestResult]): ZSpec[R, E]
def suite[R, E, T](label: String)(specs: Spec[R, E, T]*): Spec[R, E, T]

type ZTest[-R, +E] = ZIO[R, TestFailure[E], TestSuccess]
type ZSpec[-R, +E] = Spec[R, TestFailure[E], TestSuccess]
type TestResult = BoolAlgebra[AssertionResult]

Core Testing DSL

Assertion System

Comprehensive assertion library with 60+ built-in assertions and logical composition operators.

def assert[A](value: => A)(assertion: Assertion[A]): TestResult
def assertM[R, E, A](effect: ZIO[R, E, A])(assertion: AssertionM[A]): ZIO[R, E, TestResult]

// Built-in assertions
def equalTo[A](expected: A): Assertion[A]
def isGreaterThan[A](reference: A): Assertion[A]
def contains[A](element: A): Assertion[Iterable[A]]
def startsWith(prefix: String): Assertion[String]
val isTrue: Assertion[Boolean]
val isEmpty: Assertion[Iterable[Any]]

Assertions

Property-Based Testing

Sophisticated generator system for creating test data and verifying properties across input ranges.

def check[R <: TestConfig, A](rv: Gen[R, A])(test: A => TestResult): URIO[R, TestResult]
def checkM[R <: TestConfig, R1 <: R, E, A](rv: Gen[R, A])(test: A => ZIO[R1, E, TestResult]): ZIO[R1, E, TestResult]

final case class Gen[-R, +A](sample: ZStream[R, Nothing, Sample[R, A]])

// Built-in generators
val anyInt: Gen[Any, Int]
val anyString: Gen[Any, String]
def listOf[R, A](gen: Gen[R, A]): Gen[R with Sized, List[A]]
def oneOf[R, A](as: A*): Gen[R, A]

Property-Based Testing

Test Environment

Testable versions of ZIO services enabling deterministic testing of time, console, randomness, and system properties.

type ZTestEnv = TestClock with TestConsole with TestRandom with TestSystem

// TestClock operations
def adjust(duration: Duration): URIO[TestClock, Unit]
def setTime(duration: Duration): URIO[TestClock, Unit]

// TestConsole operations
def feedLines(lines: String*): URIO[TestConsole, Unit] 
val output: ZIO[TestConsole, Nothing, Vector[String]]

// TestRandom operations
def feedInts(ints: Int*): URIO[TestRandom, Unit]
def setSeed(seed: Long): URIO[TestRandom, Unit]

Test Environment

Test Aspects

Cross-cutting concerns for tests including timeouts, retries, conditional execution, and test organization.

abstract class TestAspect[+LowerR, -UpperR, +LowerE, -UpperE]

// Built-in aspects
val ignore: TestAspectAtLeastR[Annotations]
def timeout(duration: Duration): TestAspectAtLeastR[Live]
val flaky: TestAspectAtLeastR[Annotations]
def retry(schedule: Schedule[Any, TestFailure[Any], Any]): TestAspectPoly
def tag(tag: String, tags: String*): TestAspectPoly

Test Aspects

Mock Testing Framework

Service mocking system with expectation-based testing for ZIO services.

trait Mock[R]
abstract class Expectation[R]
sealed trait Capability[R, I, E, A]

// Mock creation
object MockClock extends Mock[Clock]
object MockConsole extends Mock[Console]
object MockRandom extends Mock[Random]

Mock Testing

Test Specifications

Base classes and utilities for creating runnable test specifications.

abstract class RunnableSpec[R, E]
abstract class DefaultRunnableSpec extends RunnableSpec[TestEnvironment, Any]

final case class Spec[-R, +E, +T](caseValue: SpecCase[R, E, T, Spec[R, E, T]])

Test Specifications

Types

Core Types

// Test results
sealed trait TestSuccess
sealed trait TestFailure[+E]

// Assertion types  
final class Assertion[-A]
type AssertResult = BoolAlgebra[AssertionValue]
type AssertResultM = BoolAlgebraM[Any, Nothing, AssertionValue]

// Annotation types
type Annotated[+A] = (A, TestAnnotationMap)
trait TestAnnotation[V]

// Environment types
type TestEnvironment = TestClock with TestConsole with TestRandom with TestSystem with Annotations with Live

Generator Types

final case class Gen[-R, +A](sample: ZStream[R, Nothing, Sample[R, A]])
final case class Sample[+R, +A](value: A, shrink: ZStream[R, Nothing, Sample[R, A]])

// Test configuration
type TestConfig = Has[TestConfig.Service]
type Sized = Has[Sized.Service]