You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@sling.apache.org by js...@apache.org on 2020/10/21 10:05:21 UTC
[sling-site] branch master updated: SLING-9795 - JUnit 5 support
for server-side tests (#50)
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 <js...@apache.org>
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