0
# Akka TestKit
1

2
Akka TestKit is a comprehensive testing toolkit designed specifically for testing Actor-based systems built with the Akka framework. It provides essential utilities for testing asynchronous, concurrent actor behaviors including TestActorRef for synchronous testing of actor internals, TestKit base class with assertion helpers and timing utilities, TestProbe for creating controllable mock actors, EventFilter for testing logging and exception scenarios, and CallingThreadDispatcher for deterministic single-threaded testing.
3

4
## Package Information
5

6
- **Package Name**: akka-testkit
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "com.typesafe.akka" %% "akka-testkit" % "2.8.8" % Test`
10

11
## Core Imports
12

13
```scala
14
import akka.testkit._
15
import akka.actor.{ActorSystem, ActorRef, Props}
16
import scala.concurrent.duration._
17
```
18

19
For specific components:
20

21
```scala
22
import akka.testkit.{TestKit, TestProbe, TestActorRef, ImplicitSender}
23
import akka.testkit.{EventFilter, TestFSMRef, TestLatch, TestBarrier}
24
```
25

26
## Basic Usage
27

28
```scala
29
import akka.actor.{Actor, ActorSystem, Props}
30
import akka.testkit.{TestKit, ImplicitSender}
31
import org.scalatest.BeforeAndAfterAll
32
import org.scalatest.wordspec.AnyWordSpecLike
33
import scala.concurrent.duration._
34

35
class MyActorSpec extends TestKit(ActorSystem("test-system"))
36
  with AnyWordSpecLike
37
  with ImplicitSender
38
  with BeforeAndAfterAll {
39

40
  override def afterAll(): Unit = {
41
    TestKit.shutdownActorSystem(system)
42
  }
43

44
  "MyActor" should {
45
    "respond with pong when pinged" in {
46
      val myActor = system.actorOf(Props[MyActor])
47
      myActor ! "ping"
48
      expectMsg(5.seconds, "pong")
49
    }
50
  }
51
}
52

53
class MyActor extends Actor {
54
  def receive = {
55
    case "ping" => sender() ! "pong"
56
  }
57
}
58
```
59

60
## Architecture
61

62
Akka TestKit is built around several key components:
63

64
- **TestKit Base Class**: Core testing functionality with message expectations, timing control, and actor lifecycle management
65
- **TestProbe**: Lightweight actors for controlled message sending and receiving in tests
66
- **TestActorRef**: Synchronous actor references for direct access to actor internals
67
- **Event Filtering**: System for intercepting and asserting on log events and exceptions
68
- **Synchronization Utilities**: Latches and barriers for coordinating concurrent test scenarios
69
- **Deterministic Execution**: Special dispatchers and schedulers for predictable test execution
70

71
## Capabilities
72

73
### Core Testing Framework
74

75
The main TestKit class and related testing utilities for Actor system testing with message expectations, timing assertions, and actor lifecycle management.
76

77
```scala { .api }
78
abstract class TestKitBase extends TestKitUtils {
79
  def expectMsg[T](obj: T): T
80
  def expectMsg[T](max: FiniteDuration, obj: T): T
81
  def expectMsgType[T](implicit t: ClassTag[T]): T
82
  def expectNoMessage(): Unit
83
  def expectNoMessage(max: FiniteDuration): Unit
84
  def receiveN(n: Int): immutable.Seq[AnyRef]
85
  def receiveOne(max: Duration): AnyRef
86
  def within[T](max: FiniteDuration)(f: => T): T
87
  def awaitCond(p: => Boolean, max: Duration, interval: Duration, message: String): Unit
88
  def watch(ref: ActorRef): ActorRef
89
  def testActor: ActorRef
90
  def lastSender: ActorRef
91
}
92

93
class TestKit(_system: ActorSystem) extends TestKitBase
94

95
class TestProbe(_application: ActorSystem, name: String) extends TestKit(_application) {
96
  def send(actor: ActorRef, msg: Any): Unit
97
  def reply(msg: Any): Unit
98
  def ref: ActorRef
99
}
100
```
101

102
[Core Testing Framework](./core-testing.md)
103

104
### Synchronous Actor Testing
105

106
TestActorRef for direct access to actor internals and synchronous testing without the actor model's asynchronous nature.
107

108
```scala { .api }  
109
class TestActorRef[T <: Actor](_system: ActorSystem, _props: Props, _supervisor: ActorRef, name: String) 
110
  extends LocalActorRef {
111
  def underlyingActor: T
112
  def receive(o: Any): Unit
113
  def receive(o: Any, sender: ActorRef): Unit
114
}
115

