Evaluate and select HTTP mock and Cucumber BDD framework for registry-loader integration tests

[jordanpadams]

Summary

Evaluate candidate frameworks for building a self-contained integration test suite for registry-loader. The approach should use an HTTP-level mock (e.g. WireMock, MockServer) to intercept OpenSearch REST calls — rather than testcontainers with a clean OpenSearch instance — because real-world production issues often involve quirks of specific OpenSearch deployments (throttling, OCU limits, partial bulk failures, 409 conflicts) that a clean instance would not reproduce.

Additionally, evaluate Cucumber as the BDD test framework to align with other PDS software repositories that use it.

Acceptance Criteria

• A written recommendation (ADR or design note in the repo) comparing at least two HTTP mock frameworks (e.g. WireMock vs MockServer) against registry-loader's specific needs
• Cucumber evaluated for fit as the BDD layer on top of the chosen mock framework
• Recommendation includes: ease of simulating partial bulk API failures and error responses, CI footprint (no Docker required), compatibility with the existing Maven build
• Decision is documented and linked to the parent theme

---

For Internal Dev Team To Complete

⚙️ Engineering Details

🎉 Integration & Test

🤖 Generated with Claude Code

[al-niessner]

@jordanpadams
What is the value of cucumber here? Cucumber model is correct -> define input and output expectation, but not sure the actual toolset works well with a mock opensearch. In this instance, we have input, mock parameters (how much of opensearch to mock and what to make flaky for a test), and output expectation. Do mock parameters equate to input as well? In terms of Cucumber, StepDef would have a static monolithic opensearch mock, but for broader testing a set of smaller mocks derived from standard mock would be more efficient and maintainable.

[jordanpadams]

Good pushback — you're identifying the real problem, which is a large monolithic mock that becomes impossible to maintain and reason about as the test suite grows. That's the thing to avoid regardless of which framework we land on.

The core requirement driving the framework question is traceability and reportability: every test run should produce a report where each test case is clearly tied back to the issue or requirement it covers. That's the main reason Cucumber has come up — .feature files make that link explicit and readable by non-engineers. But Cucumber isn't the only way to get there.

A few options worth evaluating:

1. Cucumber with a composable mock fixture library — directly addresses the monolithic mock concern. Build a small library of named OpenSearch behaviors (conflict(), throttle(), partialFailure(), etc.) that each scenario composes from. No scenario owns a full mock; they just pick the behaviors they need. Keeps Cucumber's traceability while staying maintainable.

2. JUnit 5 with Allure or Surefire reporting — perfectly fine if the team prefers to stay closer to plain Java. The traceability requirement can still be met with @DisplayName, @Tag, and a reporting plugin that links test names to issue numbers. Slightly less readable for non-engineers but simpler to implement and maintain.

Bottom line: we're flexible on the specific framework. What we need to preserve is that each test maps to a named requirement or bug, and the CI report makes that visible. How that gets implemented is the implementer's call — the evaluation task (#139) is the right place to make that decision with a concrete recommendation.

🤖 Generated with help from Claude Code