This is an automated email from the ASF dual-hosted git repository.
He-Pin pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/pekko.git
The following commit(s) were added to refs/heads/main by this push:
new 0fa5809069 docs: document jackson3 module, JUnit Jupiter test kit and
missing config (#3585)
0fa5809069 is described below
commit 0fa58090695ec831714428628ed9377cc6963e39
Author: PJ Fanning <[email protected]>
AuthorDate: Fri Oct 9 05:33:22 2026 +0100
docs: document jackson3 module, JUnit Jupiter test kit and missing config
(#3585)
Motivation:
The default configuration page says it lists every module's
reference.conf, but actor-testkit-typed, serialization-jackson and
serialization-jackson3 are missing. The new pekko-serialization-jackson3
module and the JUnit Jupiter support in the typed test kit are not
documented outside the release notes.
Modification:
- configuration-reference.md: add sections for pekko-actor-testkit-typed,
pekko-serialization-jackson and pekko-serialization-jackson3
- serialization-jackson.md: add a Jackson 3 section with the
pekko-serialization-jackson3 dependency and how it differs (package,
config path, tools.jackson packages, built-in modules,
datetime-features), and note that only one of the two modules should
be used since they share serializer names and identifiers
- typed/testing-async.md: document TestKitJUnitJupiterExtension,
@JUnitJupiterTestKit, JUnitJupiterTestKitBuilder and
LogCapturingExtension, using the existing example tests, and note the
deprecated JUnit5 variants
- LogCapturingExtensionExampleTest.java: add the missing opening
#log-capturing-junit-jupiter snippet tag
Result:
The configuration reference is complete and the new jackson3 module
and JUnit Jupiter support are documented.
Tests:
- Not run - docs only (plus a snippet tag comment in an example test)
References:
None - found during a review of the docs
---
.../javadsl/LogCapturingExtensionExampleTest.java | 1 +
.../paradox/general/configuration-reference.md | 15 +++++++++++
docs/src/main/paradox/serialization-jackson.md | 30 ++++++++++++++++++++++
docs/src/main/paradox/typed/testing-async.md | 24 +++++++++++++++++
4 files changed, 70 insertions(+)
diff --git
a/actor-testkit-typed/src/test/java/jdocs/org/apache/pekko/actor/testkit/typed/javadsl/LogCapturingExtensionExampleTest.java
b/actor-testkit-typed/src/test/java/jdocs/org/apache/pekko/actor/testkit/typed/javadsl/LogCapturingExtensionExampleTest.java
index f64d69425c..7bf473b4a6 100644
---
a/actor-testkit-typed/src/test/java/jdocs/org/apache/pekko/actor/testkit/typed/javadsl/LogCapturingExtensionExampleTest.java
+++
b/actor-testkit-typed/src/test/java/jdocs/org/apache/pekko/actor/testkit/typed/javadsl/LogCapturingExtensionExampleTest.java
@@ -29,6 +29,7 @@ import org.junit.jupiter.api.extension.ExtendWith;
// test code copied from LogCapturingExampleTest.java
+// #log-capturing-junit-jupiter
@DisplayName("JUnitJupiter log capturing")
@ExtendWith(TestKitJUnitJupiterExtension.class)
@ExtendWith(LogCapturingExtension.class)
diff --git a/docs/src/main/paradox/general/configuration-reference.md
b/docs/src/main/paradox/general/configuration-reference.md
index f48a80f486..d746f8c347 100644
--- a/docs/src/main/paradox/general/configuration-reference.md
+++ b/docs/src/main/paradox/general/configuration-reference.md
@@ -21,6 +21,11 @@ nondeterministic when loading the configuration.`
@@snip [reference.conf](/actor-typed/src/main/resources/reference.conf)
+<a id="config-pekko-actor-testkit-typed"></a>
+### pekko-actor-testkit-typed
+
+@@snip [reference.conf](/actor-testkit-typed/src/main/resources/reference.conf)
+
<a id="config-pekko-cluster-typed"></a>
### pekko-cluster-typed
@@ -106,6 +111,16 @@ nondeterministic when loading the configuration.`
@@snip [reference.conf](/distributed-data/src/main/resources/reference.conf)
+<a id="config-pekko-serialization-jackson"></a>
+### pekko-serialization-jackson
+
+@@snip
[reference.conf](/serialization-jackson/src/main/resources/reference.conf)
+
+<a id="config-pekko-serialization-jackson3"></a>
+### pekko-serialization-jackson3
+
+@@snip
[reference.conf](/serialization-jackson3/src/main/resources/reference.conf)
+
<a id="config-pekko-stream"></a>
### pekko-stream
diff --git a/docs/src/main/paradox/serialization-jackson.md
b/docs/src/main/paradox/serialization-jackson.md
index 45ad2d9ac2..265f5328b0 100644
--- a/docs/src/main/paradox/serialization-jackson.md
+++ b/docs/src/main/paradox/serialization-jackson.md
@@ -16,6 +16,36 @@ To use Jackson Serialization, you must add the following
dependency in your proj
version=PekkoVersion
}
+### Jackson 3
+
+`pekko-serialization-jackson` uses Jackson 2. If you want to use Jackson 3
instead, add the
+`pekko-serialization-jackson3` dependency in place of
`pekko-serialization-jackson`:
+
+@@dependency[sbt,Maven,Gradle] {
+ bomGroup=org.apache.pekko bomArtifact=pekko-bom_$scala.binary.version$
bomVersionSymbols=PekkoVersion
+ symbol1=PekkoVersion
+ value1="$pekko.version$"
+ group="org.apache.pekko"
+ artifact="pekko-serialization-jackson3_$scala.binary.version$"
+ version=PekkoVersion
+}
+
+The rest of this page applies to both modules, with these differences for
`pekko-serialization-jackson3`:
+
+* The classes are in the `org.apache.pekko.serialization.jackson3` package,
for example `JacksonMigration`
+ and `JacksonObjectMapperProvider`.
+* The configuration is under `pekko.serialization.jackson3` instead of
`pekko.serialization.jackson`,
+ see the @ref:[reference
configuration](general/configuration-reference.md#config-pekko-serialization-jackson3).
+* Jackson 3 uses the `tools.jackson` packages (for example
`tools.jackson.databind.ObjectMapper`). The
+ annotations are still in `com.fasterxml.jackson.annotation`.
+* Jackson 3 has built-in support for Java 8 date/time types, `Optional` and
parameter names, so the
+ `JavaTimeModule`, `Jdk8Module` and `ParameterNamesModule` are not registered
in `jackson-modules`. Apart from
+ the Pekko modules, only the Jackson Scala module is registered by default.
The date/time features such as
+ `WRITE_DATES_AS_TIMESTAMPS` are configured in a `datetime-features` section
instead of `serialization-features`.
+
+Both modules register their serializers with the same names (`jackson-json`
and `jackson-cbor`) and the
+same serializer identifiers, so only add one of them to your application.
+
## Introduction
You find general concepts for Pekko serialization in the
@ref:[Serialization](serialization.md) section.
diff --git a/docs/src/main/paradox/typed/testing-async.md
b/docs/src/main/paradox/typed/testing-async.md
index 43cf984481..d937bd2f3f 100644
--- a/docs/src/main/paradox/typed/testing-async.md
+++ b/docs/src/main/paradox/typed/testing-async.md
@@ -137,6 +137,22 @@ Scala
Java
: @@snip
[AsyncTestingExampleTest.java](/actor-testkit-typed/src/test/java/jdocs/org/apache/pekko/actor/testkit/typed/javadsl/JunitIntegrationExampleTest.java)
{ #junit-integration }
+@@@ div { .group-java }
+
+If you are using JUnit Jupiter (JUnit 5 or later), annotate the test class with
+`@ExtendWith(TestKitJUnitJupiterExtension.class)` and the test kit field with
`@JUnitJupiterTestKit`.
+@javadoc[JUnitJupiterTestKitBuilder](pekko.actor.testkit.typed.javadsl.JUnitJupiterTestKitBuilder)
creates the test kit,
+optionally with a custom name, configuration or existing `ActorSystem`. The
extension shuts down the test kit after
+all tests in the class have run.
+
+@@snip
[JUnitJupiterIntegrationExampleTest.java](/actor-testkit-typed/src/test/java/jdocs/org/apache/pekko/actor/testkit/typed/javadsl/JUnitJupiterIntegrationExampleTest.java)
{ #junit-jupiter-integration }
+
+The dependency on JUnit Jupiter is also marked as optional from the test kit
module, so your project must explicitly
+include a dependency on `junit-jupiter` to use this. The earlier
`TestKitJUnit5Extension`, `@JUnit5TestKit` and
+`JUnit5TestKitBuilder` are deprecated in favour of these.
+
+@@@
+
As you may have noticed
@scaladoc[ScalaTestWithActorTestKit](pekko.actor.testkit.typed.scaladsl.ScalaTestWithActorTestKit)
is an abstract class
which means its problematic if you want treat a given test suite as a value
and extend it in multiple ways (i.e. as an example you happen to be using
[testcontainers-scala](https://github.com/testcontainers/testcontainers-scala)
and hypothetically you want to extend the same test for each different type of
database
@@ -261,6 +277,14 @@ Scala
Java
: @@snip
[LogCapturingExampleTest.java](/actor-testkit-typed/src/test/java/jdocs/org/apache/pekko/actor/testkit/typed/javadsl/LogCapturingExampleTest.java)
{ #log-capturing }
+@@@ div { .group-java }
+
+With JUnit Jupiter, register the `LogCapturingExtension` with `@ExtendWith`
instead of using a `@Rule`:
+
+@@snip
[LogCapturingExtensionExampleTest.java](/actor-testkit-typed/src/test/java/jdocs/org/apache/pekko/actor/testkit/typed/javadsl/LogCapturingExtensionExampleTest.java)
{ #log-capturing-junit-jupiter }
+
+@@@
+
Then you also need to configure the `CapturingAppender` and
`CapturingAppenderDelegate` in
`src/test/resources/logback-test.xml`:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
