0
# Akka TestKit
1

2
A comprehensive testing toolkit specifically designed for testing Actor-based systems built with the Akka framework. It provides utilities and abstractions that make it easier to write unit and integration tests for actors, including features for testing actor messaging, FSM actors, event filtering, synchronization, time-controlled testing, and both synchronous and asynchronous testing patterns. The toolkit includes specialized components for message expectations, direct actor access, event filtering, synchronization primitives, custom dispatchers, and comprehensive Java interoperability.
3

4
## Package Information
5

6
- **Package Name**: akka-testkit_2.13
7
- **Language**: Scala
8
- **Package Type**: Maven
9
- **Installation**: 
10
  ```scala
11
  // sbt
12
  libraryDependencies += "com.typesafe.akka" %% "akka-testkit" % "2.8.8" % Test
13
  
14
  // Maven
15
  <dependency>
16
    <groupId>com.typesafe.akka</groupId>
17
    <artifactId>akka-testkit_2.13</artifactId>
18
    <version>2.8.8</version>
19
    <scope>test</scope>
20
  </dependency>
21
  ```
22

23
## Core Imports
24

25
```scala
26
import akka.testkit._
27
import akka.actor.{ActorSystem, Props}
28
import scala.concurrent.duration._
29
```
30

31
For Java DSL:
32
```scala
33
import akka.testkit.javadsl.TestKit
34
```
35

36
## Basic Usage
37

38
```scala
39
import akka.actor.{Actor, ActorSystem, Props}
40
import akka.testkit.{TestKit, ImplicitSender}
41
import org.scalatest.{BeforeAndAfterAll, Matchers, WordSpecLike}
42
import scala.concurrent.duration._
43

44
// Simple actor for testing
45
class EchoActor extends Actor {
46
  def receive = {
47
    case msg => sender() ! msg
48
  }
49
}
50

51
// Test class extending TestKit
52
class EchoActorSpec extends TestKit(ActorSystem("TestSystem"))
53
  with ImplicitSender
54
  with WordSpecLike
55
  with Matchers
56
  with BeforeAndAfterAll {
57

58
  override def afterAll(): Unit = {
59
    TestKit.shutdownActorSystem(system)
60
  }
61

62
  "An EchoActor" must {
63
    "reply with the same message" in {
64
      val echoActor = system.actorOf(Props[EchoActor]())
65
      echoActor ! "hello"
66
      expectMsg("hello")
67
    }
68
    
69
    "handle multiple messages" in {
70
      val echoActor = system.actorOf(Props[EchoActor]())
71
      echoActor ! "first"
72
      echoActor ! "second"
73
      expectMsg("first")
74
      expectMsg("second")
75
    }
76
  }
77
}
78
```
79

80
## Architecture
81

82
The Akka TestKit provides a layered testing architecture:
83

84
- **TestKit/TestProbe**: Main testing classes providing comprehensive message expectations, timeouts, and assertion methods
85
- **TestActorRef/TestFSMRef**: Direct access to actor instances and FSM states for unit testing
86
- **Event Filtering**: Complete logging interception system including dead letter filtering
87
- **Synchronization Tools**: Thread-safe barriers and latches for multi-threaded test coordination
88
- **Custom Dispatchers/Schedulers**: Deterministic execution environments with manual time control
89
- **Test Utilities**: Pre-built actors, socket utilities, and serialization helpers
90
- **Java DSL**: Complete Java API with functional interface support
91

92
This architecture supports both unit testing (direct actor access) and integration testing (message-based interactions), enabling comprehensive verification of actor behavior, supervision hierarchies, and distributed system properties.
93

94
## Capabilities
95

96
### Core Testing Framework
97

98
The primary TestKit class and related components for testing actor message interactions, including expectation methods, timeouts, and basic actor lifecycle testing.
99

100
```scala { .api }
101
class TestKit(system: ActorSystem)
102
trait TestKitBase
103
class TestProbe()(implicit system: ActorSystem)
104
trait ImplicitSender
105
trait DefaultTimeout
106
```
107

