or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

assertions.mdcore-testing.mdindex.mdproperty-testing.mdsmart-assertions.mdtest-aspects.mdtest-services.md
tile.json

tessl/maven-dev-zio--zio-test_3

ZIO Test is a featherweight testing library for effectful programs built on ZIO, providing a comprehensive framework for property-based testing, test composition, and resource-safe test execution.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/dev.zio/zio-test_3@2.1.x

To install, run

npx @tessl/cli install tessl/maven-dev-zio--zio-test_3@2.1.0

index.mddocs/

ZIO Test

ZIO Test is a featherweight testing library for effectful programs built on ZIO, providing a comprehensive framework for property-based testing, test composition, and resource-safe test execution. It enables developers to write tests that are both expressive and reliable, with automatic resource cleanup, deterministic test execution through ZIO's effect system, and rich assertion capabilities.

Package Information

  • Package Name: zio-test
  • Package Type: Maven
  • Language: Scala
  • Installation: 
    // SBT
libraryDependencies += "dev.zio" %% "zio-test" % "2.1.19" % Test
libraryDependencies += "dev.zio" %% "zio-test-sbt" % "2.1.19" % Test

// Mill
def testDeps = Agg(ivy"dev.zio::zio-test:2.1.19")

Core Imports

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

For basic testing with default environment:

import zio.test._

object MyTest extends ZIOSpecDefault {
  def spec = suite("my tests")(
    test("basic test") {
      assertTrue(2 + 2 == 4)
    }
  )
}

For testing with custom environment:

import zio.test._

object MyTest extends ZIOSpec[MyTestEnvironment] {
  type Env = MyTestEnvironment
  
  def spec = suite("my tests")(
    test("custom environment test") {
      for {
        service <- ZIO.service[MyService]
        result  <- service.doSomething()
      } yield assertTrue(result.isSuccess)
    }
  )
}

Basic Usage

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

object ExampleTest extends ZIOSpecDefault {
  def spec = suite("Example Tests")(
    
    // Basic assertion test
    test("simple assertion") {
      assertTrue(2 + 2 == 4)
    },
    
    // Effectful test
    test("effectful computation") {
      for {
        result <- ZIO.succeed(42)
      } yield assertTrue(result > 40)
    },
    
    // Property-based test
    test("property test") {
      check(Gen.int) { n =>
        assertTrue((n + 1) > n)
      }
    },
    
    // Test with custom assertion
    test("collection assertion") {
      val numbers = List(1, 2, 3, 4, 5)
      assertTrue(
        numbers.contains(3) &&
        numbers.size == 5 &&
        numbers.forall(_ > 0)
      )
    }
  )
}

Architecture

ZIO Test is built around several key components:

  • Spec DSL: Hierarchical test structure using suite() and test() for organizing tests
  • Assertion System: Rich assertion library with smart assertions (Scala 3) and traditional assertion functions
  • Property Testing: Comprehensive generator system (Gen) for property-based testing with automatic shrinking
  • Test Services: Controllable test environment services (TestClock, TestConsole, TestRandom, etc.) for deterministic testing
  • Test Aspects: Cross-cutting concerns like timeouts, retries, parallelism, and lifecycle hooks
  • Effect Integration: Seamless ZIO effect system integration with proper resource management and error handling

Capabilities

Core Testing DSL

Essential functions for creating test specifications and organizing test suites. The foundation of all ZIO Test usage.

def suite[In](label: String)(specs: In*)(implicit 
  suiteConstructor: SuiteConstructor[In]
): Spec[suiteConstructor.OutEnvironment, suiteConstructor.OutError]

def test[In](label: String)(assertion: => In)(implicit
  testConstructor: TestConstructor[Nothing, In]
): testConstructor.Out

type ZTest[-R, +E] = ZIO[R, TestFailure[E], TestSuccess]

Core Testing DSL

Smart Assertions (Scala 3)

Compile-time smart assertions with automatic expression analysis and enhanced error reporting for more intuitive test writing.

inline def assertTrue(inline assertion: Boolean)(implicit 
  trace: Trace, sourceLocation: SourceLocation
): TestResult

inline def assert[A](inline value: A)(inline assertion: Assertion[A])(implicit
  trace: Trace, sourceLocation: SourceLocation  
): TestResult

inline def assertZIO[R, E, A](effect: ZIO[R, E, A])(inline assertion: Assertion[A])(implicit
  trace: Trace, sourceLocation: SourceLocation
): ZIO[R, E, TestResult]

Smart Assertions

Assertion Library

Comprehensive assertion system with 100+ built-in assertions for values, collections, exceptions, and more.

case class Assertion[-A](arrow: TestArrow[A, Boolean])

def equalTo[A](expected: A): Assertion[A]
def contains[A](expected: A): Assertion[Iterable[A]]
def hasSize[A](expected: Int): Assertion[Iterable[A]]
def isLessThan[A: Ordering](expected: A): Assertion[A]
def startsWith[A](expected: Seq[A]): Assertion[Seq[A]]
def succeeds[A](assertion: Assertion[A]): Assertion[Exit[Any, A]]
def fails[E](assertion: Assertion[E]): Assertion[Exit[E, Any]]

Assertions

Property-Based Testing

Generator system for creating random test data and property-based testing with automatic shrinking support.

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

def check[R, A, In](rv: Gen[R, A])(test: A => In)(implicit
  checkConstructor: CheckConstructor[R, In]
): ZIO[checkConstructor.OutEnvironment, checkConstructor.OutError, TestResult]

def checkAll[R, A, In](rv: Gen[R, A])(test: A => In)(implicit
  checkConstructor: CheckConstructor[R, In]  
): ZIO[checkConstructor.OutEnvironment, checkConstructor.OutError, TestResult]

def int: Gen[Any, Int]
def string: Gen[Any, String] 
def listOf[A](gen: Gen[Any, A]): Gen[Any, List[A]]

Property Testing

Test Services

Controllable test environment services that replace real services with deterministic, testable implementations.

trait TestClock extends Clock
trait TestConsole extends Console  
trait TestRandom extends Random
trait TestSystem extends System
trait TestConfig

type TestEnvironment = Annotations with Live with Sized with TestConfig

def testClock(implicit trace: Trace): UIO[TestClock]
def testConsole(implicit trace: Trace): UIO[TestConsole]
def testRandom(implicit trace: Trace): UIO[TestRandom]
def testSystem(implicit trace: Trace): UIO[TestSystem]

Test Services

Test Aspects

Cross-cutting concerns for configuring test execution, lifecycle, timeouts, retries, and environment management.

abstract class TestAspect[-R0, +R1, -E0, +E1]

def timeout(duration: Duration): TestAspectPoly
def ignore: TestAspectPoly
def flaky(n: Int): TestAspectPoly
def parallel: TestAspectPoly  
def sequential: TestAspectPoly
def before[R](zio: ZIO[R, Nothing, Any]): TestAspect[Nothing, R, Nothing, Any]
def after[R](zio: ZIO[R, Nothing, Any]): TestAspect[Nothing, R, Nothing, Any]

Test Aspects

Types

// Core test specification type
final case class Spec[-R, +E](caseValue: SpecCase[R, E, Spec[R, E]])

// Test result types
sealed trait TestSuccess
sealed trait TestFailure[+E]
case class TestResult(arrow: TestArrow[Any, Boolean])

// Base specification classes
abstract class ZIOSpecDefault extends ZIOSpec[TestEnvironment]
abstract class ZIOSpec[R] extends ZIOSpecAbstract[R]
abstract class ZIOSpecAbstract[R]

// Environment and configuration
type TestEnvironment = Annotations with Live with Sized with TestConfig