This is an automated email from the ASF dual-hosted git repository.
reschke pushed a commit to branch trunk
in repository https://gitbox.apache.org/repos/asf/jackrabbit-oak.git
The following commit(s) were added to refs/heads/trunk by this push:
new 36f05bf351 OAK-10983: DocumentNodeStore: improve documentation about
testing (#1611)
36f05bf351 is described below
commit 36f05bf351c3d925a399e142d7cae95df448c36e
Author: Julian Reschke <resc...@apache.org>
AuthorDate: Thu Aug 1 10:03:32 2024 +0200
OAK-10983: DocumentNodeStore: improve documentation about testing (#1611)
---
oak-doc/src/site/markdown/testing.md | 22 +++++++++++++++++-----
1 file changed, 17 insertions(+), 5 deletions(-)
diff --git a/oak-doc/src/site/markdown/testing.md
b/oak-doc/src/site/markdown/testing.md
index af4f7c77b7..036c63b6c2 100644
--- a/oak-doc/src/site/markdown/testing.md
+++ b/oak-doc/src/site/markdown/testing.md
@@ -15,23 +15,22 @@
limitations under the License.
-->
-Testing using different NodeStore fixtures
----------------
+# Testing using different NodeStore fixtures
In Jackrabbit Oak unit and integration tests are run using different fixtures
which represent configurations of the NodeStore underlying storage for the
content repository.
This ensures that there is a fixed environment in which tests are run and the
results are consistent and repeatable across different runs.
The default fixture used when running `mvn clean install` is `SEGMENT_TAR`
which uses the SegmentNodeStore with the local storage with TAR files.
-To run the tests using a different fixture, you can use the following command:
`mvn clean install -Dfixture=<FIXTURE>`.
-You can also update the `pom.xml` file to use a different fixture by updating
the `fixture` property in the `oak-parent/pom.xml` file. If you want to run
using multiple fixtures, provide a space separated list of fixtures.
+To run the tests using a different fixture, you can use the following command:
`mvn clean install -Dnsfixtures=<FIXTURE>`.
+You can also update the `pom.xml` file to use a different fixture by updating
the `fixture` property in the `oak-parent/pom.xml` file. If you want to run
using multiple fixtures, provide a comma separated list of fixtures.
These are the possible fixtures that can be used:
- `SEGMENT_TAR` - Uses the SegmentNodeStore with the local storage with TAR
files.
- `SEGMENT_AWS` - Uses the SegmentNodeStore with the AWS backend.
- `SEGMENT_AZURE` - Uses the SegmentNodeStore with the Azure backend.
- `DOCUMENT_NS` - Uses the DocumentNodeStore with MongoDB as the underlying
storage engine. This requires a running instance of MongoDB.
-- `DOCUMENT_RDB` - Uses the DocumentNodeStore with the relational databases
such as PostgreSQL, MySQL as underlying storage engine.
+- `DOCUMENT_RDB` - Uses the DocumentNodeStore with the relational databases
such as PostgreSQL, MySQL as underlying storage engine. Note that in general,
this requires adding JDBC drivers to the class path (see the `rdb-` profiles in
the parent POM), and running the specified database engine in the local
network. A notable exception is Derby, which uses the local file system. Also,
JDBC URL, user name and password need to be specified as system properties
`rdb.jdbc-url`, `rdb.jdbc-user` [...]
- `DOCUMENT_MEM` - Uses the DocumentNodeStore with the in-memory backend. This
can be used for running tests that do not require persistence.
- `MEMORY_NS` - Uses the MemoryNodeStore with the in-memory backend which is
more lightweight than DocumentNodeStore but is not as feature-rich.
- `COMPOSITE_SEGMENT` - Uses the CompositeNodeStore which allows combining
multiple underlying segment stores into a single logical repository. It is
useful in scenarios where different parts of the content tree have different
storage requirements. For example, frequently accessed content can be stored in
a high-performance segment store, while less frequently accessed content can be
stored in a more cost-effective storage backend.
@@ -40,5 +39,18 @@ These are the possible fixtures that can be used:
Note that the [Jenkins
job](https://github.com/apache/jackrabbit-oak/blob/trunk/Jenkinsfile) that is
run as part of the CI flow use both `SEGMENT_TAR` and `DOCUMENT_NS` fixtures to
run the tests.
+## Special case: DocumentNodeStore tests
+For these tests, the base test class attempts to instantiate _all_ potential
implementations. Thus, the tests usually run minimally with `DOCUMENT_NS` and
`DOCUMENT_RDB` for H2DB (which is embeded).
+## Special case: MongoDB tests
+
+The test fixture for MongoDB attempts to access a local MongoDB instance, and
otherwise attempts to start a Docker image (the latter case will make things
slower due to startup times). If both fail, tests will not run.
+
+## Special case: RDB tests
+
+When adding database drivers using the test profiles, such as `-Prdb-derby`,
size checks on the "oak-run" project may fail. As a workaround, just specify a
larger limit, such as with `-Dmax.jar.size=200000000`.
+
+Example:
+
+`mvn clean install -PintegrationTesting -Prdb-derby -Dnsfixtures=DOCUMENT_RDB
"-Drdb.jdbc-url=jdbc:derby:./target/derby-test;create=true"
-Dmax.jar.size=200000000`
\ No newline at end of file
