or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cross-platform.mdevent-handling.mdindex.mdsbt-framework.mdtest-runners.md
tile.json

tessl/maven-dev-zio--zio-test-sbt_2-13

SBT test framework integration for ZIO tests, enabling developers to run ZIO-based test suites within the SBT build tool ecosystem.

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

To install, run

npx @tessl/cli install tessl/maven-dev-zio--zio-test-sbt_2-13@2.1.0

index.mddocs/

ZIO Test SBT

ZIO Test SBT provides SBT test framework integration for ZIO tests, enabling developers to run ZIO-based test suites within the SBT build tool ecosystem. It implements the SBT test interface standard to seamlessly integrate ZIO's functional testing capabilities with SBT's testing infrastructure.

Package Information

  • Package Name: zio-test-sbt_2.13
  • Package Type: Maven
  • Organization: dev.zio
  • Language: Scala
  • Cross-Platform: JVM, JavaScript (Scala.js), Native (Scala Native)
  • Installation: libraryDependencies += "dev.zio" %% "zio-test-sbt" % "2.1.19"

Core Imports

import zio.test.sbt._
import zio.test.sbt.ZTestFramework
import zio.test.sbt.ZioSpecFingerprint

Basic Usage

ZIO Test SBT is primarily used by SBT build tool automatically when running tests. It doesn't require direct usage in most cases - you simply configure it in your build.sbt:

testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework")

For advanced usage scenarios involving custom test runners or event handling:

import zio.test.sbt._

// Create a custom summary sender
val summaryHandler: SendSummary = SendSummary.fromSend { summary =>
  println(s"Tests completed: ${summary.total}, Failed: ${summary.fail}")
}

// Custom event handling for integration scenarios
val customHandler = new ZTestEventHandlerSbt(eventHandler, taskDef, renderer)

Architecture

ZIO Test SBT bridges ZIO's functional test framework with SBT's imperative test interface through several key components:

  • Framework Interface: ZTestFramework implements SBT's Framework interface
  • Test Discovery: ZioSpecFingerprint enables SBT to find ZIO test classes
  • Test Execution: Platform-specific runners manage the ZIO test lifecycle
  • Event Translation: Converts ZIO test events to SBT-compatible formats
  • Cross-Platform Support: Unified API across JVM, JavaScript, and Native platforms

Capabilities

SBT Framework Integration

Implements the SBT test framework interface for ZIO test discovery and execution.

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

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

SBT Framework Integration

Test Runners

Platform-specific test runners that execute ZIO tests within the SBT ecosystem.

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

// Cross-platform base task
abstract class BaseTestTask[T](
  taskDef: sbt.testing.TaskDef,
  testClassLoader: ClassLoader,
  sendSummary: SendSummary,
  args: zio.test.TestArgs,
  spec: zio.test.ZIOSpecAbstract,
  runtime: zio.Runtime[T],
  console: zio.Console
) extends sbt.testing.Task

Test Runners

Event Handling

Converts ZIO test execution events to SBT-compatible event formats.

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

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

Event Handling

Cross-Platform Support

Specialized implementations for JavaScript and Native platforms with summary protocols.

// Summary protocol for JS/Native inter-process communication
object SummaryProtocol {
  def serialize(summary: zio.test.Summary): String
  def deserialize(s: String): Option[zio.test.Summary]
  def escape(token: String): String
  def unescape(token: String): String
}

// Platform-specific runners
class ZMasterTestRunnerJS(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader)
class ZSlaveTestRunnerJS(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader, sendSummary: SendSummary)

Cross-Platform Support

Types

// Type alias for summary sending operations  
type SendSummary = zio.URIO[zio.test.Summary, Unit]

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

// Summary type from zio.test package
case class Summary(
  success: Int,
  fail: Int, 
  ignore: Int,
  failureDetails: String,
  duration: zio.Duration = zio.Duration.Zero
) {
  def add(that: Summary): Summary
  def add(executionEvent: zio.test.ExecutionEvent)(implicit trace: zio.Trace): Summary
  def status: Summary.Status
  def total: Int
  def timed(start: java.time.Instant, end: java.time.Instant): Summary
}

object Summary {
  val empty: Summary
  
  sealed trait Status
  object Success extends Status
  object Failure extends Status
}

Error Handling

ZIO Test SBT handles various error scenarios:

  • ClassNotFoundException: When test classes cannot be loaded
  • Runtime Failures: ZIO runtime failures are converted to SBT failure events
  • Signal Handling: JVM implementation includes signal handlers for fiber dumping
  • Cancellation: Proper cleanup via cancellable futures and shutdown hooks