108
[Core Testing Framework](./core-testing.md)
109

110
### Actor References and Direct Testing
111

112
Specialized actor references that provide direct access to actor internals and state, enabling unit testing of actor behavior without message passing.
113

114
```scala { .api }
115
class TestActorRef[T <: Actor](props: Props)(implicit system: ActorSystem)
116
class TestFSMRef[S, D, T <: Actor](props: Props)(implicit system: ActorSystem)
117
object TestActorRef
118
object TestFSMRef
119
```
120

121
[Actor References and Direct Testing](./actor-refs.md)
122

123
### Event Filtering and Logging
124

125
Comprehensive system for intercepting and validating log events and exceptions during testing, allowing tests to assert expected logging behavior.
126

127
```scala { .api }
128
abstract class EventFilter
129
object EventFilter
130
class ErrorFilter extends EventFilter
131
class WarningFilter extends EventFilter
132
class InfoFilter extends EventFilter
133
class DebugFilter extends EventFilter
134
```
135

136
[Event Filtering and Logging](./event-filtering.md)
137

138
### Test Actors and Utilities
139

140
Pre-built actor implementations and factory methods for common testing patterns, including echo actors, blackhole actors, and message forwarding actors.
141

142
```scala { .api }
143
object TestActors
144
class EchoActor extends Actor
145
class BlackholeActor extends Actor  
146
class ForwardActor(ref: ActorRef) extends Actor
147
```
148

149
[Test Actors and Utilities](./test-actors.md)
150

151
### Synchronization Utilities
152

153
Thread-safe synchronization primitives for coordinating multi-threaded tests and ensuring deterministic test execution across concurrent operations.
154

155
```scala { .api }
156
class TestBarrier(count: Int)
157
class TestLatch(count: Int = 1)
158
```
159

160
[Synchronization Utilities](./synchronization.md)
161

162
### Custom Dispatchers and Scheduling
163

164
Specialized dispatchers and schedulers that provide deterministic execution environments for testing, including single-threaded execution and manual time advancement.
165

166
```scala { .api }
167
class CallingThreadDispatcher
168
class ExplicitlyTriggeredScheduler
169
```
170

171
[Custom Dispatchers and Scheduling](./dispatchers.md)
172

173
### Configuration and Extensions
174

175
TestKit configuration system and Akka extensions for customizing test behavior, timeouts, and environment settings.
176

177
```scala { .api }
178
object TestKitExtension extends ExtensionId[TestKitSettings]
179
class TestKitSettings(config: Config)
180
```
181

182
[Configuration and Extensions](./configuration.md)
183

184
### Helper Utilities
185

186
Additional utility functions and classes for common testing scenarios, including socket utilities, test exceptions, and serialization helpers.
187

188
```scala { .api }
189
object SocketUtil
190
case class TestException(message: String) extends RuntimeException
191
class TestJavaSerializer
192
trait JavaSerializable
193
```
194

195
[Helper Utilities](./utilities.md)
196

197
### Java DSL
198

199
Complete Java API providing equivalent functionality to the Scala API with Java-friendly method signatures and type usage.
200

201
```scala { .api }
202
class akka.testkit.javadsl.TestKit(system: ActorSystem)
203
class akka.testkit.javadsl.EventFilter
204
```
205

206
[Java DSL](./java-dsl.md)
207

208
### Package-Level Functions
209

210
Global utility functions and implicit classes available at the package level for common testing operations and time dilation.
211

212
```scala { .api }
213
def filterEvents[T](eventFilters: EventFilter*)(block: => T)(implicit system: ActorSystem): T
214
def filterException[T <: Throwable](block: => Unit)(implicit system: ActorSystem, t: ClassTag[T]): Unit
215
implicit class TestDuration(duration: FiniteDuration)
216
```
217

218
[Package-Level Functions](./package-functions.md)