This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/main by this push:
new 67a4e626470 chore(docs): Improve integration testing documentation
(#18883)
67a4e626470 is described below
commit 67a4e626470443cd3a9c06c63b42be53a5843ad5
Author: Christoph Deppisch <[email protected]>
AuthorDate: Tue Aug 12 19:23:13 2025 +0200
chore(docs): Improve integration testing documentation (#18883)
- Improve Camel JBang test plugin
- Reference Citrus & Apache Camel related docs
- Add basic integration testing docs
---
docs/user-manual/modules/ROOT/nav.adoc | 1 +
.../modules/ROOT/pages/camel-jbang-test.adoc | 78 ++++-----
.../modules/ROOT/pages/integration-test.adoc | 184 +++++++++++++++++++++
docs/user-manual/modules/ROOT/pages/testing.adoc | 44 ++++-
4 files changed, 266 insertions(+), 41 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/nav.adoc
b/docs/user-manual/modules/ROOT/nav.adoc
index 97a96702e3a..4fa8c1b0964 100644
--- a/docs/user-manual/modules/ROOT/nav.adoc
+++ b/docs/user-manual/modules/ROOT/nav.adoc
@@ -25,6 +25,7 @@
*** xref:test-infra.adoc[Test Infra]
*** xref:notify-builder.adoc[NotifyBuilder]
*** xref:advice-with.adoc[AdviceWith]
+*** xref:integration-test.adoc[Integration Test]
** xref:rest-dsl.adoc[Working with REST and Rest DSL]
*** xref:rest-dsl-openapi.adoc[Rest DSL contract first]
** xref:writing-components.adoc[Writing Components]
diff --git a/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc
b/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc
index 95c86493585..4eaf0324bee 100644
--- a/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc
+++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc
@@ -3,14 +3,6 @@
This plugin helps you to write automated tests with Camel JBang.
Please make sure to meet these prerequisites for running tests with Camel
JBang:
-* Install the https://citrusframework.org/[Citrus test framework] as a JBang
application
-
-[source,bash]
-----
-jbang trust add https://github.com/citrusframework/citrus/
-jbang app install citrus@citrusframework/citrus
-----
-
* Activate the Camel JBang test plugin
The Camel JBang Test functionality is provided as a command plugin.
@@ -93,35 +85,6 @@ Please refer to the help page of the `run` command for
options and details.
TIP: The Camel JBang plugin automatically creates a subfolder `test` and adds
the test source files into this folder.
This is a way to separate test scoped resources from Camel integration sources.
-== Dependency management
-
-The Citrus JBang tooling includes some basic dependencies out of the box, so
you are not required to add dependencies prior to running the test.
-In case you need to add a Citrus module that is not included by default you
can add this to a file called `jbang.properties`.
-
-TIP: The property file should be located right next to the test source file,
so JBang can find it automatically when running the test.
-
-.jbang.properties
-[source,properties]
-----
-# Declare required additional dependencies
-run.deps=org.citrusframework:citrus-camel:4.7.0,\
-org.citrusframework:citrus-kafka:4.7.0,\
-org.citrusframework:citrus-testcontainers:4.7.0,\
-org.apache.camel:camel-endpointdsl:4.13.0,\
-org.apache.camel:camel-aws2-s3:4.13.0
-
-# Enable dump of Camel JBang integration output
-run.D=citrus.camel.jbang.dump.integration.output=true
-----
-
-You can add dependencies in the form of Maven GAV style coordinates in the
`run.deps` property.
-JBang will automatically resolve the artifacts and add it to the runtime.
-
-The `jbang.properties` is a good place to add System properties for the Citrus
runtime.
-For instance, the setting `citrus.camel.jbang.dump.integration.output=true`
controls the output of the Camel integration and that it should be stored into
a file for later analysis.
-
-TIP: During the project export the dependencies listed in `jbang.properties`
will be added to the Maven POM as test-scoped dependencies.
-
== Project export
Once you are happy with the Camel integration and the automated test you may
want to export these files into a project for further usage after the
prototyping phase.
@@ -153,11 +116,52 @@ Now the automated tests from the prototyping phase with
Camel JBang are part of
TIP: The project export has created a Java unit test (in `src/test/java`) that
runs the test. You can also run the test from your Java IDE with this class. By
default, the export uses JUnit Jupiter as a test engine.
+== Dependency management
+
+The test plugin is based on the Java test framework
https://citrusframework.org/[Citrus].
+It uses commands and modules provided by Citrus to run the tests.
+In fact the Camel test plugin calls Citrus as another JBang command.
+
+The Citrus JBang tooling includes some basic dependencies out of the box, so
you are not required to add dependencies prior to running the test.
+In case you need to add a Citrus module that is not included by default (e.g.
support for Kafka or Testcontainers) you can add the additional dependencies to
a file called `jbang.properties`.
+
+TIP: The property file should be located right next to the test source file,
so JBang can find it automatically when running the test.
+
+.jbang.properties
+[source,properties]
+----
+# Declare required additional dependencies
+run.deps=org.citrusframework:citrus-camel:4.7.0,\
+org.citrusframework:citrus-kafka:4.7.0,\
+org.citrusframework:citrus-testcontainers:4.7.0,\
+org.apache.camel:camel-endpointdsl:4.13.0,\
+org.apache.camel:camel-aws2-s3:4.13.0
+
+# Enable dump of Camel JBang integration output
+run.D=citrus.camel.jbang.dump.integration.output=true
+----
+
+You can add dependencies in the form of Maven GAV style coordinates in the
`run.deps` property.
+JBang will automatically resolve the artifacts and add it to the runtime.
+
+The `jbang.properties` is a good place to add System properties for the Citrus
runtime.
+For instance, the setting `citrus.camel.jbang.dump.integration.output=true`
controls the output of the Camel integration and that it should be stored into
a file for later analysis.
+
+TIP: During the project export the dependencies listed in `jbang.properties`
will be added to the Maven POM as test-scoped dependencies.
+
== Explore test capabilities
The test plugin uses https://citrusframework.org/[Citrus] as an underlying
test framework.
Citrus is an Open Source Java test framework that integrates very well with
Apache Camel as it provides special test actions to use Camel JBang for
instance.
+You can also install the https://citrusframework.org/[Citrus test framework]
JBang application to explore the full capabilities.
+
+[source,bash]
+----
+jbang trust add https://github.com/citrusframework/citrus/
+jbang app install citrus@citrusframework/citrus
+----
+
Usually an automated test of a Camel integration needs to perform these high
level steps:
* Create and prepare required test infrastructure (e.g. start a Kafka message
broker, prepare a database)
diff --git a/docs/user-manual/modules/ROOT/pages/integration-test.adoc
b/docs/user-manual/modules/ROOT/pages/integration-test.adoc
new file mode 100644
index 00000000000..8942a9daf51
--- /dev/null
+++ b/docs/user-manual/modules/ROOT/pages/integration-test.adoc
@@ -0,0 +1,184 @@
+= Integration Test
+
+The integration test is a special form of testing where you usually start a
complete Apache Camel application to verify its interaction with other
components and services.
+
+A typical integration test scenario verifies the collaboration of services and
their integration with each other. Usually this includes infrastructure in
particular data persistence layers, message brokers or 3rd party services.
+
+NOTE: Both unit testing and integration testing are essential in software
development to ensure the functionality and the compatibility with integrated
services. The combination of both results in a successful quality assurance of
your Camel application.
+
+== 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.
+
+=== Quarkus Test support
+
+When writing applications with Quarkus you will most likely use the
`@QuarkusTest` or `@QuarkusIntegrationTest` annotated JUnit Jupiter classes.
+You can continue to use this in combination with Citrus in order to write
automated integration tests for your application.
+
+The following example uses the Citrus Quarkus extension in a Quarkus test:
+
+[source,java]
+----
+@QuarkusTest
+@CitrusSupport
+public class CamelDemoApplicationIT implements TestActionSupport {
+
+ @BindToRegistry
+ private final HttpClient httpClient = HttpEndpoints.http()
+ .client()
+ .requestUrl("http://localhost:8081";)
+ .build();
+
+ @BindToRegistry
+ private final KafkaEndpoint completed = new KafkaEndpointBuilder()
+ .topic("completed")
+ .build();
+
+ @CitrusResource
+ private TestCaseRunner t;
+
+ @Test
+ void shouldVerifyDemoApp() {
+ t.given(
+ http().client(httpClient)
+ .send()
+ .post("/bookings")
+ .message()
+ .body(Resources.fromClasspath("booking.json"))
+ );
+
+ t.when(
+ http().client(httpClient)
+ .receive()
+ .response(HttpStatus.OK)
+ );
+
+ t.then(
+ receive().endpoint(completed)
+ .message()
+ .body("Booking complete!")
+ );
+ }
+}
+----
+
+Citrus comes with a Quarkus extension that provides the `@CitrusSupport`
annotation.
+Once added to your test class the test is able to use the Citrus endpoint
components as well as the Java domain specific language for writing integration
tests.
+
+The example above uses the normal `@QuarkusTest` annotation to start the Camel
application.
+Then the test then uses Citrus endpoints to interact with the exposed Http
service and invokes an endpoint `/bookings` with a given `booking.json` payload.
+The expected result is a 200 OK response as well as an event message on the
Kafka topic `completed`.
+Both response and event content is verified with an expected message content
(e.g. Http status 200 OK).
+
+NOTE: The class names that represent integration tests use the suffix `*IT`.
This is a common design principle in order to separate normal unit tests and
integration tests. Unit tests usually use the `*Test` name suffix. The Maven
build lifecycle is able to separate the test categories by their names so the
Maven `surefire` plugin is able to run unit tests in the `test` lifecycle phase
while the Maven `failsafe` plugin runs integration tests in the
`integration-test` Maven lifecycle phase.
+
+TIP: Always make sure to use one of the naming patterns for unit or
integration tests, so Maven is able to find and execute your tests in the
respective build lifecycle phase.
+
+=== Spring Boot support
+
+You can use Citrus in your Spring Boot tests very easily to interact with the
Apache Camel routes started as part of the Spring Boot application.
+
+The following example uses the Citrus Quarkus extension in a Quarkus test:
+
+[source,java]
+----
+@SpringBootTest(classes = CamelDemoApplication.class, webEnvironment =
SpringBootTest.WebEnvironment.DEFINED_PORT)
+@CitrusSpringSupport
+@ContextConfiguration(classes = { CitrusEndpointConfig.class })
+public class CamelDemoApplicationIT implements TestActionSupport {
+
+ @Autowired
+ private HttpClient httpClient;
+
+ @Autowired
+ private KafkaEndpoint completed;
+
+ @CitrusResource
+ private TestCaseRunner t;
+
+ @Test
+ void shouldVerifyDemoApp() {
+ t.given(
+ http().client(httpClient)
+ .send()
+ .post("/bookings")
+ .message()
+ .body(Resources.fromClasspath("booking.json"))
+ );
+
+ t.when(
+ http().client(httpClient)
+ .receive()
+ .response(HttpStatus.OK)
+ );
+
+ t.then(
+ receive().endpoint(completed)
+ .message()
+ .body("Booking complete!")
+ );
+ }
+}
+----
+
+Citrus comes with a Spring integration which means that you can declare Citrus
endpoints as Spring beans.
+The Citrus Spring support is enabled on the test with the
`@CitrusSpringSupport` JUnit annotation.
+
+Once added to your test class the test is able to use the Citrus endpoint
components as well as the Java domain specific language for writing integration
tests.
+
+The example above uses the normal `@SpringBootTest` annotation to start the
Camel application.
+Then the test then uses autowired Citrus endpoints to interact with the
exposed Http service and invokes an endpoint `/bookings` with a given
`booking.json` payload.
+The expected result is a 200 OK response as well as an event message on the
Kafka topic `completed`.
+Both response and event content is verified with an expected message content
(e.g. Http status 200 OK).
+
+The Citrus endpoint beans are defined in a Spring configuration class
`CitrusEndpointConfig`.
+
+[source,java]
+----
+@Configuration
+@Import(CitrusSpringConfig.class)
+public class CitrusEndpointConfig {
+
+ @Bean
+ public HttpClient httpClient() {
+ return http().client()
+ .requestUrl("http://localhost:8080";)
+ .build();
+ }
+
+ @Bean
+ public KafkaEndpoint completed() {
+ return kafka()
+ .topic("completed")
+ .build();
+ }
+}
+----
+
+NOTE: The class names that represent integration tests use the suffix `*IT`.
This is a common design principle in order to separate normal unit tests and
integration tests. Unit tests usually use the `*Test` name suffix. The Maven
build lifecycle is able to separate the test categories by their names so the
Maven `surefire` plugin is able to run unit tests in the `test` lifecycle phase
while the Maven `failsafe` plugin runs integration tests in the
`integration-test` Maven lifecycle phase.
+
+TIP: Always make sure to use one of the naming patterns for unit or
integration tests, so Maven is able to find and execute your tests in the
respective build lifecycle phase.
diff --git a/docs/user-manual/modules/ROOT/pages/testing.adoc
b/docs/user-manual/modules/ROOT/pages/testing.adoc
index b094a90d9b5..8996181acc6 100644
--- a/docs/user-manual/modules/ROOT/pages/testing.adoc
+++ b/docs/user-manual/modules/ROOT/pages/testing.adoc
@@ -28,6 +28,8 @@ class for all your configuration and routing without.
|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
@@ -110,13 +112,47 @@ For example, you can send (or send and skip) a message to
a xref:components::moc
endpoint for validating the message send by Camel is as expected.
|=======================================================================
-=== Third Party Testing libraries
+== 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.
+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 Framework] | Framework for
automated integration tests supporting a wide range of message protocols and
data formats
-| https://citrusframework.org/yaks/[Citrus Yaks] | YAKS is a framework to
enable Cloud Native BDD testing on Kubernetes
+| 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.
