(causeway) 04/06: docs(openspec): propose restoring outbox REST client tests

[da...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch htmx
in repository https://gitbox.apache.org/repos/asf/causeway.git

commit edb72e5b2f64b953437d6d8f9adb78047080c8ef
Author: Dan Haywood <da...@haywood-associates.co.uk>
AuthorDate: Sat Aug 29 21:45:05 2026 +0200

    docs(openspec): propose restoring outbox REST client tests
---
 .../.openspec.yaml                                 |  2 +
 .../design.md                                      | 80 ++++++++++++++++++++++
 .../proposal.md                                    | 29 ++++++++
 .../spec.md                                        | 72 +++++++++++++++++++
 .../tasks.md                                       | 17 +++++
 5 files changed, 200 insertions(+)

diff --git a/openspec/changes/restore-execution-outbox-restclient-tests/.openspec.yaml b/openspec/changes/restore-execution-outbox-restclient-tests/.openspec.yaml
new file mode 100644
index 00000000000..50adc91034f
--- /dev/null
+++ b/openspec/changes/restore-execution-outbox-restclient-tests/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-29
diff --git a/openspec/changes/restore-execution-outbox-restclient-tests/design.md b/openspec/changes/restore-execution-outbox-restclient-tests/design.md
new file mode 100644
index 00000000000..e23a2734670
--- /dev/null
+++ b/openspec/changes/restore-execution-outbox-restclient-tests/design.md
@@ -0,0 +1,80 @@
+## Context
+
+`RestEasyConfiguration` was removed by `d241d3d918bc` on 7 July 2025 in favor of the Restful Objects configuration exposed through `CausewayConfiguration` and `RestfulPathProvider`.
+The execution-outbox REST client test helper retained the removed type, while its integration test also retained obsolete Spring Boot imports for `EntityScan` and `LocalServerPort`.
+
+The module has declared `<maven.test.skip>true</maven.test.skip>` since 3 July 2025.
+That property skips test-source compilation as well as execution, so normal `mvn clean install` builds report success while the disabled sources do not compile.
+Forcing `-Dmaven.test.skip=false test-compile` currently exposes these failures before any runtime test diagnosis can occur.
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Compile the integration-test sources against the current Causeway and Spring Boot APIs.
+- Derive the REST endpoint from the same canonical Restful Objects base-path configuration used by production infrastructure.
+- Restore the existing integration suite to ordinary Maven and reactor participation.
+- Diagnose and fix runtime failures revealed after compilation without weakening the assertions.
+
+**Non-Goals:**
+
+- Changing the production `OutboxClient` API or wire protocol.
+- Restoring `RestEasyConfiguration` or introducing a RESTEasy-specific compatibility layer.
+- Changing the default `/restful` endpoint, web context-path rules, authentication policy, or outbox persistence semantics.
+- Replacing the current Restful Objects viewer implementation.
+
+## Decisions
+
+### Use `RestfulPathProvider` as the endpoint-path boundary
+
+`RestEndpointService` will depend on the current `org.apache.causeway.core.config.applib.RestfulPathProvider` rather than reading removed RESTEasy configuration.
+It will use `getRestfulPath().orElse("")`, combine that path with `WebAppContextPath`, and retain the existing trailing slash expected by `OutboxClient`.
+
+This follows the migration used by `TemplateResourceServlet` in the removal commit and keeps the test helper aligned with the canonical Restful Objects base path.
+Injecting the provider is preferred to recreating removed configuration structure or hard-coding `/restful`.
+
+### Migrate test annotations to current Spring Boot packages
+
+`EntityScan` will come from `org.springframework.boot.persistence.autoconfigure` and `LocalServerPort` from `org.springframework.boot.test.web.server`.
+No compatibility reflection or duplicate annotations will be introduced.
+These packages are already used by active modules in the repository.
+
+### Separate compile restoration from runtime restoration
+
+Implementation will first run test compilation with `-Dmaven.test.skip=false` while the POM suppression still exists.
+After all sources compile, the integration suite will run explicitly and any runtime failures will be diagnosed against the original assertions and fixture lifecycle.
+The skip property and its stale TODO will be removed only after focused tests pass.
+
+This ordering distinguishes source migration failures from application-context, endpoint, transaction, or delivery failures.
+
+### Re-enable tests through ordinary Maven lifecycle configuration
+
+The module-level `maven.test.skip` property will be removed rather than replaced with another default skip mechanism.
+Developers may still use standard command-line skip flags for local builds, but repository defaults must compile and execute the suite.
+Module `test`, `verify`, and root-reactor builds will therefore regain coverage.
+
+## Risks / Trade-offs
+
+- [Risk] Compiling the sources may reveal additional platform migrations beyond the three known stale imports.
+  → Mitigation: force `test-compile` first and resolve each error using current APIs already established elsewhere in the repository.
+- [Risk] Runtime failures may have been the original reason for suppressing the suite.
+  → Mitigation: preserve assertions, inspect server and client behavior, and fix deterministic setup or production regressions instead of reinstating a skip.
+- [Risk] Re-enabling integration tests increases reactor duration.
+  → Mitigation: keep the suite focused, reuse its current application context, and verify that it has bounded deterministic waits and cleanup.
+- [Risk] Endpoint path assembly could introduce missing or duplicate slashes.
+  → Mitigation: preserve `WebAppContextPath.prependContextPath` and the existing single trailing-slash client contract, with focused assertions where practical.
+
+## Migration Plan
+
+1. Update current API imports and endpoint-path injection.
+2. Force test-source compilation while overriding the existing skip.
+3. Run and repair the focused integration suite.
+4. Remove `maven.test.skip` and its TODO.
+5. Verify module test, install, RAT, and applicable reactor behavior with default settings.
+
+Rollback consists of reverting the source and POM changes together; restoring a default test skip is not an acceptable completed state.
+
+## Open Questions
+
+None at proposal time.
+Runtime failures discovered after compilation will be treated as implementation findings and will update the design only if they require a change in scope or behavior.
diff --git a/openspec/changes/restore-execution-outbox-restclient-tests/proposal.md b/openspec/changes/restore-execution-outbox-restclient-tests/proposal.md
new file mode 100644
index 00000000000..ff9096adba2
--- /dev/null
+++ b/openspec/changes/restore-execution-outbox-restclient-tests/proposal.md
@@ -0,0 +1,29 @@
+## Why
+
+The execution-outbox REST client integration-test module has skipped all test compilation and execution since July 2025, masking source breakage caused by the RESTEasy configuration removal and Spring Boot package migrations.
+Restoring this suite is necessary so normal reactor builds verify that outbox entries can still be delivered through the configured Restful Objects endpoint.
+
+## What Changes
+
+- Replace the removed `RestEasyConfiguration` dependency in the integration-test endpoint helper with the current Restful Objects path configuration contract.
+- Update stale Spring Boot test imports, including `EntityScan` and `LocalServerPort`, to their current packages.
+- Force the integration-test sources to compile during implementation and resolve any additional compile-time migration failures exposed by doing so.
+- Run and repair the execution-outbox REST client integration tests while preserving their original delivery, authentication, transaction, and cleanup intent.
+- Remove the module-level `maven.test.skip` suppression after the suite compiles and passes, so ordinary module and reactor builds exercise it.
+- Add focused regression coverage or build assertions where needed to prevent test-source compilation from being silently disabled again.
+
+## Capabilities
+
+### New Capabilities
+
+- `execution-outbox-restclient-integration-tests`: Defines compilation, endpoint-path configuration, execution, and reactor participation requirements for the execution-outbox REST client integration suite.
+
+### Modified Capabilities
+
+None.
+
+## Impact
+
+The change affects `extensions/core/executionoutbox/restclient` test sources and Maven configuration.
+It uses the existing `CausewayConfiguration` and `RestfulPathProvider` APIs and current Spring Boot test annotations without changing production REST client APIs, endpoint defaults, authentication behavior, or outbox persistence semantics.
+Normal builds may take longer because the previously suppressed integration suite will execute again.
diff --git a/openspec/changes/restore-execution-outbox-restclient-tests/specs/execution-outbox-restclient-integration-tests/spec.md b/openspec/changes/restore-execution-outbox-restclient-tests/specs/execution-outbox-restclient-integration-tests/spec.md
new file mode 100644
index 00000000000..da3fd0cfd03
--- /dev/null
+++ b/openspec/changes/restore-execution-outbox-restclient-tests/specs/execution-outbox-restclient-integration-tests/spec.md
@@ -0,0 +1,72 @@
+## ADDED Requirements
+
+### Requirement: Current-platform integration-test compilation
+The execution-outbox REST client integration-test sources SHALL compile against the repository's current Causeway and Spring Boot APIs without relying on removed types or obsolete package locations.
+
+#### Scenario: Test sources are compiled explicitly
+- **WHEN** Maven runs `test-compile` for the module with test skipping disabled
+- **THEN** `RestEndpointService` resolves the current Restful Objects path contract
+- **AND** the integration test resolves current `EntityScan` and `LocalServerPort` annotations
+- **AND** no source references `RestEasyConfiguration`
+
+#### Scenario: Further stale APIs are exposed
+- **WHEN** forced test compilation reveals another removed or relocated platform API
+- **THEN** the test source migrates to the current supported API
+- **AND** compilation is not bypassed through exclusion, reflection, or another skip property
+
+### Requirement: Canonical configured REST endpoint
+The integration-test endpoint helper SHALL construct the `OutboxClient` base URI from the random server port, current web application context path, and canonical configured Restful Objects path.
+It MUST preserve the client contract of one usable trailing path separator without hard-coding the default endpoint.
+
+#### Scenario: Default Restful Objects path is used
+- **WHEN** the test application uses the default Restful Objects base path
+- **THEN** the client targets that path beneath the current web context
+- **AND** outbox calls do not depend on removed RESTEasy configuration
+
+#### Scenario: Restful Objects path is configured
+- **WHEN** the test application supplies a non-default Restful Objects base path
+- **THEN** the helper derives the client URI from that configured path
+- **AND** does not silently fall back to `/restful`
+
+#### Scenario: Application context path is configured
+- **WHEN** the web application has a non-empty context path
+- **THEN** the endpoint URI contains both the context path and Restful Objects path exactly once
+- **AND** remains a valid absolute client base URI
+
+### Requirement: Default Maven lifecycle participation
+The execution-outbox REST client module SHALL compile and execute its integration tests through the ordinary Maven lifecycle by default.
+Repository POM configuration MUST NOT set `maven.test.skip` or an equivalent default suppression for this suite.
+
+#### Scenario: Module test lifecycle runs
+- **WHEN** a developer runs the module's ordinary Maven test or verify lifecycle without skip flags
+- **THEN** test sources compile
+- **AND** the execution-outbox REST client integration tests execute
+
+#### Scenario: Root reactor runs
+- **WHEN** the module participates in the repository's ordinary reactor build
+- **THEN** its test compilation and execution failures fail the build
+- **AND** stale test sources cannot remain hidden behind a successful reactor result
+
+#### Scenario: Developer explicitly skips tests
+- **WHEN** a developer supplies a standard Maven command-line test-skip option
+- **THEN** Maven retains its standard explicit skip behavior
+- **AND** repository defaults remain test-enabled for subsequent builds
+
+### Requirement: Restored outbox delivery regression coverage
+The re-enabled integration suite SHALL preserve verification of execution-outbox recording and REST-client delivery through the running application.
+Fixes MUST retain authorization, transaction, ordering, and cleanup assertions unless an explicit specification change supersedes them.
+
+#### Scenario: Recorded interactions are delivered
+- **WHEN** the test creates publishable interactions and invokes the REST outbox client with valid credentials
+- **THEN** the client receives and acknowledges the expected outbox entries
+- **AND** persisted entry state reflects successful delivery according to the existing contract
+
+#### Scenario: Runtime setup fails
+- **WHEN** application startup, persistence, authentication, endpoint routing, serialization, or cleanup no longer satisfies the existing test contract
+- **THEN** the focused integration test fails with a diagnosable error
+- **AND** the implementation corrects the deterministic regression rather than disabling the suite
+
+#### Scenario: Suite completes
+- **WHEN** the focused integration suite finishes successfully
+- **THEN** created domain and outbox state is isolated or cleaned according to the existing fixture lifecycle
+- **AND** repeated module runs do not depend on stale state or execution order
diff --git a/openspec/changes/restore-execution-outbox-restclient-tests/tasks.md b/openspec/changes/restore-execution-outbox-restclient-tests/tasks.md
new file mode 100644
index 00000000000..e7d8176a7b0
--- /dev/null
+++ b/openspec/changes/restore-execution-outbox-restclient-tests/tasks.md
@@ -0,0 +1,17 @@
+## 1. Restore test-source compilation
+
+- [ ] 1.1 Replace `RestEasyConfiguration` in `RestEndpointService` with the current `RestfulPathProvider` contract while preserving context-path and trailing-slash URI assembly.
+- [ ] 1.2 Migrate `EntityScan`, `LocalServerPort`, and any other stale test imports to current Spring Boot and Causeway APIs.
+- [ ] 1.3 Run forced test compilation with `-Dmaven.test.skip=false` and resolve every remaining compile error without excluding sources or weakening compiler checks.
+
+## 2. Restore integration behavior
+
+- [ ] 2.1 Run the focused execution-outbox REST client integration suite and diagnose application-context, endpoint, authentication, persistence, transaction, serialization, and cleanup failures.
+- [ ] 2.2 Fix deterministic runtime regressions while preserving the existing outbox recording, delivery, acknowledgment, ordering, and authorization assertions.
+- [ ] 2.3 Add or refine focused endpoint-path and repeated-run coverage where needed to protect configured-path composition and fixture isolation.
+
+## 3. Re-enable default lifecycle coverage
+
+- [ ] 3.1 Remove the module-level `maven.test.skip` property and stale TODO after focused compilation and tests pass.
+- [ ] 3.2 Verify the module's default `test`, `verify`, install, and RAT lifecycles execute the restored suite successfully without command-line skip overrides.
+- [ ] 3.3 Run the applicable parent-reactor build, strict OpenSpec validation, IntelliJ compilation or inspections, and diff checks to confirm the module can no longer hide stale test sources.