Serge Huber created UNOMI-968:
---------------------------------
Summary: Make integration tests pluggable for additional
PersistenceService providers
Key: UNOMI-968
URL: https://issues.apache.org/jira/browse/UNOMI-968
Project: Apache Unomi
Issue Type: Bug
Components: unomi(-core)
Affects Versions: unomi-3.1.0
Reporter: Serge Huber
Assignee: Serge Huber
Fix For: unomi-3.1.0
h2. Summary
Unomi’s runtime persistence is pluggable ({{unomi.persistence;provider:=…}}),
but the Pax Exam integration-test harness is hard-wired to Elasticsearch and
OpenSearch. This improvement generalizes {{BaseIT}} / {{AllITs}} so additional
{{PersistenceService}} implementations can reuse the shared behavioural suite,
while search-cluster-only tests remain explicitly gated.
h2. Motivation (why this helps the whole community)
* The SPI already allows alternate backends. Contributors who prototype or ship
another provider today must *fork or rewrite* a large IT suite (~50 classes)
that already encodes Unomi’s behavioural contracts (profiles, segments, rules,
GraphQL, shell, tenancy, …).
* That duplication raises the contribution bar and makes it harder for the
project to *compare* backends against the same bar used for ES/OS.
* OpenSearch support already shows the limitation: several tests special-case
{{equals("opensearch")}} (for example the 1.6→current migration IT) instead of
expressing *capabilities* such as “supports ES snapshot restore” or “exposes
rollover HTTP APIs”.
* A provider-oriented harness keeps ES/OS as first-class CI cells while
unlocking cleaner modelling for any future in-tree or out-of-tree provider
(JDBC, embedded, cloud-managed stores, research backends, etc.) — without tying
the ticket to a single vendor product.
h2. Problem (current behaviour)
* System property {{unomi.search.engine}} accepts only {{elasticsearch}} |
{{opensearch}}.
* {{BaseIT}} provisions ES/OS features/distributions and waits on search HTTP
{{/_cluster/health}}.
* Unknown engine values fail fast; there is no extension point for a third
provider.
* Suite members such as {{Migrate16xToCurrentVersionIT}}, {{RolloverIT}}, and
parts of {{HealthCheckIT}} assume search-cluster HTTP APIs or search-named
health probes.
h2. Proposed direction
# Introduce a persistence-*provider* oriented IT configuration (exact property
name TBD; keep {{unomi.search.engine}} as a deprecated alias for compatibility).
# Extract a small test-only backend SPI used by {{BaseIT}} (provision options,
distribution feature for {{unomi:setup}}, await-ready, persistence ConfigAdmin
PID, *capabilities*).
# Implement built-in backends for Elasticsearch and OpenSearch with *no
intentional behaviour change* for existing CI cells.
# Classify search-only tests (JUnit categories or a split {{CoreITs}} /
{{SearchBackendITs}} suite) so non-search providers run the behavioural core
without snapshot/rollover/search-health assertions.
# Replace brittle {{opensearch}}-only string checks with capability assumptions
(e.g. {{legacyEsSnapshotMigrate}}, {{indexRolloverPolicies}}).
# Document in {{itests/README.md}} how an additional provider registers a
backend on the Failsafe classpath (ServiceLoader and/or explicit FQCN system
property).
h2. Non-goals
* Shipping a new production persistence module in this issue.
* Requiring every incomplete backend to pass the full suite on day one — the
contract is *reuse + selective exclude*, not instant green for partial SPI
implementations.
* Changing product SPI method contracts beyond what the IT harness needs.
h2. Suggested phases
# Behaviour-preserving extract of ES/OS backends behind {{BaseIT}}.
# Mark/split search-only ITs; document Failsafe excludes.
# Capability-based skips (migration, rollover, health expectations).
# Extension documentation (+ minimal registration example).
h2. Acceptance criteria
* Elasticsearch and OpenSearch integration-test cells remain green with no
intentional product behaviour change.
* {{BaseIT}} resolves providers via a backend SPI (clear error if none
registered), instead of a closed if/else on two engine names only.
* Search-only tests are identifiable (category or separate suite) and
documented.
* Legacy migration / rollover / search-specific health assertions are gated by
capabilities, not only {{searchEngine.equals("opensearch")}}.
* ITs that touch {{org.apache.unomi.persistence.*}} configuration use a single
PID helper.
* {{itests/README.md}} documents third-provider plug-in steps.
* Existing {{unomi.search.engine}} / {{--use-opensearch}} workflows keep
working.
h2. Open questions
* JUnit {{@Category}} vs split suite aggregators?
* Property name: {{unomi.persistence.provider}} vs open-ended
{{unomi.search.engine}}?
* Extension mechanism: {{ServiceLoader}} vs
{{-Dunomi.persistence.it.backend=fqcn}}?
* Should product healthchecks grow a generic backend probe, or only relax IT
assertions?
h2. Related code (starting points)
* {{itests/src/test/java/org/apache/unomi/itests/BaseIT.java}}
* {{itests/src/test/java/org/apache/unomi/itests/AllITs.java}}
* {{itests/src/test/java/org/apache/unomi/itests/RolloverIT.java}}
* {{itests/src/test/java/org/apache/unomi/itests/HealthCheckIT.java}}
*
{{itests/src/test/java/org/apache/unomi/itests/migration/Migrate16xToCurrentVersionIT.java}}
* {{itests/pom.xml}} ({{unomi.search.engine}} / OpenSearch profiles)
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
