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
```