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 539dd46de79 CAMEL-21618: review test infra documentation (#16952)
539dd46de79 is described below
commit 539dd46de79d4faa4e6ade0afc7b08e907f9f737
Author: Otavio Rodolfo Piske <orpi...@users.noreply.github.com>
AuthorDate: Wed Jan 29 07:06:51 2025 +0100
CAMEL-21618: review test infra documentation (#16952)
---
.../user-manual/modules/ROOT/pages/test-infra.adoc | 167 ++++++---------------
test-infra/camel-test-infra-core/README.md | 71 ++++++++-
2 files changed, 115 insertions(+), 123 deletions(-)
diff --git a/docs/user-manual/modules/ROOT/pages/test-infra.adoc
b/docs/user-manual/modules/ROOT/pages/test-infra.adoc
index 2b2cc134def..237846a8dd9 100644
--- a/docs/user-manual/modules/ROOT/pages/test-infra.adoc
+++ b/docs/user-manual/modules/ROOT/pages/test-infra.adoc
@@ -1,70 +1,11 @@
= Test Infrastructure
-The components in the Camel Test Infra provide utilities to simplify testing
with Camel and other systems may interact with it. They work as JUnit 5
extensions.
+The components in the Camel Test Infra provide utilities to simplify testing
with Camel and other systems may interact with it.
-== Working with the Camel Context in Tests
+The test infra is divided in two parts:
-When testing Camel or a Camel-based integration, you almost certainly need to
use the `CamelContext` to configure the registry, add routes and execute other
operations. The test infra comes with a module that provides a JUnit 5
extension that allows you to inject a Camel context into your tests.
-
-Adding it to your test code is as simple as adding the following lines of code
to your test class:
-
-[source,java]
-----
-@RegisterExtension
-protected static CamelContextExtension contextExtension = new
DefaultCamelContextExtension();
-----
-
-Then, via the extension, you can access the context (i.e.:
`contextExtension.getContext()`) to manipulate it as needed in the tests.
-
-The extension comes with a few utilities to simplify configuring the context,
and adding routes at the appropriate time.
-
-=== Configuring the Camel Context
-
-To create a method that configures the context, you can declare a method
receiving an instance of `CamelContext` and annotate it with `@ContextFixture`.
-
-[source,java]
-----
-@ContextFixture
-public void configureContext(CamelContext context) {
- // context configuration code here
-}
-----
-
-Additionally, you can simplify the class hierarchy, and ensure consistency you
may also implement the `ConfigurableContext` interface.
-
-=== Configuring the Routes
-
-You can configure the routes using a similar process as the one described for
configuring the Camel context. You can create a method that receives an
instance of `CamelContext` and annotate it with `@RouteFixture`.
-
-[source,java]
-----
-@RouteFixture
-public void createRouteBuilder(CamelContext context) throws Exception {
- context.addRoutes(new RouteBuilder() {
- @Override
- public void configure() {
- from(fromUri).to(destUri);
- }
- });
-}
-----
-
-=== Use the Camel Context Extension
-
-To start using the Camel Context extension on your code, add the following
dependency:
-
-[source,xml]
-----
-<dependency>
- <groupId>org.apache.camel</groupId>
- <artifactId>camel-test-infra-core</artifactId>
- <version>${camel.version}</version>
- <scope>test</scope>
- <type>test-jar</type>
-</dependency>
-----
-
-For simplicity and consistency, you may also declare the route as implementing
the `ConfigurableRoute`.
+* One that offers container provisioning features for all scopes
+* Another that provides container provisioning features for tests.
== Simulating the Test Infrastructure
@@ -85,25 +26,38 @@ This section is aimed at Camel maintainers that need to
write new test infra com
====
The test code abstracts the provisioning of test environments behind service
classes (i.e.: JMSService, JDBCService,
-etc). The purpose of the service class is to abstract the both the type
service (i.e.: Kafka, Strimzi, etc) and
+etc). The purpose of the service class is to abstract both the type service
(i.e.: Kafka, Strimzi, etc.) and
the location of the service (i.e.: remote, local, embedded, etc). This
provides flexibility to test the code under
different circumstances (i.e.: using a remote JMS broker or using a local JMS
broker running in a container managed by
TestContainers). It makes it easier to hit edge cases as well as try different
operating scenarios (i.e.: higher
latency, slow backends, etc).
-JUnit 5 manages the lifecycle of the services.
-Therefore, each service must be a JUnit 5 compliant extension.
-The exact extension point that a service must extend is specific to each
service.
-The https://junit.org/junit5/docs/current/user-guide[JUnit 5 documentation] is
the reference for the extension points.
-
When a container image is not available via TestContainers, tests can provide
their own implementation using officially
available images. The license must be compatible with Apache 2.0. If an
official image is not available, a Dockerfile
to build the service can be provided. The Dockerfile should try to minimize
the container size and resource usage
whenever possible.
+The container information must reside in a file named `container.properties`
which should contain the container fully qualified
+name:
+
+[source,properties]
+----
+opensearch.container=mirror.gcr.io/opensearchproject/opensearch:2.18.0
+opensearch.container.ppc64le=icr.io/ppc64le-oss/opensearch-ppc64le:2.12.0
+----
+
+The keys must follow the pattern `<name>.properties`. Specific architectures
can be added to the key to denote which container
+to be used for each architecture. Currently accepted values are:
+
+* `aarch64`: for Arm
+* `s390x`: for s390x (Linux On Mainframe)
+* `ppc64le`: for 64-bit little ending power
+
It is also possible to use embeddable components when required, although this
usually leads to more code and higher
maintenance.
+NOTE: support for embeddable components may be removed in future versions.
+
==== Recommended Structure for Test Infrastructure Modules
The actual Service interface and implementation should be added under
`src/main`, while the actual integration with JUnit
@@ -113,17 +67,10 @@ by JUnit and can be run separately.
===== Main Sources
The service should provide an interface, named after the infrastructure being
implemented, and this interface should extend the
-https://github.com/apache/camel/blob/main/test-infra/camel-test-infra-common/src/main/java/org/apache/camel/test/infra/common/services/InfrastructureService.java[InfrastructureService]
+https://github.com/apache/camel/blob/main/test-infra/camel-test-infra-common/src/main/java/org/apache/camel/test/infra/common/services/InfrastructureService.java[`InfrastructureService`]
interface.
-[NOTE]
-====
-Bear in mind that, according to the
https://junit.org/junit5/docs/5.1.1/api/org/junit/jupiter/api/extension/RegisterExtension.html[JUnit
5 extension]
-model, the time of initialization of the service may differ depending on
whether the service instance is declared as
-static or not in the test class. As such, the code should make no assumptions
as to its time of initialization.
-====
-
-Ideally, there should be two concrete implementations of the services: one of
the remote service (if applicable) and
+Ideally, there should be two concrete implementations of the services: one of
the remote service (if applicable) and
another for the container service:
```
@@ -153,10 +100,17 @@ and
https://junit.org/junit5/docs/5.1.1/api/org/junit/jupiter/api/extension/Afte
should be the preferred extensions whenever possible because they allow the
instance of the infrastructure to be static
throughout the test execution.
+[NOTE]
+====
+Bear in mind that, according to the
https://junit.org/junit5/docs/5.1.1/api/org/junit/jupiter/api/extension/RegisterExtension.html[JUnit
5 extension]
+model, the time of service initialization may differ depending on whether the
service instance is declared as
+static or not in the test class. As such, the code should make no assumptions
as to its time of initialization.
+====
+
==== Registering Properties
All services should register the properties, via `System.setProperty` that
allow access to the services. This is required
-in order to resolve those properties when running tests using the Spring
framework. This registration allows the properties
+ to resolve those properties when running tests using the Spring framework.
This registration allows the properties
to be resolved in Spring's XML files.
This registration is done in the `registerProperties` methods during the
service initialization.
@@ -196,7 +150,7 @@ Then, when referring these properties in Camel routes or
Spring XML properties,
This is infrastructure code for testing, therefore, it should be package as
test type artifacts. The
https://github.com/apache/camel/blob/main/test-infra/camel-test-infra-parent[parent
pom] should provide all the necessary bits for packaging the test
infrastructure.
-=== Using The New Test Infrastructure
+=== Using The Test Infrastructure in Tests
Using the test infra in a new component test is rather straightforward,
similar to using any other reusable component.
You start by declaring the test infra dependencies in your pom file.
@@ -222,7 +176,7 @@ Camel version when used outside the Camel Core project.
====
On the test class, add a member variable for the service and annotate it with
the
https://junit.org/junit5/docs/5.1.1/api/org/junit/jupiter/api/extension/RegisterExtension.html[@RegisterExtension],
-in order to let JUnit 5 manage its lifecycle.
+ to let JUnit 5 manage its lifecycle.
[source,java]
----
@@ -283,48 +237,20 @@ For instance:
protected static CamelContextExtension contextExtension = new
DefaultCamelContextExtension();
----
+== Container Runtime Support
-== Converting Camel TestContainers Code To The New Test Infrastructure
-
-
-[NOTE]
-====
-This section is aimed at Camel maintainers that need to write new test infra
components. End users can skip this section.
-====
-
-Using the camel-nats as an example, we can compare how the base test class for
nats changed between
https://github.com/apache/camel/blob/camel-3.6.0/components/camel-nats/src/test/java/org/apache/camel/component/nats/NatsTestSupport.java[3.6.x]
-and
https://github.com/apache/camel/blob/camel-3.7.0/components/camel-nats/src/test/java/org/apache/camel/component/nats/NatsTestSupport.java[3.7.x].
-
-The first conversion step is to remove the
https://github.com/apache/camel/blob/camel-3.6.0/components/camel-nats/pom.xml#L59-L63[camel-testcontainer
dependencies]
-and replace them with the ones from the
https://github.com/apache/camel/blob/camel-3.7.0/components/camel-nats/pom.xml#L61-L75[test-infra
module].
-Then, it's necessary to replace the
https://github.com/apache/camel/blob/camel-3.6.0/components/camel-nats/src/test/java/org/apache/camel/component/nats/NatsTestSupport.java#L24-L45[container
handling code and the old base class]
-with the
https://github.com/apache/camel/blob/camel-3.7.0/components/camel-nats/src/test/java/org/apache/camel/component/nats/NatsTestSupport.java#L26-L27[service
provided in the module].
-Then, we replace the base class. The `ContainerAwareTestSupport` class and
other similar classes from other
-`camel-testcontainer` modules are not necessary and can be replaced with
`CamelTestSupport` or the spring-based one
-`CamelSpringTestSupport`.
+Most of the test infrastructure in this module is based on containers.
+Therefore, they will require a container runtime to run.
+The tests have been written and tested using:
-With the base changes in place, the next step is to make sure that addresses
(URLs, hostnames, ports, etc.) and
-resources (usernames, passwords, tokens, etc.) referenced during the test
execution, use the test-infra services. This
-may differ, according to each service. Replacing the call to get the
https://github.com/apache/camel/blob/camel-3.6.0/components/camel-nats/src/test/java/org/apache/camel/component/nats/NatsAuthConsumerLoadTest.java#L38[service
URL]
-with the one provided by the new
https://github.com/apache/camel/blob/camel-4.4.0/components/camel-nats/src/test/java/org/apache/camel/component/nats/integration/NatsAuthConsumerLoadIT.java#L37[test
infra service]
-is a good example of the changes that may be necessary.
+* Docker
+* https://podman.io/[Podman]
-In some cases, it may be necessary to adjust the variables used in
https://github.com/apache/camel/blob/camel-3.6.0/components/camel-consul/src/test/resources/org/apache/camel/component/consul/cloud/SpringConsulRibbonServiceCallRouteTest.xml#L36[simple
language]
-so that they match the
https://github.com/apache/camel/blob/camel-3.14.0/components/camel-consul/src/test/resources/org/apache/camel/component/consul/cloud/SpringConsulRibbonServiceCallRouteTest.xml#L36[new
property format] used in the test infra service.
-
-
-There are some cases where the container instance requires
https://github.com/apache/camel/blob/camel-3.6.0/components/camel-pg-replication-slot/src/test/java/org/apache/camel/component/pg/replication/slot/integration/PgReplicationTestSupport.java#L31[extra
customization].
-Nonetheless, the migrated code still benefits from the
https://github.com/apache/camel/blob/camel-3.7.0/components/camel-pg-replication-slot/src/test/java/org/apache/camel/component/pg/replication/slot/integration/PgReplicationTestSupport.java#L31[test-infra
approach],
-but this may be very specific to the test scenario.
-
-
-== Running With Podman
-
-Most of the test infrastructure in this module is based on containers.
Therefore, they will require a container runtime to run. Although the tests
have been written and tested using Docker, they should also work with
https://podman.io/[Podman] (another popular container runtime on Linux
operating systems).
+=== Podman Support
Assuming Podman is properly installed and configured to behave like docker
(i.e.: short name resolution, resolving docker.io registry, etc.), the only
requirement for using Podman is to export the `DOCKER_HOST` variable before
running the tests.
-=== Linux
+==== Linux
On most systems that should be similar to the following command:
@@ -332,7 +258,7 @@ On most systems that should be similar to the following
command:
export DOCKER_HOST=unix:///run/user/$UID/podman/podman.sock
```
-=== OS X and Windows
+==== OS X and Windows
Running the test-infra with Podman on OS X and Windows should work on many
cases. However, it requires additional steps and has a few issues. Therefore,
it is not recommended at this time.
@@ -344,7 +270,4 @@ Some containers don't have images available for all
architectures. In this case,
1. use an alternative image from a reputable source if they provide an image
for that architecture.
2. create a `Dockerfile` and build your own if the system is available on that
arch.
-3. disable the tests on that architecture.
-
-
-
+3. disable the tests on that architecture.
\ No newline at end of file
diff --git a/test-infra/camel-test-infra-core/README.md
b/test-infra/camel-test-infra-core/README.md
index 5aeb8c2608a..905557a4f47 100644
--- a/test-infra/camel-test-infra-core/README.md
+++ b/test-infra/camel-test-infra-core/README.md
@@ -1,8 +1,77 @@
# Converting Projects
+## Working with the Camel Context Infra
+
+One of the infrastructure components provided by test infra is a JUnit 5
extension that injects a Camel context into the tests.
+This extension is called `camel-test-infra-core`.
+It is an internal interface, meant to be used only by Camel itself, for very
+specific test scenarios.
+
+When testing Camel or a Camel-based integration, you almost certainly need to
use the `CamelContext` to configure the registry, add routes and execute other
operations. The test infra comes with a module that provides a JUnit 5
extension that allows you to inject a Camel context into your tests.
+
+Adding it to your test code is as simple as adding the following lines of code
to your test class:
+
+```java
+@RegisterExtension
+protected static CamelContextExtension contextExtension = new
DefaultCamelContextExtension();
+```
+
+Then, via the extension, you can access the context (i.e.,:
`contextExtension.getContext()`) to manipulate it as needed in the tests.
+
+The extension comes with a few utilities to simplify configuring the context,
and adding routes at the appropriate time.
+
+### Configuring the Camel Context
+
+To create a method that configures the context,
+you can declare a method receiving an instance of `CamelContext` and annotate
it with `@ContextFixture`.
+
+```java
+@ContextFixture
+public void configureContext(CamelContext context) {
+ // context configuration code here
+}
+```
+
+Additionally, you can simplify the class hierarchy,
+and ensure consistency you may also implement the `ConfigurableContext`
interface.
+
+
+### Configuring the Routes
+
+You can configure the routes using a similar process as the one described for
configuring the Camel context. You can create a method that receives an
instance of `CamelContext` and annotate it with `@RouteFixture`.
+
+```java
+@RouteFixture
+public void createRouteBuilder(CamelContext context) throws Exception {
+ context.addRoutes(new RouteBuilder() {
+ @Override
+ public void configure() {
+ from(fromUri).to(destUri);
+ }
+ });
+}
+```
+
+### Using the Camel Context Extension
+
+To start using the Camel Context extension on your code, add the following
dependency:
+
+```xml
+<dependency>
+ <groupId>org.apache.camel</groupId>
+ <artifactId>camel-test-infra-core</artifactId>
+ <version>${camel.version}</version>
+ <scope>test</scope>
+ <type>test-jar</type>
+</dependency>
+```
+
+For simplicity and consistency, you may also declare the route as implementing
the `ConfigurableRoute`.
+
+
## Converting projects that manage the CamelContext directly
-This section describe how to convert projects that create and manage a
`CamelContext` directly (i.e.; not relying on `CamelTestSupport`).
+This section describes how to convert projects that create and manage a
`CamelContext` directly (i.e.; not relying on `CamelTestSupport`).
1. Add the dependency that brings the CamelContext JUnit 5 extension
