aw-spec-cli 0.1.10 → 0.1.11

package/assets/guardrails/technology/java-spring/testing.md

@@ -0,0 +1,601 @@
+# Testing Strategy — Java · DDD · Hexagonal Architecture (Ports & Adapters)
+
+> **Domain-agnostic.** This document defines testing standards applicable to any Java project
+> structured around Domain-Driven Design and Hexagonal Architecture.
+
+---
+
+## 1. Core Philosophy
+
+| Principle | Rule |
+|-----------|------|
+| **Test-First Engineering** | Tests MUST be written and verified to fail before the production change is in place. |
+| **Right test at the right level** | Domain logic → pure unit tests. Application orchestration → unit tests. Adapter logic → integration/slice tests. No cross-layer leakage. |
+| **Tests as executable specification** | Test names describe business behaviour or externally observable technical behaviour, not implementation details. |
+| **Determinism** | Time, randomness, and identity generation are always injected. Production code MUST NOT directly create non-deterministic values inside business/application logic. |
+| **Same-commit discipline** | Any change to an aggregate invariant, port contract, Result contract, or error representation MUST include the corresponding test update in the same commit. |
+| **No production data in tests** | Tests use synthetic fixture data only. Production data MUST NOT appear in development, test, demo, or CI environments. |
+
+---
+
+## 2. Architecture Layers and Their Test Owners
+
+```text
+┌──────────────────────────────────────────────────┐
+│             Driving Adapters (Primary)           │
+│        [ Controller Slice Tests / E2E ]          │
+├──────────────────────────────────────────────────┤
+│           Application Layer (Use Cases)          │
+│        [ Application Service Unit Tests ]        │
+├──────────────────────────────────────────────────┤
+│              Domain Layer (Core)                 │
+│           [ Pure Domain Unit Tests ]             │
+├──────────────────────────────────────────────────┤
+│          Driven Adapters (Secondary)             │
+│       [ Persistence / Adapter Integration ]      │
+└──────────────────────────────────────────────────┘
+````
+
+Domain unit tests MUST remain framework-independent.
+
+Application unit tests SHOULD remain independent of Spring infrastructure wherever the
+application implementation permits it. Spring-specific wiring is tested separately through
+appropriate integration or slice tests.
+
+Driven adapters are tested against real infrastructure through Testcontainers where
+infrastructure behaviour is relevant. H2 MUST NOT be used as a substitute for PostgreSQL
+integration testing.
+
+---
+
+## 3. Test Types Reference
+
+| Test Type                | Layer               | Framework                                    | Spring Context | I/O                 |
+| ------------------------ | ------------------- | -------------------------------------------- | -------------- | ------------------- |
+| Domain unit              | Domain              | JUnit 5                                      | ❌ None         | ❌ None              |
+| Application service unit | Application         | JUnit 5 + Mockito                            | ❌ None         | ❌ Mocked ports only |
+| Controller slice         | Primary Adapter     | `@WebMvcTest` + MockMvc                      | ✅ Slice        | ❌ Use case mocked   |
+| Persistence integration  | Secondary Adapter   | `@DataJpaTest` + Testcontainers              | ✅ Slice        | ✅ Real DB           |
+| Full integration         | All layers          | `@SpringBootTest` + Testcontainers           | ✅ Full         | ✅ Real DB           |
+| Architecture             | Cross-cutting       | ArchUnit                                     | ❌ None         | ❌ None              |
+| Result Mapping           | HTTP/Infrastructure | JUnit 5 + Spring test support where required | As required    | Usually ❌           |
+| Problem Details          | HTTP/Infrastructure | JUnit 5 + MockMvc where required             | As required    | Usually ❌           |
+
+---
+
+## 4. Domain Unit Tests
+
+### Rules
+
+* No Spring context. No Mockito. No I/O.
+* Test every aggregate **state transition**, **invariant enforcement**, and **domain event emission**.
+* Test every **value object**: construction, equality, and rejection of invalid values.
+* Test every **domain specification / policy**.
+* Use only plain Java and the domain model itself.
+* Domain tests MUST NOT depend on Result Mapping, Problem Details, HTTP, Spring Web, SLF4J, Logback, or other infrastructure concerns.
+
+### Mandatory Coverage
+
+* Every aggregate command method → at least one positive and one negative test.
+* Every value object constructor with invalid input → rejection verified.
+* Every invariant violation → appropriate domain failure behaviour verified.
+* Every domain event-producing behaviour → event emission verified.
+
+The exact failure representation MUST follow the application's established domain error model.
+Tests MUST NOT require exceptions merely because a scenario represents failure if the application
+uses explicit Result-based failure semantics.
+
+### Naming Convention
+
+```text
+should_[expected outcome]_when_[condition]
+```
+
+### Determinism Rule
+
+Time and identity generation MUST be injectable when required by the system under test.
+
+Use `java.time.Clock` directly where appropriate, or an application-defined time abstraction when
+additional control is required.
+
+Example:
+
+```java
+Clock fixedClock =
+    Clock.fixed(
+        Instant.parse("2025-01-01T00:00:00Z"),
+        ZoneOffset.UTC
+    );
+
+IdGenerator fixedIds =
+    () -> UUID.fromString("00000000-0000-0000-0000-000000000001");
+```
+
+Production domain/application code MUST NOT directly call:
+
+```java
+LocalDateTime.now();
+Instant.now();
+UUID.randomUUID();
+```
+
+when doing so would make business/application behaviour non-deterministic.
+
+### Structure Example
+
+```java
+@DisplayName("Registration Aggregate")
+class RegistrationTest {
+
+    @Test
+    void should_reject_registration_when_capacity_is_full() {
+
+        // Arrange
+        var event =
+            EventBuilder.anEventWithCapacity(1)
+                .withOneExistingRegistration()
+                .build();
+
+        // Act
+        var result = event.register(aParticipant(), fixedClock);
+
+        // Assert
+        assertThat(result.isFailure()).isTrue();
+        assertThat(result.error()).isEqualTo(CapacityExceededError.INSTANCE);
+    }
+
+    @Test
+    void should_emit_domain_event_when_registration_succeeds() {
+
+        // Arrange
+        var event = EventBuilder.anEventWithCapacity(10).build();
+
+        // Act
+        var result = event.register(aParticipant(), fixedClock);
+
+        // Assert
+        assertThat(result.isSuccess()).isTrue();
+        assertThat(result.domainEvents()).hasSize(1)
+            .first()
+            .isInstanceOf(ParticipantRegisteredEvent.class);
+    }
+}
+```
+
+The exact `Result` API is implementation-specific and MUST follow the application's established
+Result model.
+
+---
+
+## 5. Application Service / Use Case Unit Tests
+
+### Rules
+
+* No Spring context unless the behaviour being tested specifically requires framework wiring.
+* Use JUnit 5 and Mockito where mocking output ports is appropriate.
+* Mock output ports such as persistence, messaging, external service, and event publication ports.
+* Do NOT mock domain objects.
+* Test orchestration logic only.
+* Do NOT re-test domain invariants here.
+* Tests MUST exercise the use case through its public application-facing contract.
+* Application tests MUST verify the established application Result semantics where Result Mapping
+  is the standard failure mechanism.
+
+### Mandatory Scenarios per Handler
+
+Every Command Handler and Query Handler SHOULD have tests covering applicable scenarios:
+
+| Scenario               | Assertion                                                                 |
+| ---------------------- | ------------------------------------------------------------------------- |
+| ✅ Happy path           | Correct output port called; correct successful Result returned            |
+| ❌ Validation failure   | Correct failed Result or established application error behaviour returned |
+| ❌ Not found            | Correct failed Result or established application error behaviour returned |
+| ⚡ Concurrency conflict | Correct concurrency failure Result/error behaviour returned               |
+| ❌ Dependency failure   | Correct failure behaviour returned without corrupting application state   |
+
+The test MUST NOT require a specific exception type when the established application Result model
+represents that failure explicitly.
+
+### Port Argument Verification
+
+Use `@Captor` to assert the exact argument passed to output ports where the argument itself is
+important to the use-case behaviour.
+
+```java
+@Captor
+ArgumentCaptor<Registration> registrationCaptor;
+
+verify(saveRegistrationPort).save(registrationCaptor.capture());
+
+assertThat(registrationCaptor.getValue().status())
+    .isEqualTo(RegistrationStatus.CONFIRMED);
+```
+
+---
+
+## 6. Controller / Primary Adapter Slice Tests
+
+### Rules
+
+* Use `@WebMvcTest(XxxController.class)` where Spring MVC slice testing is appropriate.
+* Mock the application input/use-case port.
+* Do NOT load the full application context for ordinary controller slice tests.
+* Do NOT test business logic — that belongs in application/domain tests.
+* Tests exercise only the public HTTP surface.
+* HTTP error responses MUST follow the application's Problem Details standard.
+
+### Mandatory Scenarios per Endpoint
+
+| Scenario                   | Assertion                                                            |
+| -------------------------- | -------------------------------------------------------------------- |
+| ✅ Happy path               | Correct HTTP status (200/201/204) and response body shape            |
+| ❌ Invalid request body     | HTTP 400 with standardized validation/Problem Details representation |
+| 🔒 Unauthenticated         | HTTP 401 where authentication is required                            |
+| 🔒 Insufficient permission | HTTP 403 where authorization is required                             |
+| ❌ Resource not found       | Standardized HTTP 404 Problem Details response                       |
+| ❌ Application failure      | Appropriate HTTP status and Problem Details representation           |
+| ⚡ Concurrency conflict     | Standardized HTTP 409 response where applicable                      |
+
+Controller tests MUST NOT duplicate the internal logic of Result Mapping or Problem Details.
+
+---
+
+## 7. Persistence / Secondary Adapter Integration Tests
+
+### Rules
+
+* Use `@DataJpaTest` with Testcontainers PostgreSQL where persistence integration behaviour is
+  being tested.
+* `@AutoConfigureTestDatabase(replace = NONE)` SHOULD be used when required to prevent replacement
+  with an embedded database.
+* **Never use H2 or another in-memory substitute for PostgreSQL integration tests.**
+* Testcontainers configuration MUST use an approved PostgreSQL version managed by the project.
+* Flyway migrations MUST be applied before persistence integration tests where migrations are part
+  of the application's persistence configuration.
+* Tests SHOULD validate the migrated schema rather than relying on Hibernate schema generation.
+
+### Mandatory Scenarios
+
+Where applicable, persistence tests MUST verify:
+
+* Entity mapping is correct.
+* Column types, nullability, constraints, and indexes behave as expected.
+* Repository adapter behaviour is correct.
+* Specifications produce the expected query results.
+* Pagination and ordering behave correctly.
+* Optimistic concurrency behaviour is correctly persisted and detected.
+* Soft-delete restrictions behave correctly.
+* Flyway migrations apply cleanly from a blank schema.
+* Unique and other database constraints produce the expected persistence failure behaviour.
+
+Custom JPQL or native queries SHOULD only be tested where such queries are explicitly required by
+the persistence design.
+
+### Shared Base Class Pattern
+
+```java
+@Testcontainers
+public abstract class AbstractPersistenceTest {
+
+    @Container
+    static final PostgreSQLContainer<?> POSTGRES =
+        new PostgreSQLContainer<>("postgres:<approved-version>")
+            .withDatabaseName("app_test")
+            .withUsername("app_test")
+            .withPassword("app_test");
+
+    @DynamicPropertySource
+    static void configureDataSource(DynamicPropertyRegistry registry) {
+
+        registry.add("spring.datasource.url", POSTGRES::getJdbcUrl);
+        registry.add("spring.datasource.username", POSTGRES::getUsername);
+        registry.add("spring.datasource.password", POSTGRES::getPassword);
+    }
+}
+```
+
+The PostgreSQL version MUST be supplied through the project's dependency/version-management policy
+rather than being prescribed by this rule.
+
+---
+
+## 8. Full Integration Tests
+
+### Rules
+
+* Use `@SpringBootTest(webEnvironment = RANDOM_PORT)` + Testcontainers.
+* Use `WebTestClient` or `RestAssured` for HTTP calls against the running application.
+* Reserve full integration tests for **critical end-to-end flows** only.
+* Full integration tests are not a substitute for unit or slice tests.
+* Keep the total count intentionally small to protect CI execution time.
+
+### Candidate Flows
+
+* Core happy-path user journey.
+* Authentication and authorization flow.
+* Cross-module application-event flow.
+* Critical persistence transaction flow.
+* Critical error-response flow involving Result Mapping and Problem Details.
+
+---
+
+## 9. Architecture Tests (ArchUnit)
+
+Architecture tests run on every build and enforce Hexagonal Architecture and module boundaries.
+
+### Mandatory Rules
+
+```java
+@AnalyzeClasses(packages = "com.yourproject")
+class HexagonalArchitectureTest {
+
+    @ArchTest
+    ArchRule domainIsFrameworkFree =
+        noClasses()
+            .that().resideInAPackage("..domain..")
+            .should().dependOnClassesThat()
+            .resideInAnyPackage(
+                "org.springframework..",
+                "jakarta.persistence..",
+                "javax.persistence.."
+            );
+
+    @ArchTest
+    ArchRule applicationDoesNotDependOnAdapters =
+        noClasses()
+            .that().resideInAPackage("..application..")
+            .should().dependOnClassesThat()
+            .resideInAPackage("..adapter..");
+
+    @ArchTest
+    ArchRule noDirectCrossModuleDomainImports =
+        noClasses()
+            .that().resideInAPackage("..moduleA..")
+            .should().dependOnClassesThat()
+            .resideInAPackage("..moduleB..domain..");
+
+    @ArchTest
+    ArchRule portsMustBeInterfaces =
+        classes()
+            .that().haveNameMatching(".*Port")
+            .should().beInterfaces();
+}
+```
+
+Architecture tests SHOULD additionally verify that:
+
+* Domain does not depend on HTTP or Problem Details types.
+* Domain does not depend on Logging or logging implementations.
+* Application does not depend directly on infrastructure adapters.
+* Modules do not access another module's repositories or domain internals.
+* Result Mapping and Problem Details remain at the HTTP/infrastructure boundary.
+
+---
+
+## 10. Result Mapping and Problem Details Tests
+
+Because Result Mapping and Problem Details are explicit technical capabilities, their reusable
+implementations MUST have focused tests.
+
+### Result Mapping
+
+Tests SHOULD verify:
+
+* Successful generic Result → successful HTTP response containing the Result value.
+* Successful non-generic Result → successful HTTP response without a body.
+* Failed Result → delegation to Problem Details.
+* Result Mapping does not construct a second/custom Problem Details representation.
+* Result Mapping does not bypass the established Problem Details mechanism.
+
+### Problem Details
+
+Tests SHOULD verify:
+
+* Standard Problem Details fields are populated correctly.
+* Application errors can be represented as Problem Details.
+* Appropriate exceptions can be mapped.
+* Validation errors can be represented without performing validation.
+* Diagnostic metadata is included only when configured and available.
+* Sensitive exception information is not exposed.
+* Stack traces are disabled by default for production configuration.
+
+These tests MUST NOT move Problem Details or HTTP-specific types into Domain or Application tests.
+
+---
+
+## 11. Test Data and Fixtures
+
+### Rules
+
+* Use a **shared fixture/builder library** per project where repeated fixtures provide value.
+* Builders use the Builder pattern or static factory methods.
+* Builders provide sensible defaults.
+* Tests override only values relevant to the scenario.
+* Domain-specific sentinel values belong in the project's domain testing rules.
+
+### Builder Pattern
+
+```java
+public class RegistrationBuilder {
+
+    private ParticipantId participantId =
+        ParticipantId.of(
+            UUID.fromString("00000000-0000-0000-0000-000000000001")
+        );
+
+    private EventId eventId =
+        EventId.of(
+            UUID.fromString("00000000-0000-0000-0000-000000000002")
+        );
+
+    private RegistrationStatus status =
+        RegistrationStatus.CONFIRMED;
+
+    public static RegistrationBuilder aRegistration() {
+        return new RegistrationBuilder();
+    }
+
+    public RegistrationBuilder withStatus(RegistrationStatus status) {
+        this.status = status;
+        return this;
+    }
+
+    public Registration build() {
+        return Registration.reconstitute(
+            participantId,
+            eventId,
+            status
+        );
+    }
+}
+```
+
+---
+
+## 12. Coverage Targets
+
+| Layer                                           | Target                               | Tool   | CI Gate       |
+| ----------------------------------------------- | ------------------------------------ | ------ | ------------- |
+| Domain — aggregate behaviours and value objects | **100%** line + branch               | JaCoCo | ✅ Fails build |
+| Domain — all other domain code                  | **85%** line                         | JaCoCo | ✅ Fails build |
+| Application — use case handlers                 | **85%** line                         | JaCoCo | ✅ Fails build |
+| Primary Adapters                                | No fixed target — slice-tested       | —      | —             |
+| Secondary Adapters                              | No fixed target — integration-tested | —      | —             |
+
+Coverage MUST be considered together with test quality and meaningful assertions.
+
+Coverage MUST be measured on the changed-files delta per PR in addition to overall package
+thresholds where supported by the CI tooling.
+
+A PR that drops overall coverage below the approved threshold MUST be rejected by CI.
+
+---
+
+## 13. CI Pipeline Test Gates
+
+All of the following MUST pass before a PR can merge to `main`:
+
+| Gate                                                     | Failure Action |
+| -------------------------------------------------------- | -------------- |
+| All unit tests pass                                      | ❌ Block merge  |
+| All integration tests pass                               | ❌ Block merge  |
+| All ArchUnit architecture tests pass                     | ❌ Block merge  |
+| Domain + Application layer coverage ≥ approved threshold | ❌ Block merge  |
+| Required aggregate/value-object coverage achieved        | ❌ Block merge  |
+| Test count report published                              | Informational  |
+
+Integration test execution time SHOULD be monitored and optimized where necessary.
+
+### Security Hygiene in CI
+
+* Test credentials MUST use non-production placeholder values.
+* Integration tests MUST NOT use production environment variables.
+* Tests MUST never hit production endpoints or production databases.
+* Testcontainers MUST use isolated test infrastructure.
+* Sensitive test data MUST NOT be committed to source control.
+
+---
+
+## 14. Test-First Workflow
+
+```text
+1. Write the failing test       → confirm it fails  (RED)
+
+2. Write minimum production code → confirm it passes (GREEN)
+
+3. Refactor                     → confirm tests still pass (REFACTOR)
+
+4. Commit test + production code together
+```
+
+This workflow is **non-negotiable**.
+
+A PR that adds production behaviour without appropriate accompanying tests MUST be rejected during
+code review, unless the change is explicitly classified as a non-behavioural configuration,
+documentation, or infrastructure-only change where tests are not applicable.
+
+---
+
+## 15. Frontend Test Stack (if applicable)
+
+Frontend testing is governed by the frontend/UI lane where one is present.
+
+| Test Type              | Framework                                    | Scope                             |
+| ---------------------- | -------------------------------------------- | --------------------------------- |
+| Component unit         | Project-approved frontend test framework     | Rendering, user interactions      |
+| Hook / composable unit | Project-approved frontend test framework     | Custom hooks and state logic      |
+| API client unit        | Project-approved frontend test framework     | Request format and error handling |
+| E2E                    | Playwright or project-approved E2E framework | Critical user journeys            |
+
+Frontend-specific coverage targets SHOULD be defined by the frontend lane rather than this
+backend technology rule.
+
+---
+
+## 16. Required Dependencies
+
+The exact versions MUST be controlled by the project's centralized dependency management or
+approved BOM.
+
+Typical testing dependencies include:
+
+```xml
+<!-- Testing stack -->
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-test</artifactId>
+    <scope>test</scope>
+</dependency>
+
+<dependency>
+    <groupId>org.testcontainers</groupId>
+    <artifactId>postgresql</artifactId>
+    <scope>test</scope>
+</dependency>
+
+<dependency>
+    <groupId>org.testcontainers</groupId>
+    <artifactId>junit-jupiter</artifactId>
+    <scope>test</scope>
+</dependency>
+
+<dependency>
+    <groupId>com.tngtech.archunit</groupId>
+    <artifactId>archunit-junit5</artifactId>
+    <scope>test</scope>
+</dependency>
+```
+
+The project MAY use additional testing libraries where justified. This rule MUST NOT hardcode
+library versions.
+
+---
+
+## 17. Risks and Mitigations
+
+| Risk                                       | Mitigation                                                                                          |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| Slow integration tests blocking CI         | Share Testcontainers infrastructure where appropriate; reserve `@SpringBootTest` for critical flows |
+| Coverage gamed by trivial tests            | Code review policy requires meaningful assertions and behaviour-focused tests                       |
+| Testcontainers unavailable in CI           | CI runners MUST provide supported container execution                                               |
+| Non-deterministic test failures            | Inject `Clock` and identity generation where required                                               |
+| Cross-module coupling introduced silently  | ArchUnit cross-module boundary rules fail the build                                                 |
+| Tests written after production code        | PR review requires tests for applicable behavioural changes                                         |
+| Error behaviour diverges from API standard | Controller and Problem Details integration tests verify standardized error responses                |
+| Result Mapping duplicates error handling   | Focused Result Mapping tests verify delegation to Problem Details                                   |
+
+```
+
+### One important point
+
+I would **not change the testing file beyond this level**. In particular, I would not add detailed package structures, exact Spring annotations, or exact class names because your other guardrails correctly state that implementation details should remain configurable.
+
+Also, your **`technology-constitution.md` itself has one inconsistency** that should eventually be corrected:
+
+> Principle X says: **"Structured logging using SLF4J/Logback"**
+
+But `logging.md` says the **backend/provider is pluggable** and only SLF4J is the default API/facade. Therefore the constitution should say something like:
+
+> **Structured logging using the approved SLF4J API/facade and configured approved implementation; provider substitution must remain possible.**
+
+That is a **separate small change** I recommend making to `technology-constitution.md`.