0
# Akka Actor TestKit Typed
1

2
The Akka Actor TestKit Typed is a comprehensive testing library for Akka Typed actors providing both synchronous and asynchronous testing capabilities. It enables testing of actor behaviors, message handling, state transitions, supervision strategies, and provides utilities for time dilation and log verification.
3

4
## Package Information
5

6
- **Package Name**: akka-actor-testkit-typed
7
- **Package Type**: maven
8
- **Language**: Scala with Java interop
9
- **Installation**: Add to your sbt build.sbt:
10
  ```scala
11
  libraryDependencies += "com.typesafe.akka" %% "akka-actor-testkit-typed" % "2.8.8" % Test
12
  ```
13

14
## Core Imports
15

16
**Scala API:**
17
```scala
18
import akka.actor.testkit.typed.scaladsl.{ActorTestKit, BehaviorTestKit, TestProbe}
19
import akka.actor.testkit.typed.scaladsl.LoggingTestKit
20
import akka.actor.testkit.typed.{Effect, TestKitSettings}
21
```
22

23
**Java API:**
24
```java
25
import akka.actor.testkit.typed.javadsl.ActorTestKit;
26
import akka.actor.testkit.typed.javadsl.BehaviorTestKit;
27
import akka.actor.testkit.typed.javadsl.TestProbe;
28
```
29

30
## Basic Usage
31

32
**Asynchronous Testing (ActorTestKit + TestProbe):**
33
```scala
34
import akka.actor.testkit.typed.scaladsl.ActorTestKit
35
import akka.actor.typed.scaladsl.Behaviors
36

37
// Create test kit
38
val testKit = ActorTestKit()
39

40
// Spawn an actor
41
val actor = testKit.spawn(Behaviors.receiveMessage[String] { msg =>
42
  println(s"Received: $msg")
43
  Behaviors.same
44
})
45

46
// Create test probe
47
val probe = testKit.createTestProbe[String]()
48

49
// Send message and verify
50
actor ! "Hello"
51
probe.expectNoMessage() // Verify no reply was sent
52

53
testKit.shutdownTestKit()
54
```
55

56
**Synchronous Testing (BehaviorTestKit):**
57
```scala
58
import akka.actor.testkit.typed.scaladsl.BehaviorTestKit
59
import akka.actor.testkit.typed.Effect
60
import akka.actor.typed.scaladsl.Behaviors
61

62
// Create behavior test kit
63
val testKit = BehaviorTestKit(Behaviors.receiveMessage[String] { msg =>
64
  println(s"Received: $msg")
65
  Behaviors.same
66
})
67

68
// Send message and verify effects
69
testKit.run("Hello")
70
testKit.expectEffect(Effect.NoEffects)
71
```
72

73
## Architecture
74

75
The Akka Actor TestKit Typed is organized around several key components:
76

77
- **Dual Testing Approaches**: Asynchronous testing using real actor systems (ActorTestKit) and synchronous testing with isolated behaviors (BehaviorTestKit)
78
- **Effect System**: Comprehensive capture of all observable side effects from behavior execution for precise testing
79
- **Time Management**: Multi-layered time dilation and manual time control for deterministic testing
80
- **Framework Integration**: Ready-made integrations for ScalaTest and JUnit with automatic cleanup
81
- **Logging Verification**: Comprehensive log testing capabilities with Logback integration
82
- **Serialization Testing**: Built-in utilities for testing message serialization roundtrips
83

84
## Capabilities
85

86
### Asynchronous Testing
87

88
Complete integration testing framework using real ActorSystem for testing actor interactions, message flows, and system behavior.
89

90
```scala { .api }
91
object ActorTestKit {
92
  def apply(): ActorTestKit
93
  def apply(system: ActorSystem[_]): ActorTestKit
94
  def apply(name: String): ActorTestKit
95
  def apply(customConfig: Config): ActorTestKit
96
}
97

98
class ActorTestKit {
99
  def spawn[T](behavior: Behavior[T]): ActorRef[T]
100
  def spawn[T](behavior: Behavior[T], name: String): ActorRef[T]
101
  def createTestProbe[M](): TestProbe[M]
102
  def createTestProbe[M](name: String): TestProbe[M]
103
  def shutdownTestKit(): Unit
104
}
105
```
106

107
[Asynchronous Testing](./async-testing.md)
108

109
### Synchronous Testing
110

111
Unit testing framework for isolated behavior testing with comprehensive effect capture and assertion capabilities.
112

113
```scala { .api }
114
object BehaviorTestKit {
115
  def apply[T](initialBehavior: Behavior[T]): BehaviorTestKit[T]
116
  def apply[T](initialBehavior: Behavior[T], name: String): BehaviorTestKit[T]
117
}
118

119
trait BehaviorTestKit[T] {
120
  def run(message: T): Unit
121
  def retrieveEffect(): Effect
122
  def retrieveAllEffects(): immutable.Seq[Effect]
123
  def expectEffect(expectedEffect: Effect): Unit
124
  def childInbox[U](name: String): TestInbox[U]
125
  def selfInbox(): TestInbox[T]
126
}
127
```
128

