or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

event-handling.mdframework-integration.mdindex.mdjs-platform.mdjvm-platform.mdnative-platform.mdtest-discovery.md
tile.json

tessl/maven-dev-zio--zio-test-sbt-3

ZIO Test SBT Framework integration that provides test interface implementation for running ZIO-based tests within SBT build environments

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

To install, run

npx @tessl/cli install tessl/maven-dev-zio--zio-test-sbt-3@2.1.0

index.mddocs/

ZIO Test SBT

ZIO Test SBT provides a comprehensive SBT test framework integration for ZIO Test, enabling seamless execution of ZIO-based tests within SBT build environments. It offers cross-platform support for JVM, JavaScript, and Scala Native platforms through a unified test interface implementation.

Package Information

  • Package Name: zio-test-sbt_3
  • Package Type: maven
  • Language: Scala
  • Group ID: dev.zio
  • Installation: libraryDependencies += "dev.zio" %% "zio-test-sbt" % "2.1.19"

Core Imports

import zio.test.sbt._

For SBT framework usage:

import zio.test.sbt.ZTestFramework

For event handling:

import zio.test.sbt.{ZTestEvent, ZTestEventHandlerSbt}

Basic Usage

ZIO Test SBT is primarily configured through SBT's test framework mechanism. In your build.sbt:

// Enable ZIO Test framework
testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")

// Your ZIO test specifications
libraryDependencies += "dev.zio" %% "zio-test" % "2.1.19" % Test
libraryDependencies += "dev.zio" %% "zio-test-sbt" % "2.1.19" % Test

Example ZIO test specification that works with this framework:

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

object MyZIOSpec extends ZIOSpecDefault {
  def spec = suite("MyTests")(
    test("example test") {
      assert(1 + 1)(equalTo(2))
    }
  )
}

Architecture

ZIO Test SBT is built around the SBT Testing Interface with several key components:

  • Framework Integration: ZTestFramework implements SBT's Framework interface, providing discovery and runner creation
  • Test Discovery: ZioSpecFingerprint enables SBT to find ZIO test specifications in the classpath
  • Platform-Specific Runners: Separate implementations for JVM, JavaScript, and Native platforms handle test execution
  • Event System: Converts ZIO test events to SBT events for proper integration with build tools and IDEs
  • Cross-Platform Design: Shared abstractions with platform-specific optimizations for each target environment

Capabilities

Framework Integration

Core SBT framework implementation that enables ZIO Test to be recognized and executed by SBT, providing the primary entry point for test discovery and execution.

final class ZTestFramework extends Framework {
  val name: String
  val fingerprints: Array[Fingerprint]
  def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): Runner
}

Framework Integration

Test Discovery

Test specification discovery mechanism that allows SBT to identify ZIO test classes and convert them into executable test tasks.

object ZioSpecFingerprint extends SubclassFingerprint {
  def superclassName(): String
  def isModule(): Boolean  
  def requireNoArgConstructor(): Boolean
}

Test Discovery

Event Handling

Event conversion and handling system that translates ZIO test execution events into SBT's event format for proper reporting and integration.

final case class ZTestEvent(
  fullyQualifiedName0: String,
  selector0: Selector,
  status0: Status,
  maybeThrowable: Option[Throwable],
  duration0: Long,
  fingerprint0: Fingerprint
) extends Event

class ZTestEventHandlerSbt(
  eventHandler: EventHandler, 
  taskDef: TaskDef, 
  renderer: TestRenderer
) extends ZTestEventHandler {
  def handle(event: ExecutionEvent): UIO[Unit]
}

Event Handling

JVM Platform Support

Full-featured JVM test runner with advanced debugging capabilities, signal handling, and comprehensive SBT integration features.

final class ZTestRunnerJVM(
  args: Array[String], 
  remoteArgs: Array[String], 
  testClassLoader: ClassLoader
) extends Runner {
  def tasks(defs: Array[TaskDef]): Array[Task]
  def done(): String
}

JVM Platform Support

JavaScript Platform Support

Lightweight JavaScript test runner with master/slave architecture for distributed test execution and inter-process communication through serialized summaries.

sealed abstract class ZTestRunnerJS(
  args: Array[String],
  remoteArgs: Array[String], 
  testClassLoader: ClassLoader,
  runnerType: String
) extends Runner

final class ZMasterTestRunnerJS extends ZTestRunnerJS
final class ZSlaveTestRunnerJS extends ZTestRunnerJS

JavaScript Platform Support

Native Platform Support

Scala Native test runner optimized for native compilation with efficient memory usage and native-specific execution patterns.

sealed abstract class ZTestRunnerNative(
  args: Array[String],
  remoteArgs: Array[String],
  testClassLoader: ClassLoader, 
  runnerType: String
) extends Runner

final class ZMasterTestRunner extends ZTestRunnerNative
final class ZSlaveTestRunner extends ZTestRunnerNative

Native Platform Support

Types

SendSummary

Type alias for summary handling operations.

type SendSummary = URIO[Summary, Unit]

object SendSummary {
  def fromSend(send: Summary => Unit): SendSummary
  def fromSendZIO(send: Summary => UIO[Unit]): SendSummary  
  def noop: SendSummary
}

BaseTestTask

Abstract base class for all platform-specific test tasks, providing shared functionality for test execution and SBT integration.

abstract class BaseTestTask[T](
  taskDef0: TaskDef,
  testClassLoader: ClassLoader,
  sendSummary: SendSummary,
  args: TestArgs,
  spec: ZIOSpecAbstract,
  runtime: zio.Runtime[T],
  console: Console
) extends Task {
  def taskDef(): TaskDef
  def execute(eventHandler: EventHandler, loggers: Array[Logger]): Array[Task]
  def tags(): Array[String]
  
  /**
   * Creates the shared test layer with environment and scope
   * @param trace Implicit trace for ZIO effect tracking
   * @return ZLayer providing TestEnvironment, ZIOAppArgs, and Scope
   */
  protected def sharedFilledTestLayer(implicit trace: Trace): ZLayer[Any, Nothing, TestEnvironment with ZIOAppArgs with Scope]
  
  /**
   * Internal method to run the test with event handling
   * @param eventHandlerZ ZIO Test event handler for test execution
   * @param trace Implicit trace for ZIO effect tracking
   * @return ZIO effect representing test execution
   */
  private[zio] def run(eventHandlerZ: ZTestEventHandler)(implicit trace: Trace): ZIO[Any, Throwable, Unit]
}

SummaryProtocol

Serialization protocol for test summaries in distributed execution environments (JavaScript and Native platforms).

object SummaryProtocol {
  def serialize(summary: Summary): String
  def deserialize(s: String): Option[Summary]
  def escape(token: String): String
  def unescape(token: String): String
}