This is an automated email from the ASF dual-hosted git repository. davsclaus pushed a commit to branch feature/CAMEL-23722-cli-docs-restructure in repository https://gitbox.apache.org/repos/asf/camel.git
commit 048e8bf4525b6889bbfc809a25135e46e251786a Author: Claus Ibsen <[email protected]> AuthorDate: Tue Jun 9 20:00:58 2026 +0200 CAMEL-23722: Tighten Testing Plugin page prose (353 -> 158 lines) Co-Authored-By: Claude <[email protected]> Signed-off-by: Claus Ibsen <[email protected]> --- .../modules/ROOT/pages/camel-jbang-test.adoc | 265 +++------------------ 1 file changed, 35 insertions(+), 230 deletions(-) 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 fb66393c5c48..e0a474f48f2c 100644 --- a/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc +++ b/docs/user-manual/modules/ROOT/pages/camel-jbang-test.adoc @@ -1,184 +1,84 @@ = Camel Testing plugin -This plugin helps you to write automated tests with Camel CLI. -Please make sure to meet these prerequisites for running tests with Camel CLI: +Write and run automated tests for Camel integrations using the https://citrusframework.org/[Citrus] test framework. -* Activate the Camel CLI test plugin - -The Camel CLI Test functionality is provided as a command plugin. -This means you need to enable the `test` plugin first to use the subcommands in Camel CLI. +Enable the plugin: [source,bash] ---- camel plugin add test ---- -You should see the `test` plugin listed as an installed plugin. - -[source,bash] ----- -camel plugin get ----- - -[source,bash] ----- - NAME COMMAND DEPENDENCY DESCRIPTION - test test org.apache.camel:camel-jbang-plugin-test Manage tests for Camel applications ----- - -Now Camel CLI is able to run the subcommands offered by the plugin. -You can inspect the help page to see the list of available plugin subcommands. - -[source,bash] ----- -camel test --help ----- - -You will see the list of available subcommands for this plugin. +TIP: Run `camel test --help` to see all available subcommands. == Initialize tests -The plugin helps you to create automated tests for your Camel integration. - -The `init` command creates an empty test file that you can use as a starting point. +Create an empty test file as a starting point: [source,bash] ---- camel test init route-test.yaml ---- -The command creates an empty test that uses the given test specification language derived from the file name extension. -In the example above the test uses YAML as a domain specific language. - -The plugin supports the following languages to write automated tests: - -* YAML -* Java -* XML -* Cucumber (.feature file extension) +The file extension determines the test language: YAML, Java, XML, or Cucumber (`.feature`). -Whatever language you choose, the result will be a new file that represents the test. - -NOTE: The plugin automatically uses a `test` subfolder to create and run tests. This is because it is a good design to separate test-scoped and runtime source files. - -TIP: You do not need to navigate to the `test` subfolder when running the test. The plugin will automatically set the proper working directory for you so you do not have to switch folders all the time. - -You can directly run the test and start implementing the test logic. +NOTE: Tests are created in a `test` subfolder to separate them from runtime sources. You don't need to navigate there — the plugin handles the working directory automatically. == Run tests -The test plugin helps you to run the tests with JBang. -As usual, there is no need to create a project or set-up dependencies for that. -Camel CLI just runs the test locally. +Run tests locally with JUnit Jupiter — no project setup needed: [source,bash] ---- camel test run route-test.yaml ---- -You will see the test running and producing some output to the console. -At the end you should see a passed test in the test summary. -By default, the tests are run with the JUnit Jupiter engine. -Please refer to the help page of the `run` command for options and details. - -TIP: The Camel CLI 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. - == 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. - -The test plugin is able to participate in the project export in order to also add test scoped resources. -When the plugin is active in your local JBang environment it will try to locate the automated tests and its resources (in the `test` subfolder) to add them to the exported project. - -Just keep using the normal project export command provided in Camel CLI. -The test plugin will automatically add the test resources for you. +When you export a project, the test plugin automatically includes test resources as test-scoped Maven dependencies in `src/test/java` and `src/test/resources`: [source,bash] ---- camel export route.yaml --dir my-export --runtime quarkus ----- - -The resulting project export holds the test resources and the required dependencies to run the test. -In Maven this will be test-scoped dependencies added to the Maven `pom.xml` and test resources in `src/test/java` and `src/test/resources`. - -The tests are now part of the Maven build lifecycle so you can build the project and see the tests being automatically run. -Navigate to the project export folder and run the Maven verify lifecycle that includes running integration tests. - -[source,bash] ----- +cd my-export ./mvnw verify ---- -You should see some tests being executed during the Maven build and of course in case a test is failing you will see the Maven build failing, too. -Now the automated tests from the prototyping phase with Camel CLI are part of the project for further usage in a CI/CD pipeline for instance. - -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. +TIP: The export creates a JUnit Jupiter test class in `src/test/java` that you can also run from your IDE. == 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. +Basic Citrus dependencies are included out of the box. For additional modules (Kafka, Testcontainers, etc.), add them in a `jbang.properties` file next to the test source: .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 CLI 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. +TIP: These dependencies are automatically added as test-scoped dependencies during project export. -== Explore test capabilities +== Writing tests with Citrus -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 CLI for instance. +The test plugin uses https://citrusframework.org/[Citrus] as the underlying test framework. A typical test: -You can also install the https://citrusframework.org/[Citrus test framework] JBang application to explore the full capabilities. +1. Starts infrastructure (Kafka, database, etc.) +2. Launches the Camel integration with test configuration +3. Sends messages to trigger route logic +4. Verifies the outcome -[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) -* Start the Camel integration and configure the routes to connect with the infrastructure -* Invoke exposed services of the Camel integration that triggers the route logic -* Verify the Camel integration outcome (e.g. receive and validate created events on Kafka, verify the entries in a database) - -The following sections explore these tasks when writing a test in Citrus. -For further details on test capabilities please also read the https://citrusframework.org/citrus/reference/html/[Citrus documentation]. +For full details, see the https://citrusframework.org/citrus/reference/html/[Citrus documentation]. -=== Using Camel Infrastructure Services +=== Using infrastructure services -The Camel CLI `infra` command enables you to start infrastructure services in your test environment. -See the list of available services with `camel infra`. +Start Camel infra services or Testcontainers as part of the test: -The Citrus test is able to run these infrastructure services as part of the test. - -.Start Camel infra service [source,yaml] ---- actions: @@ -186,59 +86,24 @@ actions: infra: run: service: postgres ----- - -Once the infrastructure service is started Citrus exposes connection settings as test variables. -You can use the exposed connection settings to create proper clients that connect to the services. - -The exposed connection settings follow a naming pattern that looks like this: - -* CITRUS_CAMEL_INFRA_SERVICE_<SERVICE_NAME>_<PROPERTY_NAME> -* CITRUS_CAMEL_INFRA_SERVICE_<SERVICE_NAME>_<IMPLEMENTATION>_<PROPERTY_NAME> - -You can then use these test variables in the Camel configuration (e.g. in `application.properties`). - -.application.properties -[source,properties] ----- -camel.database.url=${CITRUS_CAMEL_INFRA_POSTGRES_SERVICE_ADDRESS} ----- - -Read more about the https://citrusframework.org/citrus/reference/html/#camel-infra[Camel infra support in Citrus]. - -=== Using Testcontainers - -In a similar way to starting Camel infrastructure services you can also use Testcontainers as a form of infrastructure for your test. -You may want to start a Testcontainers instance as part of the test. - -[source,yaml] ----- -actions: - testcontainers: start: kafka: {} ---- -Once the Testcontainers instance is started the Citrus test exposes connection settings in the form of test variables. -The variable names follow this naming pattern: +Connection settings are exposed as test variables (`CITRUS_CAMEL_INFRA_SERVICE_<NAME>_<PROP>` or `CITRUS_TESTCONTAINERS_<NAME>_<PROP>`) for use in `application.properties`: -* CITRUS_TESTCONTAINERS_<SERVICE_NAME>_<PROPERTY_NAME> - -You can reference the test variables in the configuration for the Camel routes (e.g. in `application.properties`). - -.application.properties [source,properties] ---- +camel.database.url=${CITRUS_CAMEL_INFRA_POSTGRES_SERVICE_ADDRESS} camel.kafka.bootstrapServers=${CITRUS_TESTCONTAINERS_KAFKA_BOOTSTRAP_SERVERS} ---- -Read more about the https://citrusframework.org/citrus/reference/html/#testcontainers[Testcontainers support in Citrus]. +See https://citrusframework.org/citrus/reference/html/#camel-infra[Camel infra] and https://citrusframework.org/citrus/reference/html/#testcontainers[Testcontainers] in the Citrus docs. -=== Run the Camel integration +=== Running the Camel integration -Citrus provides special test actions to run Camel integrations with Camel CLI. -The test starts the integration as a separate Camel CLI process. -You are able to apply specific configuration to the Camel CLI process such as `application.properties`, system properties and environment variables. +Launch a Camel integration as a separate process with test-specific configuration: [source,yaml] ---- @@ -252,25 +117,15 @@ actions: file: "application.test.properties" ---- -The test action above runs the Camel integration in the file `route.yaml` and applies some test configuration as application properties. - -TIP: Note that the file path to the `route.yaml` Camel integration uses a relative path that navigates to the parent folder. -This is because usually the tests are located in a subdirectory (e.g. `test`) in order to separate test-scoped resources from runtime resources. - -This will start the Camel integration as a Camel CLI process. -The test waits for the integration to report a running status. -Then the test proceeds with further actions (e.g. invoking the exposed service of the Camel integration). - -Read more about the https://citrusframework.org/citrus/reference/html/#apache-camel[Camel CLI support in Citrus]. +TIP: The path uses `../` because tests are in the `test` subfolder. -=== Send/receive messages +See https://citrusframework.org/citrus/reference/html/#apache-camel[Camel CLI support in Citrus]. -Once the Camel integration is up and running the test may trigger the route logic by invoking an exposed service. -Citrus is able to send and receive messages with various messaging transports (Kafka, Http, SOAP WebServices, FTP, JMS and many more). +=== Sending and receiving messages -You can send a message to a Kafka topic for instance: +Citrus supports Kafka, HTTP, SOAP, FTP, JMS, and many more transports: -.Send message to Kafka topic +.Send to Kafka [source,yaml] ---- actions: @@ -285,28 +140,7 @@ actions: value: "bookings.csv_0" ---- -The message sent may trigger the Camel integration that listens for events on the Kafka topic `bookings`. - -In the same way Citrus would be able to invoke an Http service that the Camel integration exposes as a Http platform service. - -.Invoke Http service -[source,yaml] ----- -actions: - - send: - endpoint: "http://localhost:8080/bookings"; - message: - body: - data: | - { "client": "camel-batch", "product": "Orange", "amount": 200, "price": 1.0, "status": "APPROVAL_REQUIRED" } - headers: - - name: "Content-Type" - value: "application/json" ----- - -When receiving messages in the test you can define an expected message content (body and headers). - -.Validate Kafka event +.Verify received message [source,yaml] ---- actions: @@ -318,36 +152,7 @@ actions: { "bookings": { "completed": 1, "errors": 0 } } ---- -The test will validate the message according to the expected message content and of course the test will fail in case some elements -are not as expected. Citrus as a test framework provides very powerful message validation capabilities for different message formats such as XML, Json, YAML, plaintext and more. - -Read more about https://citrusframework.org/citrus/reference/html/#endpoints[message endpoints] and how to invoke services with https://citrusframework.org/citrus/reference/html/#actions-send[send and receive test actions] in Citrus. - -=== Invoke Camel endpoint URIs - -Citrus is able to invoke any Camel endpoint URI as part of the test. -This way users are able to use any of the Apache Camel components for sending and receiving messages during the test. - -.Send message to AWS S3 service -[source,yaml] ----- -actions: - - send: - endpoint: | - camel:aws2-s3:my-bucket?amazonS3Client=#s3Client - message: - body: - data: | - Apple,200,1.0 - Orange,100,1.0 - Pineapple,100,2.99 - headers: - - name: "CamelAwsS3Key" - value: "bookings.csv" ----- - -This uses the `aws2-s3` Apache Camel component to create a new file on a S3 bucket. - -TIP: You can reference beans in the Camel endpoint URI. As an example the URI above uses a bean reference `#s3Client` as a client that connects to the AWS S3 test infrastructure service. The beans can be added to both the Camel context or the Citrus registry. +You can also use any Camel endpoint URI directly (e.g., `camel:aws2-s3:my-bucket?amazonS3Client=#s3Client`). +Bean references (`#beanName`) and Citrus test variables work in endpoint URIs. -TIP: You can also use Citrus test variables in the Camel endpoint URIs in order to reference dynamic values such as connection settings exposed by test infrastructure. +See https://citrusframework.org/citrus/reference/html/#actions-send[send/receive actions] and https://citrusframework.org/citrus/reference/html/#endpoints[message endpoints] in the Citrus docs.
