CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

Pending
Overview
Eval results
Files

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

Install with Tessl CLI

npx tessl i tessl/maven-dev-zio--zio-test-sbt-2-13
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/dev.zio/zio-test-sbt_2.13@2.1.x
Badge
tessl/maven-dev-zio--zio-test-sbt-2-13 badge