or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

async-testing.mdconfiguration.mdindex.mdlogging.mdsync-testing.mdtest-probes.mdtime-control.md
tile.json

configuration.mddocs/

Configuration

Test configuration management including timeout settings, time dilation, and shutdown behavior for controlling test execution and reliability.

Capabilities

TestKitSettings

Main configuration class for controlling test kit behavior including timeouts, time dilation, and system shutdown.

/**
 * Factory methods for creating TestKitSettings
 */
object TestKitSettings {
  /** Create settings from actor system configuration */
  def apply(system: ActorSystem[_]): TestKitSettings
  /** Create settings from custom configuration */
  def apply(config: Config): TestKitSettings
  /** Java API: Create settings from actor system */
  def create(system: ActorSystem[_]): TestKitSettings
  /** Java API: Create settings from custom configuration */
  def create(config: Config): TestKitSettings
}

/**
 * Configuration settings for test kit behavior
 */
class TestKitSettings(val config: Config) {
  /** Time scaling factor for test timeouts (must be positive finite) */
  val TestTimeFactor: Double
  
  /** Default timeout for single message expectations (dilated) */
  val SingleExpectDefaultTimeout: FiniteDuration
  /** Default timeout for expect-no-message assertions (dilated) */
  val ExpectNoMessageDefaultTimeout: FiniteDuration
  /** Default timeout for ask operations (dilated) */
  val DefaultTimeout: Timeout
  /** Default timeout for actor system shutdown (dilated) */
  val DefaultActorSystemShutdownTimeout: FiniteDuration
  
  /** Whether to throw exception on shutdown timeout */
  val ThrowOnShutdownTimeout: Boolean
  /** Time allowance for log filtering operations (dilated) */
  val FilterLeeway: FiniteDuration
  
  /** Apply time dilation to duration */
  def dilated(duration: FiniteDuration): FiniteDuration
  /** Java API: Apply time dilation to duration */
  def dilated(duration: java.time.Duration): java.time.Duration
}

Usage Examples:

import akka.actor.testkit.typed.{TestKitSettings}
import akka.actor.testkit.typed.scaladsl.ActorTestKit
import com.typesafe.config.ConfigFactory
import scala.concurrent.duration._

// Create test kit with custom settings
val customConfig = ConfigFactory.parseString("""
  akka.actor.testkit.typed {
    timefactor = 2.0
    single-expect-default = 5s
    expect-no-message-default = 200ms
    default-timeout = 10s
  }
""")

val testKit = ActorTestKit("test-system", customConfig)
val settings = testKit.testKitSettings

// Use dilation
val dilatedTimeout = settings.dilated(1.second) // Will be 2 seconds with timefactor = 2.0

println(s"Time factor: ${settings.TestTimeFactor}")
println(s"Default timeout: ${settings.DefaultTimeout}")

Time Dilation

Configuration and utilities for scaling test timeouts to handle varying execution speeds across environments.

/**
 * Time scaling factor for all test timeouts
 * Configured via akka.actor.testkit.typed.timefactor
 */
val TestTimeFactor: Double

/**
 * Apply time dilation to a duration
 * @param duration Original duration to scale
 * @returns Scaled duration using TestTimeFactor
 */
def dilated(duration: FiniteDuration): FiniteDuration

/**
 * Java API: Apply time dilation to a Java duration
 * @param duration Original Java duration to scale
 * @returns Scaled Java duration using TestTimeFactor
 */
def dilated(duration: java.time.Duration): java.time.Duration

Timeout Configuration

Pre-configured timeout values for different test operations, all subject to time dilation.

/**
 * Default timeout for single message expectations (dilated)
 * Configured via akka.actor.testkit.typed.single-expect-default
 */
val SingleExpectDefaultTimeout: FiniteDuration

/**
 * Default timeout for expect-no-message assertions (dilated)
 * Configured via akka.actor.testkit.typed.expect-no-message-default
 */
val ExpectNoMessageDefaultTimeout: FiniteDuration

/**
 * Default timeout for ask operations (dilated)
 * Configured via akka.actor.testkit.typed.default-timeout
 */
val DefaultTimeout: Timeout

