or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cross-platform-communication.mdevent-handling.mdframework-integration.mdindex.mdtest-execution.md
tile.json

tessl/maven-dev-zio--zio-test-sbt_sjs1_3

SBT test framework integration for ZIO that enables running ZIO-based test suites through SBT's testing infrastructure.

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

To install, run

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

index.mddocs/

ZIO Test SBT

ZIO Test SBT provides SBT test framework integration for ZIO, enabling developers to run ZIO-based test suites through SBT's standard testing infrastructure. It includes test task implementations that bridge ZIO's asynchronous, effect-based testing model with SBT's test interface, supporting cross-compilation for JVM, JavaScript (Scala.js), and Native platforms.

Package Information

  • Package Name: zio-test-sbt
  • Package Type: Maven
  • Group ID: dev.zio
  • Artifact ID: zio-test-sbt_sjs1_3
  • Version: 1.0.18
  • Language: Scala
  • Platforms: JVM, JavaScript (Scala.js), Native (Scala Native)
  • Installation: Add to build.sbt: 
    libraryDependencies += "dev.zio" %% "zio-test-sbt" % "1.0.18"

Core Imports

import zio.test.sbt._

Platform-specific imports:

// For SBT framework registration (automatically handled)
import zio.test.sbt.ZTestFramework

// For custom test tasks or runners
import zio.test.sbt.{ZTestRunner, BaseTestTask, ZTestEvent}

// For summary handling and communication
import zio.test.sbt.{SendSummary, SummaryProtocol}

Basic Usage

ZIO Test SBT integrates automatically with SBT's testing infrastructure. Users typically don't interact with the API directly, but register the framework in their build configuration:

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

// Your ZIO test specifications
import zio.test._

object MySpec extends DefaultRunnableSpec {
  def spec = suite("MySpec")(
    test("example test") {
      assert(2 + 2)(equalTo(4))
    }
  )
}

The framework automatically discovers and executes ZIO test specifications when running sbt test.

Architecture

ZIO Test SBT is built around several key components that work together to bridge ZIO's effect system with SBT's testing infrastructure:

  • Framework Layer: ZTestFramework serves as the entry point for SBT integration, implementing SBT's Framework interface
  • Runner Layer: Platform-specific runners (ZTestRunner, ZMasterTestRunner, ZSlaveTestRunner) handle test discovery and execution coordination
  • Task Layer: BaseTestTask and platform-specific task implementations execute individual test specifications within the ZIO runtime
  • Event System: ZTestEvent converts ZIO test results into SBT-compatible events for reporting and IDE integration
  • Communication Layer: SendSummary and SummaryProtocol handle result transmission, especially for distributed execution on JS/Native platforms

Capabilities

Framework Integration

Core SBT framework integration that enables ZIO test discovery and execution within SBT's testing infrastructure.

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
}

Framework Integration

Test Execution

Test execution system that runs ZIO test specifications and handles platform-specific execution models.

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

class ZTestRunner(
  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
}

Test Execution

Event Handling and Reporting

Event system that converts ZIO test results into SBT-compatible events for reporting, IDE integration, and test result visualization.

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

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

Event Handling

Cross-Platform Communication

Communication system for handling test result transmission across different platforms, with serialization support for JavaScript and Native platforms.

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
}

object SummaryProtocol {
  def serialize(summary: zio.test.Summary): String
  def deserialize(s: String): Option[zio.test.Summary]
}

Cross-Platform Communication

Types

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

// Fingerprint for ZIO test discovery
object RunnableSpecFingerprint extends sbt.testing.SubclassFingerprint {
  def superclassName(): String
  def isModule(): Boolean  
  def requireNoArgConstructor(): Boolean
}

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

// Default task policy implementation
class ZTestTaskPolicyDefaultImpl extends ZTestTaskPolicy {
  def merge(zioTasks: Array[ZTestTask]): Array[sbt.testing.Task]
}