116
object TestActorRef {
117
  def apply[T <: Actor: ClassTag](factory: => T)(implicit system: ActorSystem): TestActorRef[T]
118
  def apply[T <: Actor](props: Props)(implicit system: ActorSystem): TestActorRef[T]
119
}
120
```
121

122
[Synchronous Actor Testing](./synchronous-testing.md)
123

124
### FSM Testing
125

126
Specialized testing utilities for Finite State Machine actors with state inspection and timer management.
127

128
```scala { .api }
129
class TestFSMRef[S, D, T <: Actor](system: ActorSystem, props: Props, supervisor: ActorRef, name: String) 
130
  extends TestActorRef[T] {
131
  def stateName: S
132
  def stateData: D
133
  def setState(stateName: S, stateData: D): Unit
134
  def startTimerWithFixedDelay(name: String, msg: Any, delay: FiniteDuration): Unit
135
  def isTimerActive(name: String): Boolean
136
}
137
```
138

139
[FSM Testing](./fsm-testing.md)
140

141
### Event Filtering and Logging
142

143
System for intercepting, filtering, and asserting on log events, exceptions, and dead letters during tests.
144

145
```scala { .api }
146
abstract class EventFilter {
147
  def intercept[T](code: => T)(implicit system: ActorSystem): T
148
  def awaitDone(max: Duration): Boolean
149
}
150

151
object EventFilter {
152
  def apply[A <: Throwable: ClassTag](
153
    message: String = "",
154
    source: String = "",
155
    start: String = "",
156
    pattern: String = "",
157
    occurrences: Int = 1
158
  ): EventFilter
159
  
160
  def error(message: String = "", occurrences: Int = 1): EventFilter
161
  def warning(message: String = "", occurrences: Int = 1): EventFilter
162
  def info(message: String = "", occurrences: Int = 1): EventFilter
163
  def debug(message: String = "", occurrences: Int = 1): EventFilter
164
}
165
```
166

167
[Event Filtering and Logging](./event-filtering.md)
168

169
### Synchronization Utilities
170

171
Utilities for coordinating concurrent test scenarios including countdown latches and cyclic barriers.
172

173
```scala { .api }
174
class TestLatch(count: Int = 1)(implicit system: ActorSystem) {
175
  def countDown(): Unit
176
  def isOpen: Boolean
177
  def open(): Unit
178
  def reset(): Unit
179
  def ready(atMost: Duration)(implicit permit: CanAwait): TestLatch
180
}
181

182
class TestBarrier(count: Int) {
183
  def await()(implicit system: ActorSystem): Unit
184
  def await(timeout: FiniteDuration)(implicit system: ActorSystem): Unit
185
  def reset(): Unit
186
}
187
```
188

189
[Synchronization Utilities](./synchronization.md)
190

191
### Deterministic Execution Control
192

193
Specialized dispatchers and schedulers for predictable, deterministic test execution and timing control.
194

195
```scala { .api }
196
class CallingThreadDispatcher extends MessageDispatcher {
197
  // Executes messages on the calling thread for deterministic execution
198
}
199

200
class ExplicitlyTriggeredScheduler extends Scheduler {
201
  def timePasses(amount: FiniteDuration): Unit
202
  def currentTimeMs: Long
203
}
204
```
205

206
[Deterministic Execution Control](./deterministic-execution.md)
207

208
### Test Utilities and Helpers
209

210
Utility classes, actors, and functions for common testing patterns and network testing.
211

212
```scala { .api }
213
object TestActors {
214
  val echoActorProps: Props
215
  val blackholeProps: Props
216
  def forwardActorProps(ref: ActorRef): Props
217
}
218

219
object SocketUtil {
220
  def temporaryLocalPort(udp: Boolean = false): Int
221
  def temporaryServerAddress(address: String, udp: Boolean): InetSocketAddress
222
}
223

224
case class TestException(message: String) extends RuntimeException with NoStackTrace
225
```
226

227
[Test Utilities and Helpers](./test-utilities.md)
228

229
## Types
230

231
```scala { .api }
232
// Core testing types
233
trait TestKitBase {
234
  implicit def testKitSettings: TestKitSettings
235
  def testActor: ActorRef
236
  def system: ActorSystem
237
}
238

239
// AutoPilot system for automatic message handling
240
abstract class AutoPilot {
241
  def run(sender: ActorRef, msg: Any): AutoPilot
242
}
243

244
case object NoAutoPilot extends AutoPilot
245
case object KeepRunning extends AutoPilot
246

247
// Configuration settings
248
class TestKitSettings(config: Config) {
249
  val TestTimeFactor: Double
250
  val SingleExpectDefaultTimeout: FiniteDuration
251
  val ExpectNoMessageDefaultTimeout: FiniteDuration
252
  val TestEventFilterLeeway: FiniteDuration
253
  val DefaultTimeout: Timeout
254
}
255

256
// Implicit traits for common patterns
257
trait ImplicitSender extends TestKitBase {
258
  implicit def self: ActorRef = testActor
259
}
260

261
trait DefaultTimeout extends TestKitBase {
262
  implicit val timeout: Timeout = testKitSettings.DefaultTimeout
263
}
264

265
// Time dilation for test scenarios
266
implicit class TestDuration(val duration: FiniteDuration) extends AnyVal {
267
  def dilated(implicit system: ActorSystem): FiniteDuration
268
}
269
```