This is an automated email from the ASF dual-hosted git repository.
jsedding pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/sling-site.git
The following commit(s) were added to refs/heads/master by this push:
new 2657916 SLING-9795 - JUnit 5 support for server-side tests (#50)
2657916 is described below
commit 2657916a411457f3940cdf11e6f2e64d4d7c74eb
Author: Julian Sedding <[email protected]>
AuthorDate: Wed Oct 21 12:05:13 2020 +0200
SLING-9795 - JUnit 5 support for server-side tests (#50)
* SLING-9795 - JUnit 5 support for server-side tests
- documentation update
---
.../bundles/org-apache-sling-junit-bundles.md | 71 +++++++++++++++++++++-
1 file changed, 70 insertions(+), 1 deletion(-)
diff --git
a/src/main/jbake/content/documentation/bundles/org-apache-sling-junit-bundles.md
b/src/main/jbake/content/documentation/bundles/org-apache-sling-junit-bundles.md
index 9892443..e9ceb7d 100644
---
a/src/main/jbake/content/documentation/bundles/org-apache-sling-junit-bundles.md
+++
b/src/main/jbake/content/documentation/bundles/org-apache-sling-junit-bundles.md
@@ -11,7 +11,7 @@ provide different examples including HTTP-based and
server-side teleported tests
bundle module, running against a full Sling instance setup in the same Maven
module.
## org.apache.sling.junit.core: server-side JUnit tests support
-This bundle provides a `JUnitServlet` that runs JUnit tests found in bundles.
+This bundle provides a `JUnitServlet` that runs JUnit tests found in bundles.
Both JUnit 4 tests and (optionally) JUnit 5 tests (aka Jupiter) are supported.
<div class="warning">
Note that the JUnitServlet does not require authentication, so it would allow
any client to run tests. The servlet can be disabled by configuration if
needed, but in general the `/system` path should not be accessible to website
visitors anyway.
@@ -27,6 +27,75 @@ the test class names, like for example:
Sling-Test-Regexp=com.example.*ServerSideTest
+### JUnit 4 Support
+All that is required is the installation of the the Apache Sling JUnit Core
bundle. The bundle exports the packages `junit.*`, `org.junit.*` and
additionally `org.hamcrest.*`.
+
+Note however that the `org.junit.platform.*` packages, which contain the
generic testing platform developed for JUnit 5, are NOT exported.
+
+If you want to run JUnit 4 tests side-by-side with JUnit 5 tests, please refer
to the next section.
+
+### JUnit 5 Support (since version 1.1.0)
+
+The Apache Sling JUnit Core bundle has a number of optional imports. JUnit 5
support is automatically enabled when these optional imports are satisfied.
+
+Note that a restart of the Apache Sling JUnit Core bundle is required if the
optional dependencies are installed after the bundle was resolved.
+
+The next sections provide a high level overview of the JUnit 5 architecture
and list the additional bundles that must be deployed in order to run tests on
the JUnit Platform.
+
+#### Background on JUnit 5
+
+JUnit 5 is composed of three main components, each of which is composed of
several bundles:
+
+> **JUnit 5 = _JUnit Platform_ + _JUnit Jupiter_ + _JUnit Vintage_**
+
+Source: [JUnit 5 User Guide - What is JUnit
5?](https://junit.org/junit5/docs/current/user-guide/#overview-what-is-junit-5)
+
+[JUnit Platform](#junit-platform): a generic platform for launching testing
frameworks that defines the `TestEngine` API, an extension point for hooking in
arbitrary ways of describing tests.
+
+[JUnit Jupiter](#bundles-for-the-junit-jupiter-engine-junit-5): a `TestEngine`
that can run Jupiter based tests on the platform. I.e. it runs tests that are
coloquially referred to as JUnit 5 tests.
+
+[JUnit Vintage](#bundles-for-the-junit-vintage-engine-junit-4): a `TestEngine`
that can run JUnit 3 and JUnit 4 based tests on the platform.
+
+#### JUnit Platform
+
+The optional imports of the Apache Sling JUnit Core bundle are for the JUnit
Platform. The bundle is agnostic of the actual `TestEngine` implementations.The
following four bundles need to be deployed:
+
+- org.opentest4j:opentest4j
+- org.junit.platform:junit-platform-commons
+- org.junit.platform:junit-platform-engine
+- org.junit.platform:junit-platform-launcher
+
+<div class="note">
+Note: `junit-platform-commons` version 1.7.0 cannot be deployed using Sling's
OSGi Installer, due to [junit5 issue
#2438](https://github.com/junit-team/junit5/issues/2438). Other JUnit5 bundles
_may_ be affected by the same issue.
+</div>
+
+However, in order to run tests at least one implementation of
`org.junit.platform.engine.TestEngine` needs to be available. Both [JUnit
Jupiter](#bundles-for-the-junit-jupiter-engine-junit-5) and [JUnit
Vintage](#bundles-for-the-junit-vintage-engine-junit-4) provide a test engine,
so at least one of the two needs to be deployed.
+
+Custom or other other 3rd party `TestEngine` implementations should be able to
hook in transparently, provided they are advertised using Java's
`ServiceLoader` mechanism. Apache Sling Junit Core takes care of detecting test
engines in other installed bundles and automatically makes them available for
test execution.
+
+#### Bundles for the JUnit Jupiter Engine (JUnit 5)
+
+The JUnit Jupiter engine enables the new Jupiter style (or JUnit 5 style) for
writing unit tests.
+
+In addition to the [JUnit Platform bundles](#junit-platform) the following
bundles need to be deployed:
+
+- org.junit.jupiter:junit-jupiter-api
+- org.junit.jupiter:junit-jupiter-engine
+- (optional) org.junit.jupiter:junit-jupiter-params
+- (optional) org.junit.jupiter:junit-jupiter-migrationsupport
+
+#### Bundles for the JUnit Vintage Engine (JUnit 4)
+
+The JUnit Vintage engine provides a backwards compatibility layer to allow
running JUnit 4 tests on the new JUnit Platform.
+
+In addition to the [JUnit Platform bundles](#junit-platform) the following
bundle needs to be deployed:
+
+- org.junit.vintage:junit-vintage-engine
+
+<div class="note">
+Note: the JUnit Vintage engine is only required if JUnit 4 and JUnit 5 tests
should be executed side-by-side. For plain JUnit 4 support _only_ the Apache
Sling JUnit Core bundle needs to be installed. For plain Jupiter (or JUnit 5)
tests, see [JUnit Jupiter](#bundles-for-the-junit-jupiter-engine-junit-5).
+</div>
+
### The TeleporterRule
The `TeleporterRule` supplied by this bundle (since V1.0.12) makes it easy to
write such tests, as it takes care of
