This is an automated email from the ASF dual-hosted git repository.
davsclaus pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/camel.git
The following commit(s) were added to refs/heads/master by this push:
new ccb1e0a Added documentation about the test-infra (#4750)
ccb1e0a is described below
commit ccb1e0a9ed738958a48b6558cc48f1adae4381bc
Author: Otavio Rodolfo Piske <orpi...@users.noreply.github.com>
AuthorDate: Thu Dec 10 11:05:43 2020 +0100
Added documentation about the test-infra (#4750)
---
.../modules/ROOT/pages/contributing.adoc | 19 +++++++++
test-infra/README.md | 46 ++++++++++++++++++++++
2 files changed, 65 insertions(+)
diff --git a/docs/user-manual/modules/ROOT/pages/contributing.adoc
b/docs/user-manual/modules/ROOT/pages/contributing.adoc
index 4f0de01..9b703cc 100644
--- a/docs/user-manual/modules/ROOT/pages/contributing.adoc
+++ b/docs/user-manual/modules/ROOT/pages/contributing.adoc
@@ -25,6 +25,7 @@ We also participate in Google Summer of Code and Outreachy
programs, for informa
* <<improving-the-documentation,Improving the documentation>>
* <<if-you-find-a-bug-or-problem,If you find a bug or problem>>
* <<working-on-the-code,Working on the code>>
+* <<testing-the-changes,Testing the changes>>
* <<running-checkstyle,Running checkstyle>>
* <<verify-karaf-features,Verify Karaf features>>
* <<apache-camel-committers-should-work-on-the-asf-git-repo,Apache Camel
committers should work on the ASF git repo>>
@@ -103,6 +104,24 @@ If you intend to work on the code and provide patches and
other work you want to
If you aren't able to build component after adding some new URI parameters due
to `Empty doc for option: [OPTION], parent options: <null>` please make sure
that you either added properly javadoc for get/set method or description in
`@UriPath` annotation.
+[#testing-the-changes]
+== Testing the changes
+
+If you need to implement tests for your changes, you will probably need to
handle 3 separate things: simulate the infrastructure
+required for the test (ie.: JMS brokers, Kafka, etc), the code changes and the
test logic itself. Naturally, there is no rule of
+thumb for how the code changes and test logic should be. However, in regard to
simulating the test infrastructure, there is a
+growing library of reusable components that can be helpful. These components
are locate in the test-infra module and provide
+support for simulating message brokers, cloud environments, databases and much
more.
+
+Using these components is usually as simple as registering them as JUnit 5
extensions:
+
+ @RegisterExtension
+ static NatsService service = NatsServiceFactory.createService();
+
+Then, you can access the service by using the methods and properties provided
by the services. This varies according to each service.
+
+If you need to implement a new test infra service, check the readme on the
test-infra module for additional details.
+
[#running-checkstyle]
== Running checkstyle
diff --git a/test-infra/README.md b/test-infra/README.md
new file mode 100644
index 0000000..6d2843a
--- /dev/null
+++ b/test-infra/README.md
@@ -0,0 +1,46 @@
+# Test Infrastructure
+
+## Simulating the Test Infrastructure
+
+One of the first steps when implementing a new test, is to identify how to
simulate infrastructure required for it to
+run. The test-infra module provides a reusable library of infrastructure that
can be used for that purpose.
+
+In general, the integration test leverages the features provided by the
project https://www.testcontainers.org/[TestContainers]
+and uses container images to simulate the environments. Additionally, it may
also support running the tests against remote
+environments as well as, when available, embeddable components. This varies by
each component and it is recommended to
+check the code for additional details.
+
+## Implementing new Test Infra
+
+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
+the location of the service (i.e.: remote, local, embedded, etc). This
provides flexibility to test the code under
+different circumstances (ie.: 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 (ie.: 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
JUnit 5
+https://junit.org/junit5/docs/current/user-guide/[documentation] is the
reference for the extension points.
+
+In general, the services should aim to minimize the test execution time and
resource usage when running. As such,
+the
https://junit.org/junit5/docs/5.1.1/api/org/junit/jupiter/api/extension/BeforeAllCallback.html[BeforeAllCallback]
+and
https://junit.org/junit5/docs/5.1.1/api/org/junit/jupiter/api/extension/AfterAllCallback.html[AfterAllCallback]
+should be the preferred extensions whenever possible because they allow the
instance of the infrastructure to be static
+throughout the test execution.
+
+In most cases a specialized service factory class is responsible for creating
the service according to runtime
+parameters and/or other test scenarios constraints. When a service allows
different service types or locations to be
+selected, this should be done via command line properties
(`-D<property.name>=<value>`). For example, when allowing a
+service to choose between running as a local container or as remote instance,
a property in the format
+`<name>.instance.type` should be handled. Additional runtime parameters used
in different scenarios, should be handled
+as `<name>.<parameter>`. More complex services may use the builder pattern to
compose the service accordingly.
+
+
+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.
+
+It is also possible to use embeddable components when required, although this
usually lead to more code and higher
+maintenance.
\ No newline at end of file
