The ability to create and run automated tests is a fundamental tool of modern software development. By automating the testing process, developers can save valuable time and effort, enabling the detection of bugs and issues early in the development process. Additionally, it provides a safety net during frequent code changes and enhancements, helping to maintain the integrity and stability of the software.

In Kalix, you can create different types of automated tests: Unit, Integration and End-to-end Tests.

If you’re looking to do some capacity / performance testing on a real environment, reach us at kalix-support@lightbend.com.

Unit Tests

Unit Tests allow verifying that the smallest units of code work as expected in isolation. In Kalix, such tests can be of two shapes:

  • Using common test frameworks to test self-contained business logic that does not directly depend on Kalix features.

  • Testing Kalix components using the Kalix TestKit. For each different type of component (e.g. Value entities), the TestKit provides ways to make independent calls to the component and assert on the results and side-effects.


  • test that for a given Event Sourced Entity, if command A is received then event X is produced with Y property;

  • test that a given Action transforms and forwards a received command B to a specific entity Y;

  • test a given Action with a mocked interaction with a different Entity.

You can find specific documentation and examples on each component page in your SDK of choice (e.g. Java SDK > Value Entity > Testing the Entity).

Integration Tests

Integration tests examine the interaction between different components or modules of the software and validate that the integrated system functions as expected, uncovering issues that arise from the collaboration between various parts. To this goal, with the Kalix TestKit you can run the Kalix Runtime in a Docker container attached to the Kalix Service, allowing for testing business flows that span multiple Kalix components and might interact with real or mocked external data sources such as brokers or HTTP endpoints.

Since these tests require building and deploying a docker image as well as actual (local) networking, they depend on docker on the development machine. This also means they take a bit more time to execute compared to the unit tests which are completely local and do not involve networking.


  • test an Action subscribing to topic and sending commands to a value entity, using TestKit’s test broker;

  • test Kafka integration by consuming from real instance (externally managed) and forwarding commands to event sourced entity;

  • test a Workflow depending on a mocked external HTTP API.

You can find specific documentation and examples as the last of section of the corresponding component-specific page for a given SDK (e.g. Java SDK > Value Entity > Testing the Entity).

End-to-end Tests

End-to-end tests validate the entire system or application from start to finish, simulating real-world user scenarios. These tests mimic user interactions, typically spanning multiple modules or services, to verify that the system functions correctly as a whole. In Kalix, this could be a test that spans over multiple services belonging to the same project or even different projects. The concrete setup and ergonomics of running such tests are greatly dependent on the specific environment in which they are to be run. However, Kalix offers different configuration options that should be flexible enough to fit your use case.


  • test flow of data between 2 different Kalix services belonging to the same project using service-to-service eventing;

  • test business use case where 3 services from different projects interact over Kafka.

When building end-to-end tests, you might be required to use some configuration to allow different services to see each other. You can find specific documentation about this under section "Running a service locally" for a given SDK (e.g. Java SDK > Running a service locally).