From 7dae4e0ea029b5b28367fc9f5dd0f976ee5e3a9e Mon Sep 17 00:00:00 2001 From: Oliver Lietz Date: Fri, 29 Nov 2024 18:09:39 +0100 Subject: [PATCH] #1090 Move documentation from Confluence to Git * add more content * adjust titles * use version from Git --- documentation/antora.yml | 2 +- documentation/modules/ROOT/nav.adoc | 11 +++++ .../modules/ROOT/pages/containers/forked.adoc | 4 +- .../modules/ROOT/pages/containers/karaf.adoc | 4 +- .../modules/ROOT/pages/containers/native.adoc | 4 +- .../modules/ROOT/pages/containers/remote.adoc | 2 - .../modules/ROOT/pages/drivers/junit4.adoc | 4 +- .../ROOT/pages/drivers/servlet-bridge.adoc | 4 +- .../modules/ROOT/pages/drivers/testng.adoc | 4 +- documentation/modules/ROOT/pages/index.adoc | 43 +++++++++++++++++++ documentation/modules/ROOT/pages/reactor.adoc | 23 ++++++++++ 11 files changed, 90 insertions(+), 15 deletions(-) delete mode 100644 documentation/modules/ROOT/pages/containers/remote.adoc create mode 100644 documentation/modules/ROOT/pages/reactor.adoc diff --git a/documentation/antora.yml b/documentation/antora.yml index a36241660..3e4ecd5ed 100644 --- a/documentation/antora.yml +++ b/documentation/antora.yml @@ -1,5 +1,5 @@ name: pax-exam title: Pax Exam -version: 4 +version: true nav: - modules/ROOT/nav.adoc diff --git a/documentation/modules/ROOT/nav.adoc b/documentation/modules/ROOT/nav.adoc index 31f850eeb..442595974 100644 --- a/documentation/modules/ROOT/nav.adoc +++ b/documentation/modules/ROOT/nav.adoc @@ -1 +1,12 @@ * xref:index.adoc[] +* xref:containers.adoc[] +** xref:containers/native.adoc[] +** xref:containers/forked.adoc[] +** xref:containers/karaf.adoc[] +* xref:drivers.adoc[] +** xref:drivers/junit4.adoc[] +** xref:drivers/testng.adoc[] +** xref:drivers/servlet-bridge.adoc[] +* xref:configuration.adoc[] +* xref:reactor.adoc[] +* xref:logging.adoc[] diff --git a/documentation/modules/ROOT/pages/containers/forked.adoc b/documentation/modules/ROOT/pages/containers/forked.adoc index 1d104cc79..1f1e2b1e1 100644 --- a/documentation/modules/ROOT/pages/containers/forked.adoc +++ b/documentation/modules/ROOT/pages/containers/forked.adoc @@ -1,2 +1,2 @@ -= Forked Test Container -:navtitle: Forked += Pax Exam Forked Container +:navtitle: Forked Container diff --git a/documentation/modules/ROOT/pages/containers/karaf.adoc b/documentation/modules/ROOT/pages/containers/karaf.adoc index 49f471d93..046fdcd9f 100644 --- a/documentation/modules/ROOT/pages/containers/karaf.adoc +++ b/documentation/modules/ROOT/pages/containers/karaf.adoc @@ -1,2 +1,2 @@ -= Karaf Test Container -:navtitle: Karaf += Pax Exam Karaf Container +:navtitle: Karaf Container diff --git a/documentation/modules/ROOT/pages/containers/native.adoc b/documentation/modules/ROOT/pages/containers/native.adoc index 4549764fe..67d79a7db 100644 --- a/documentation/modules/ROOT/pages/containers/native.adoc +++ b/documentation/modules/ROOT/pages/containers/native.adoc @@ -1,2 +1,2 @@ -= Native Test Container -:navtitle: Native += Pax Exam Native Container +:navtitle: Native Container diff --git a/documentation/modules/ROOT/pages/containers/remote.adoc b/documentation/modules/ROOT/pages/containers/remote.adoc deleted file mode 100644 index d4d108471..000000000 --- a/documentation/modules/ROOT/pages/containers/remote.adoc +++ /dev/null @@ -1,2 +0,0 @@ -= Remote Test Container -:navtitle: Remote diff --git a/documentation/modules/ROOT/pages/drivers/junit4.adoc b/documentation/modules/ROOT/pages/drivers/junit4.adoc index 3f2b66836..73a610d7c 100644 --- a/documentation/modules/ROOT/pages/drivers/junit4.adoc +++ b/documentation/modules/ROOT/pages/drivers/junit4.adoc @@ -1,2 +1,2 @@ -= JUnit Driver -:navtitle: JUnit += Pax Exam JUnit Driver +:navtitle: JUnit Driver diff --git a/documentation/modules/ROOT/pages/drivers/servlet-bridge.adoc b/documentation/modules/ROOT/pages/drivers/servlet-bridge.adoc index 394cd2be5..065219a53 100644 --- a/documentation/modules/ROOT/pages/drivers/servlet-bridge.adoc +++ b/documentation/modules/ROOT/pages/drivers/servlet-bridge.adoc @@ -1,2 +1,2 @@ -= Servlet Bridge Driver -:navtitle: Servlet Bridge += Pax Exam Servlet Bridge Driver +:navtitle: Servlet Bridge Driver diff --git a/documentation/modules/ROOT/pages/drivers/testng.adoc b/documentation/modules/ROOT/pages/drivers/testng.adoc index 305dae993..483eab950 100644 --- a/documentation/modules/ROOT/pages/drivers/testng.adoc +++ b/documentation/modules/ROOT/pages/drivers/testng.adoc @@ -1,2 +1,2 @@ -= TestNG Driver -:navtitle: TestNG += Pax Exam TestNG Driver +:navtitle: TestNG Driver diff --git a/documentation/modules/ROOT/pages/index.adoc b/documentation/modules/ROOT/pages/index.adoc index 407dc2e95..f9b233802 100644 --- a/documentation/modules/ROOT/pages/index.adoc +++ b/documentation/modules/ROOT/pages/index.adoc @@ -1,2 +1,45 @@ = Pax Exam :navtitle: Pax Exam + +Pax Exam is an in-container testing framework for https://www.osgi.org[OSGi]. + +* Pax Exam lets you take control of the OSGi framework, the test framework (e.g. JUnit) and your system under test at the same time. +* Pax Exam is also able to bootstrap an https://karaf.apache.org[Apache Karaf] container allowing you to directly execute commands, deploy features, etc. +* Pax Exam has a test driver and a test container. The driver launches the OSGi framework and the system under test. It builds on-the-fly bundles from your test cases and injects them into the container. The driver is a plain old Java application and does not itself require an OSGi framework. +* The test container comes in two flavours: The Native Container launches an embedded OSGi framework in the test driver VM. With the Forked Container, the system under test runs in a separate Java virtual machine under remote control from the test driver. +* Test containers support different strategies for restarting or reusing the running OSGi framework for each test. +* With the Pax Exam JUnit runner, you simply need to add some special annotations and a configuration method to a JUnit class to run your OSGi tests. Thanks to this runner, any JUnit integration (e.g. in Eclipse or Maven Surefire) works with Pax Exam out of the box. +* Pax Exam itself is distributed as Maven artifacts and lets you provision Maven bundles to your OSGi framework directly from local or remote Maven repositories. +* Pax Exam supports all major OSGi frameworks (https://eclipse.dev/equinox/[Equinox], https://felix.apache.org[Felix], https://www.knopflerfish.org[Knopflerfish]). + +== Framework +In the context of Pax Exam, the term framework usually refers to the OSGi framework running the system under test. + +== System under test +The system under test is the collection of your application and library bundles. +Pax Exam aims at executing black box tests, but in fact the box (i.e. the container) is slightly grey, as Pax Exam adds some bundles of its own and the probe. + +== Test Container +The test container is a thin wrapper around the framework, the system under test and the probe, adding the ability to communicate with the driver and the +outside world in general. + +== Reactor +The reactor manages the collection of all tests to be executed in one or more different containers. The reactor starts and stops the required containers and +provisions bundles and probes to the containers. + +== Driver +The driver is the entry point into Pax Exam. It evaluates configuration options and creates a reactor based on these options. The driver receives the test +results and handles them in an implementation dependent way. + +Pax Exam includes different drivers: + +* The JUnit driver integrates Pax Exam with https://junit.org[JUnit]. +* The TestNG driver integrates Pax Exam with https://testng.org[TestNG]. + +== Probe +The probe is a synthetic artifact which Pax Exam adds to the system under test. +Pax Exam creates the probe on the fly with the help of https://github.com/ops4j/org.ops4j.pax.tinybundles[Tinybundles]. The probe contains the current test class and all classes and resources found under the same root. + +== Configuration +The configuration determines the set of bundles provisioned to the container, and some system and environment properties. +Use one or more methods annotated by `@Configuration` with return type `Option[]`. diff --git a/documentation/modules/ROOT/pages/reactor.adoc b/documentation/modules/ROOT/pages/reactor.adoc new file mode 100644 index 000000000..6a4c60107 --- /dev/null +++ b/documentation/modules/ROOT/pages/reactor.adoc @@ -0,0 +1,23 @@ += Pax Exam Reactor +:navtitle: Reactor + +== Reactor Strategies + +A reactor strategy defines a factory for creating reactors. The reactor strategy determines whether the test container will be stopped and restarted between tests. +The reactor strategy is defined by an annotation on the test class. + +[source,java] +---- +@RunWith(PaxExam.class) +@ExamReactorStrategy(PerMethod.class) +public class ExplodedReferenceTest { + +} +---- + +=== Per Method +With the _Per Method_ strategy, the test container is started and stopped before and after each individual test method. +PerMethod is the default strategy. + +=== Per Class +With the _Per Class_ strategy, the test container is started and stopped before and after running all tests of a given test class. Thus, subsequent test methods are not completely isolated from any side effects of previous methods of the same test class.