129
[Synchronous Testing](./sync-testing.md)
130

131
### Test Probes and Message Assertion
132

133
Flexible message testing with timeouts, selective filtering, and assertion utilities for asynchronous actor testing.
134

135
```scala { .api }
136
trait TestProbe[M] {
137
  def expectMessage[T <: M](obj: T): T
138
  def expectMessage[T <: M](max: FiniteDuration, obj: T): T
139
  def expectMessageType[T <: M](implicit t: ClassTag[T]): T
140
  def expectNoMessage(): Unit
141
  def fishForMessage(max: FiniteDuration)(fisher: M => FishingOutcome): immutable.Seq[M]
142
  def awaitAssert[A](a: => A): A
143
}
144
```
145

146
[Test Probes](./test-probes.md)
147

148
### Log Verification
149

150
Comprehensive log testing with filtering, assertion, and verification capabilities requiring Logback integration.
151

152
```scala { .api }
153
object LoggingTestKit {
154
  def empty: LoggingTestKit
155
  def info(messageIncludes: String): LoggingTestKit
156
  def error(messageIncludes: String): LoggingTestKit
157
  def warn[A <: Throwable: ClassTag]: LoggingTestKit
158
}
159

160
trait LoggingTestKit {
161
  def withOccurrences(newOccurrences: Int): LoggingTestKit
162
  def withLogLevel(newLogLevel: Level): LoggingTestKit
163
  def expect[T](code: => T)(implicit system: ActorSystem[_]): T
164
}
165
```
166

167
[Log Verification](./logging.md)
168

169
### Configuration and Settings
170

171
Test configuration management including timeout settings, time dilation, and shutdown behavior.
172

173
```scala { .api }
174
class TestKitSettings(val config: Config) {
175
  val TestTimeFactor: Double
176
  val SingleExpectDefaultTimeout: FiniteDuration
177
  val DefaultTimeout: Timeout
178
  def dilated(duration: FiniteDuration): FiniteDuration
179
}
180

181
object TestKitSettings {
182
  def apply(system: ActorSystem[_]): TestKitSettings
183
  def apply(config: Config): TestKitSettings
184
}
185
```
186

187
[Configuration](./configuration.md)
188

189
### Time Control
190

191
Manual time control and time dilation utilities for deterministic testing of time-sensitive actor behaviors.
192

193
```scala { .api }
194
trait ManualTime {
195
  def scheduler: TestScheduler
196
  def timePasses(amount: FiniteDuration): Unit
197
  def expectNoMessageFor(duration: FiniteDuration, on: TestProbe[_]*): Unit
198
}
199

200
implicit class TestDuration(val duration: FiniteDuration) {
201
  def dilated(implicit settings: TestKitSettings): FiniteDuration
202
}
203
```
204

205
[Time Control](./time-control.md)
206

207
## Types
208

209
### Effect System
210

211
```scala { .api }
212
sealed trait Effect
213

214
object Effect {
215
  case class Spawned[T](behavior: Behavior[T], name: String, props: Props, ref: ActorRef[T]) extends Effect
216
  case class SpawnedAnonymous[T](behavior: Behavior[T], props: Props, ref: ActorRef[T]) extends Effect
217
  case class Stopped(name: String) extends Effect
218
  case class Watched[T](other: ActorRef[T]) extends Effect
219
  case class Unwatched[T](other: ActorRef[T]) extends Effect
220
  case class MessageSent[T](message: T, to: ActorRef[T]) extends Effect
221
  case class Scheduled[T](delay: FiniteDuration, target: ActorRef[T], message: T) extends Effect
222
  case object NoEffects extends Effect
223
  case object Stashed extends Effect
224
}
225
```
226

227
### Fishing Outcomes
228

229
```scala { .api }
230
sealed trait FishingOutcome
231

232
object FishingOutcome {
233
  case object Complete extends FishingOutcome
234
  case object Continue extends FishingOutcome
235
  case object ContinueAndIgnore extends FishingOutcome
236
  case class Fail(message: String) extends FishingOutcome
237
}
238

239
object FishingOutcomes {
240
  val complete: FishingOutcome
241
  val continue: FishingOutcome
242
  val continueAndIgnore: FishingOutcome
243
  def fail(message: String): FishingOutcome
244
}
245
```
246

247
### Test Inboxes
248

249
```scala { .api }
250
trait TestInbox[T] {
251
  def ref: ActorRef[T]
252
  def receiveMessage(): T
253
  def expectMessage(expectedMessage: T): T
254
  def hasMessages: Boolean
255
  def receiveAll(): immutable.Seq[T]
256
}
257

258
trait ReplyInbox[Res] {
259
  def receiveReply(): Res
260
  def expectReply(expectedReply: Res): Res
261
  def hasReply: Boolean
262
}
263
```