or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-dev-zio--zio-test-sbt_3

SBT test framework integration for ZIO Test, providing infrastructure to run ZIO-based tests within SBT build environments across JVM, JavaScript, and Native platforms

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

To install, run

npx @tessl/cli install tessl/maven-dev-zio--zio-test-sbt_3@1.0.0

index.mddocs/

ZIO Test SBT

SBT test framework integration for ZIO Test, providing the necessary infrastructure to run ZIO-based tests within SBT build environments across JVM, JavaScript, and Native platforms. This library implements the SBT testing interface protocols and provides test runners, event handlers, and summary reporting capabilities for ZIO Test specifications.

Package Information

  • Package Name: zio-test-sbt
  • Package Group: dev.zio
  • Language: Scala
  • Platforms: JVM, JavaScript (ScalaJS), Native (Scala Native)
  • Installation: Add to build.sbt: libraryDependencies += "dev.zio" %% "zio-test-sbt" % "1.0.18"

Core Imports

import zio.test.sbt._

For SBT framework integration:

import zio.test.sbt.ZTestFramework

For custom test tasks:

import zio.test.sbt.{BaseTestTask, SendSummary}

Basic Usage

The framework is automatically detected by SBT when included as a dependency. ZIO Test specs extending AbstractRunnableSpec are automatically discovered and executed:

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

object MyTestSuite extends DefaultRunnableSpec {
  def spec = suite("MyTestSuite")(
    test("basic test") {
      assert(1 + 1)(equalTo(2))
    },
    test("async test") {
      for {
        result <- ZIO.succeed(42)
      } yield assert(result)(equalTo(42))
    }
  )
}

Architecture

The library follows SBT's testing framework protocol with ZIO-specific implementations:

  • ZTestFramework: Entry point that SBT uses to discover and execute tests
  • ZTestRunner: Platform-specific test runners that manage test execution
  • BaseTestTask: Base class for individual test tasks that run ZIO specs
  • ZTestEvent: SBT-compatible events generated from ZIO test results
  • SummaryProtocol: Serialization for distributed testing (JS/Native platforms)

Capabilities

Framework Integration

The main entry point for SBT integration.

JVM Framework

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

JavaScript/Native Framework

final class ZTestFramework extends sbt.testing.Framework {
  override def name(): String
  override def fingerprints(): Array[sbt.testing.Fingerprint]
  def runner(args: Array[String], remoteArgs: Array[String], testClassLoader: ClassLoader): sbt.testing.Runner
  def slaveRunner(
    args: Array[String],
    remoteArgs: Array[String], 
    testClassLoader: ClassLoader,
    send: String => Unit
  ): sbt.testing.Runner
}

The framework provides:

  • Automatic discovery of ZIO test specifications via RunnableSpecFingerprint
  • Cross-platform support (JVM, JS, Native)
  • Distributed testing support for JS/Native platforms via master/slave runner architecture

Test Runners

Platform-specific implementations for executing ZIO tests within SBT.

JVM Test Runner

final class ZTestRunner(
  val args: Array[String], 
  val remoteArgs: Array[String], 
  testClassLoader: ClassLoader
) extends sbt.testing.Runner {
  val summaries: java.util.concurrent.atomic.AtomicReference[Vector[zio.test.Summary]]
  val sendSummary: SendSummary
  
  def tasks(defs: Array[sbt.testing.TaskDef]): Array[sbt.testing.Task]
  def done(): String
}

JavaScript/Native Test Runners

abstract class ZTestRunner(
  args: Array[String],
  remoteArgs: Array[String], 
  testClassLoader: ClassLoader,
  runnerType: String
) extends sbt.testing.Runner {
  def sendSummary: SendSummary
  def tasks(defs: Array[sbt.testing.TaskDef]): Array[sbt.testing.Task]
  def done(): String
  def receiveMessage(summary: String): Option[String]
  def serializeTask(task: sbt.testing.Task, serializer: sbt.testing.TaskDef => String): String
  def deserializeTask(task: String, deserializer: String => sbt.testing.TaskDef): sbt.testing.Task
}

class ZMasterTestRunner(
  args: Array[String], 
  remoteArgs: Array[String], 
  testClassLoader: ClassLoader
) extends ZTestRunner

class ZSlaveTestRunner(
  args: Array[String], 
  remoteArgs: Array[String], 
  testClassLoader: ClassLoader,
  sendSummary: SendSummary
) extends ZTestRunner

Test Tasks

Base class for executing individual ZIO test specifications.