/**
 * Default timeout for actor system shutdown (dilated)
 * Configured via akka.actor.testkit.typed.system-shutdown-default
 */
val DefaultActorSystemShutdownTimeout: FiniteDuration

/**
 * Time allowance for log filtering operations (dilated)
 * Configured via akka.actor.testkit.typed.filter-leeway
 */
val FilterLeeway: FiniteDuration

Usage Examples:

import akka.actor.testkit.typed.scaladsl.ActorTestKit

val testKit = ActorTestKit()
val settings = testKit.testKitSettings

// Access configured timeouts
val singleExpectTimeout = settings.SingleExpectDefaultTimeout
val noMessageTimeout = settings.ExpectNoMessageDefaultTimeout
val askTimeout = settings.DefaultTimeout.duration

// Use in test probe operations
val probe = testKit.createTestProbe[String]()
probe.expectMessage(singleExpectTimeout, "expected message")
probe.expectNoMessage(noMessageTimeout)

Shutdown Configuration

Settings controlling actor system shutdown behavior during test cleanup.

/**
 * Whether to throw exception if actor system shutdown times out
 * Configured via akka.actor.testkit.typed.throw-on-shutdown-timeout
 */
val ThrowOnShutdownTimeout: Boolean

/**
 * Default timeout for actor system shutdown operations (dilated)
 * Configured via akka.actor.testkit.typed.system-shutdown-default
 */
val DefaultActorSystemShutdownTimeout: FiniteDuration

Configuration Reference

Complete reference of available configuration options for the test kit.

akka.actor.testkit.typed {
  # Time scaling factor for test timeouts (must be positive finite double)
  timefactor = 1.0
  
  # Default timeout for single message expectations
  single-expect-default = 3s
  
  # Default timeout for expect-no-message operations  
  expect-no-message-default = 100ms
  
  # Default timeout for ask operations
  default-timeout = 5s
  
  # Default timeout for actor system shutdown
  system-shutdown-default = 10s
  
  # Whether to throw on shutdown timeout
  throw-on-shutdown-timeout = false
  
  # Time allowance for log filtering
  filter-leeway = 3s
}

Usage Examples:

import com.typesafe.config.ConfigFactory

// Custom configuration for testing
val testConfig = ConfigFactory.parseString("""
  akka.actor.testkit.typed {
    # Slow down tests for debugging
    timefactor = 10.0
    
    # Longer timeouts for integration tests
    single-expect-default = 30s
    default-timeout = 60s
    
    # Strict shutdown handling
    throw-on-shutdown-timeout = true
    system-shutdown-default = 5s
  }
""")

// Create test kit with custom configuration
val testKit = ActorTestKit("integration-test", testConfig)

// All timeouts will be scaled by timefactor = 10.0
val probe = testKit.createTestProbe[String]()
probe.expectMessage("test") // Will wait up to 300s (30s * 10.0)

Environment-Specific Configuration

Patterns for configuring test kits for different environments and CI systems.

Development Configuration:

akka.actor.testkit.typed {
  timefactor = 1.0
  single-expect-default = 3s
  throw-on-shutdown-timeout = true
}

CI/Build Server Configuration:

akka.actor.testkit.typed {
  # Account for slower/overloaded CI environment
  timefactor = 3.0
  single-expect-default = 10s
  system-shutdown-default = 30s
  throw-on-shutdown-timeout = false
}

Debug Configuration:

akka.actor.testkit.typed {
  # Very slow timeouts for debugging
  timefactor = 100.0
  single-expect-default = 60s
  expect-no-message-default = 1s
}

Usage Examples:

import akka.actor.testkit.typed.scaladsl.ActorTestKit

// Environment-aware test kit creation
val testKit = sys.env.get("CI") match {
  case Some(_) => 
    // CI environment - use longer timeouts
    val ciConfig = ConfigFactory.parseString("""
      akka.actor.testkit.typed.timefactor = 5.0
    """)
    ActorTestKit("ci-test", ciConfig)
  case None => 
    // Development environment - use defaults
    ActorTestKit()
}

// Configuration validation
val settings = testKit.testKitSettings
require(settings.TestTimeFactor > 0, "Time factor must be positive")
require(settings.TestTimeFactor.isFinite, "Time factor must be finite")