docs/user-manual/modules/ROOT/pages/testing.adoc

= Testing

Testing is a crucial activity in any piece of software development or
integration. Typically, Camel users would use various different
technologies wired together in a variety of EIPs with different
endpoints, languages, bean integration, and
dependency injection, so it's easy for things to go wrong!
Testing is the crucial weapon to ensure that things work as you would expect.

Camel is a Java library, so you can easily wire up tests in JUnit.
However, the Camel project has tried to make the testing of Camel as easy
and powerful as possible, so we have introduced the following features.

== Testing modules

The following modules are supported:

[width="100%",cols="1m,4",options="header",]
|=======================================================================
|Component |Description

|xref:components:others:test-junit5.adoc[camel-test-junit5] |*JUnit 5*: Is an older standalone Java
library letting you easily create Camel test cases using a single Java
class for all your configuration and routing without.
|xref:components:others:test-main-junit5.adoc[camel-test-main-junit5] | *JUnit 5*: Used for testing Camel in Camel Main mode

|xref:components:others:test-spring-junit5.adoc[camel-test-spring-junit5] | *JUnit 5*: Used for testing Camel with Spring / Spring Boot

|xref:test-infra.adoc[camel-test-infra] | *Camel Test Infra*: Camel Test Infra is a set of modules that leverage modern JUnit 5 features to abstract the provisioning and execution of test infrastructure. Among other things, it provides abstraction of the infrastructure (based on Test Containers - being the de-facto successor of the camel-testcontainers components) as well as JUnit 5 extensions for the Camel Context itself.

|xref:camel-jbang-test.adoc[camel-jbang-test] | *Camel JBang Test Plugin*: A Camel JBang plugin to help writing automated tests during prototyping with JBang. The tests are able to start the Camel integration and verify its logic from the very beginning. The test plugin does not require any project setup so you can just start writing and executing automated tests.

|=======================================================================

NOTE: If you are using Camel Quarkus, then you can find information in
its documentation how to do testing with Quarkus and Camel.

In all approaches, the test classes look pretty much the same in that
they all reuse the xref:bean-integration.adoc[Camel binding and
injection annotations].

TIP: For more details on the different testing modules, then see their respective documentation
from the links in the table above.

== Testing functionality

Camel provides a set of features that are common to use when writing unit or integration tests with Camel.

=== Testing endpoints

Camel provides a number of xref:endpoint.adoc[endpoints] which can make testing easier.

[width="100%",cols="1,3",options="header",]
|=======================================================================
|Name |Description
|xref:components::mock-component.adoc[Mock] |For testing routes and mediation rules using
mocks and allowing assertions to be added to an endpoint.

|xref:components::dataset-component.adoc[DataSet] |For load & soak testing, this endpoint
provides a way to create huge numbers of messages for sending to
components and asserting that they are consumed correctly.

|xref:components::dataset-test-component.adoc[DataSet Test] |Used to automatically load
a set of expected messages from another endpoint which is then compared to the messages
that arrive at this endpoint.

|=======================================================================

The main endpoint is the xref:components::mock-component.adoc[Mock] endpoint, which allows
expectations to be added to different endpoints; you can then run your
tests and assert that your expectations are met at the end.

=== Stubbing out physical transport technologies

If you wish to test out a route but want to avoid actually using real physical transport, then the following
endpoints can be useful:

NOTE: For example, to unit test a transformation route rather than performing a full integration test

[width="100%",cols="1,3",options="header",]
|=======================================================================
|Name |Description
|xref:components::direct-component.adoc[Direct] |Direct invocation of the consumer from the
producer so that single threaded (non-SEDA) in VM invocation is
performed which can be useful to mock out physical transports

|xref:components::seda-component.adoc[SEDA] |Deliver messages asynchronously to consumers via
a `BlockingQueue` which is good for testing asynchronous transports

|xref:components::stub-component.adoc[Stub] |Works like xref:components::stub-component.adoc[SEDA] but does not
validate the endpoint URI, which makes stubbing straightforward.
|=======================================================================

=== Testing existing routes

Camel provides some features to aid during testing of existing routes
where you cannot or will not use xref:components::mock-component.adoc[Mock] etc.
For example, you may have a production ready route which you want to test with some
third party API that sends messages into this route.

[width="100%",cols="1,3",options="header",]
|=======================================================================
|Name |Description
|xref:notify-builder.adoc[NotifyBuilder] |Allows you to be notified when
a certain condition has occurred. For example, when the route has
completed five messages. You can build complex expressions to match your
criteria when to be notified.

|xref:advice-with.adoc[AdviceWith] |Allows you to _advice_ (enhance)
an existing route using a xref:route-builder.adoc[RouteBuilder] style.
For example, you can send (or send and skip) a message to a xref:components::mock-component.adoc[Mock]
endpoint for validating the message send by Camel is as expected.
|=======================================================================

== Integration testing

The purpose of integration testing is to verify a whole component or service with its integration to other components, infrastructure and services.

Usually the integration tests start the Camel application as a whole and include test infrastructure such as message brokers, data persistence and 3rd party services that interact with the Camel application.

See this chapter about xref:integration-test.adoc[integration testing] for details and how to master common integration testing challenges.

There are a number of third party testing libraries that Camel users have found useful especially when it comes to integration testing.

[width="100%",cols="1,3",options="header",]
|=======================================================================
|Name |Description
| https://citrusframework.org/[Citrus Integration Testing] | Framework for automated integration tests supporting a wide range of message protocols and data formats
| https://citrusframework.org/yaks/[YAKS] | YAKS is a framework based on Citrus to enable Cloud Native BDD testing on Kubernetes
|=======================================================================

=== Citrus test framework

As an example of writing integration tests for Camel applications you can use the
https://citfrusframework.org[Citrus] test framework.
Citrus is an Open Source Java testing framework with focus on integration testing and messaging.

The framework provides a very good integration with Apache Camel.
Citrus helps you to write automated integration tests with a proper preparation of test infrastructure and connects with the exposed services to verify the Camel application with powerful message validation capabilities for different message data formats (e.g. XML, Json, YAML, plaintext).

Please refer to the https://citrusframework.org/citrus/reference/html/[Citrus documentation] to find out how to write automated tests for Apache Camel applications.
The following sections might be interesting to explore for Camel developers and testers:

[width="100%",cols="1,3",options="header",]
|=======================================================================
|Name |Description
| https://citrusframework.org/citrus/reference/html/#apache-camel[Citrus & Camel routes] | Start and stop Camel routes as part of the test.
| https://citrusframework.org/citrus/reference/html/#camel-infra[Citrus & Camel test infra] | Start and stop Camel test infrastructure services as part of the Citrus test.
| https://citrusframework.org/citrus/reference/html/#camel-processor-support[Citrus & Camel processors] | Use Camel processor, transformer and data format EIPs in Citrus tests.
| https://citrusframework.org/citrus/reference/html/#apache-camel[Citrus & Camel JBang] | Run Camel integrations with JBang as part of a test.
|=======================================================================

TIP: Citrus provides a good integration with https://www.jbang.dev[JBang] and Camel JBang.
This means you can use Citrus from the very beginning for writing automated tests also in the prototyping phase with Camel JBang.
Read about it in the chapter xref:camel-jbang-test.adoc[Camel JBang test plugin].

Citrus integrates with Quarkus and Spring Boot so you can write the tests on top of known concepts and libraries.
You can choose from a set of supported test engines such as JUnit Jupiter to run the tests as part of the build lifecycle or from your favorite IDE.