abstract class BaseTestTask(
  taskDef0: sbt.testing.TaskDef,
  testClassLoader: ClassLoader,
  sendSummary: SendSummary,
  args: zio.test.TestArgs
) extends sbt.testing.Task {
  val testClassLoader: ClassLoader
  val sendSummary: SendSummary
  val args: zio.test.TestArgs
  
  final def taskDef(): sbt.testing.TaskDef
  def execute(eventHandler: sbt.testing.EventHandler, loggers: Array[sbt.testing.Logger]): Array[sbt.testing.Task]
  def tags(): Array[String]
}

Platform-specific task implementations:

// JVM Task
class ZTestTask(
  taskDef: sbt.testing.TaskDef,
  testClassLoader: ClassLoader, 
  sendSummary: SendSummary,
  testArgs: zio.test.TestArgs
) extends BaseTestTask

// JS/Native Task (with async execution)
class ZTestTask(
  taskDef: sbt.testing.TaskDef,
  testClassLoader: ClassLoader,
  runnerType: String,
  sendSummary: SendSummary, 
  testArgs: zio.test.TestArgs
) extends BaseTestTask {
  def execute(
    eventHandler: sbt.testing.EventHandler,
    loggers: Array[sbt.testing.Logger], 
    continuation: Array[sbt.testing.Task] => Unit
  ): Unit
}

Test Events

SBT-compatible events generated from ZIO test execution results.

// JVM/JS Implementation
case class ZTestEvent(
  fullyQualifiedName: String,
  selector: sbt.testing.Selector,
  status: sbt.testing.Status,
  maybeThrowable: Option[Throwable],
  duration: Long,
  fingerprint: sbt.testing.Fingerprint
) extends sbt.testing.Event {
  def throwable(): sbt.testing.OptionalThrowable
}

// Native Implementation (with explicit overrides)
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 {
  override def fullyQualifiedName(): String
  override def selector(): sbt.testing.Selector
  override def status(): sbt.testing.Status
  override def duration(): Long
  override def fingerprint(): sbt.testing.Fingerprint
  def throwable(): sbt.testing.OptionalThrowable
}

object ZTestEvent {
  def from[E](
    executedSpec: zio.test.ExecutedSpec[E],
    fullyQualifiedName: String,
    fingerprint: sbt.testing.Fingerprint
  ): Seq[ZTestEvent]
}

Task Policies

Customizable policies for merging and organizing test tasks.

abstract class ZTestTaskPolicy {
  def merge(zioTasks: Array[ZTestTask]): Array[sbt.testing.Task]
}

class ZTestTaskPolicyDefaultImpl extends ZTestTaskPolicy {
  override def merge(zioTasks: Array[ZTestTask]): Array[sbt.testing.Task] = zioTasks.toArray
}

Summary Management

Type-safe summary handling with platform-specific serialization support.

type SendSummary = zio.URIO[zio.test.Summary, Unit]

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

For JavaScript/Native distributed testing:

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
}

Test Discovery

Fingerprint for automatic discovery of ZIO test specifications.

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

Types

Core Types

// Re-exported from zio.test
type Summary = zio.test.Summary
type TestArgs = zio.test.TestArgs
type ExecutedSpec[E] = zio.test.ExecutedSpec[E]
type AbstractRunnableSpec = zio.test.AbstractRunnableSpec

// SBT Testing API types (from sbt.testing._)
type Framework = sbt.testing.Framework
type Runner = sbt.testing.Runner  
type Task = sbt.testing.Task
type TaskDef = sbt.testing.TaskDef
type Event = sbt.testing.Event
type EventHandler = sbt.testing.EventHandler
type Logger = sbt.testing.Logger
type Fingerprint = sbt.testing.Fingerprint
type SubclassFingerprint = sbt.testing.SubclassFingerprint
type Selector = sbt.testing.Selector
type TestSelector = sbt.testing.TestSelector
type Status = sbt.testing.Status
type OptionalThrowable = sbt.testing.OptionalThrowable

Platform-Specific Differences

JVM Platform

  • Synchronous test execution
  • Single ZTestRunner implementation
  • Direct task execution without continuations

JavaScript Platform

  • Master/slave runner architecture for distributed testing
  • Asynchronous task execution with continuations
  • Message-based summary communication via SummaryProtocol
  • Task serialization/deserialization support

Native Platform

  • Similar to JavaScript platform architecture
  • Supports distributed testing capabilities
  • Platform-specific ZTestEvent implementation with explicit method overrides

Error Handling

Test failures are converted to appropriate SBT events:

  • TestFailure.Assertion becomes AssertionError
  • TestFailure.Runtime becomes RuntimeException
  • All errors include rendered test output with ANSI codes stripped

Integration Notes

  • Tests are automatically discovered if they extend AbstractRunnableSpec
  • Test arguments can be passed through SBT's testOptions
  • Summary information is collected and displayed at completion
  • Supports SBT's parallel test execution
  • Compatible with SBT's test filtering and selection