Tests that don't lie.
A complete TDD stack for
Java 21 + Spring Boot 3.5.13.

version: "3.9"
name: tdd-stack

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: apppass
      POSTGRES_DB: appdb
      POSTGRES_MULTIPLE_DATABASES: appdb,temporal,keycloak
    ports: ["5432:5432"]
    volumes:
      - postgres-data:/var/lib/postgresql/data
      - ./scripts/init-multi-db.sh:/docker-entrypoint-initdb.d/10-init-multi-db.sh:ro
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 5s

  redis:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes", "--requirepass", "redispass"]
    ports: ["6379:6379"]

  localstack:
    image: localstack/localstack:3.8
    environment:
      SERVICES: s3,sqs,sts,iam
      AWS_DEFAULT_REGION: us-east-1
      AWS_ACCESS_KEY_ID: test
      AWS_SECRET_ACCESS_KEY: test
    ports: ["4566:4566"]
    volumes:
      - ./scripts/init-localstack.sh:/etc/localstack/init/ready.d/init.sh:ro

  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    command: ["start-dev", "--import-realm"]
    environment:
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: appuser
      KC_DB_PASSWORD: apppass
    ports: ["8081:8080"]
    volumes:
      - ./keycloak/realm-export.json:/opt/keycloak/data/import/realm-export.json:ro
    depends_on:
      postgres: { condition: service_healthy }

  temporal:
    image: temporalio/auto-setup:1.25
    environment:
      DB: postgres12
      POSTGRES_USER: appuser
      POSTGRES_PWD: apppass
      POSTGRES_SEEDS: postgres
    ports: ["7233:7233"]
    depends_on:
      postgres: { condition: service_healthy }

  temporal-ui:
    image: temporalio/ui:2.32.0
    environment:
      TEMPORAL_ADDRESS: temporal:7233
    ports: ["8088:8080"]
    depends_on: [temporal]

volumes:
  postgres-data:

#!/bin/bash
set -e
for db in $(echo "$POSTGRES_MULTIPLE_DATABASES" | tr ',' ' '); do
  [ "$db" = "$POSTGRES_DB" ] && continue
  psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -c "CREATE DATABASE $db;"
done

#!/bin/bash
awslocal s3 mb s3://app-uploads
awslocal s3 mb s3://app-archive
awslocal sqs create-queue --queue-name order-events
awslocal sqs create-queue --queue-name order-events-dlq
awslocal sqs create-queue --queue-name notifications

<parent>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-parent</artifactId>
  <version>3.5.13</version>
</parent>

<properties>
  <java.version>21</java.version>
  <aws.sdk.version>2.29.0</aws.sdk.version>
  <temporal.version>1.27.0</temporal.version>
  <testcontainers.version>1.20.4</testcontainers.version>
</properties>

<dependencies>
  <!-- web stack -->
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-actuator</artifactId></dependency>

  <!-- persistence -->
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-jpa</artifactId></dependency>
  <dependency><groupId>org.postgresql</groupId><artifactId>postgresql</artifactId><scope>runtime</scope></dependency>
  <dependency><groupId>org.flywaydb</groupId><artifactId>flyway-database-postgresql</artifactId></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-data-redis</artifactId></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-cache</artifactId></dependency>

  <!-- security / OIDC -->
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-oauth2-resource-server</artifactId></dependency>

  <!-- AWS SDK v2 + Spring Cloud AWS for SQS listeners -->
  <dependency><groupId>software.amazon.awssdk</groupId><artifactId>s3</artifactId><version>${aws.sdk.version}</version></dependency>
  <dependency><groupId>software.amazon.awssdk</groupId><artifactId>sqs</artifactId><version>${aws.sdk.version}</version></dependency>
  <dependency><groupId>io.awspring.cloud</groupId><artifactId>spring-cloud-aws-starter-sqs</artifactId><version>3.2.1</version></dependency>

  <!-- Temporal -->
  <dependency><groupId>io.temporal</groupId><artifactId>temporal-spring-boot-starter</artifactId><version>${temporal.version}</version></dependency>

  <!-- mapping / boilerplate -->
  <dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency>
  <dependency><groupId>org.mapstruct</groupId><artifactId>mapstruct</artifactId><version>1.6.3</version></dependency>

  <!-- ====== TEST ====== -->
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
  <dependency><groupId>org.springframework.security</groupId><artifactId>spring-security-test</artifactId><scope>test</scope></dependency>
  <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-testcontainers</artifactId><scope>test</scope></dependency>
  <dependency><groupId>org.testcontainers</groupId><artifactId>junit-jupiter</artifactId><scope>test</scope></dependency>
  <dependency><groupId>org.testcontainers</groupId><artifactId>postgresql</artifactId><scope>test</scope></dependency>
  <dependency><groupId>org.testcontainers</groupId><artifactId>localstack</artifactId><scope>test</scope></dependency>
  <dependency><groupId>com.redis</groupId><artifactId>testcontainers-redis</artifactId><version>2.2.4</version><scope>test</scope></dependency>
  <dependency><groupId>io.temporal</groupId><artifactId>temporal-testing</artifactId><version>${temporal.version}</version><scope>test</scope></dependency>
  <dependency><groupId>org.wiremock</groupId><artifactId>wiremock-standalone</artifactId><version>3.10.0</version><scope>test</scope></dependency>
  <dependency><groupId>org.awaitility</groupId><artifactId>awaitility</artifactId><scope>test</scope></dependency>
  <dependency><groupId>com.tngtech.archunit</groupId><artifactId>archunit-junit5</artifactId><version>1.3.0</version><scope>test</scope></dependency>
</dependencies>

spring:
  application:
    name: tdd-stack
  threads:
    virtual:
      enabled: true                                # Java 21 virtual threads on Tomcat

  datasource:
    url: jdbc:postgresql://localhost:5432/appdb
    username: appuser
    password: apppass
    hikari:
      maximum-pool-size: 20
  jpa:
    hibernate.ddl-auto: validate
    properties.hibernate.jdbc.time_zone: UTC
  flyway:
    enabled: true
    locations: classpath:db/migration

  data:
    redis:
      host: localhost
      port: 6379
      password: redispass
      timeout: 2s

  cache:
    type: redis
    redis:
      time-to-live: 10m

  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: http://localhost:8081/realms/tdd-app
          jwk-set-uri: http://localhost:8081/realms/tdd-app/protocol/openid-connect/certs

# AWS SDK v2 — point to LocalStack
aws:
  region: us-east-1
  endpoint: http://localhost:4566
  access-key: test
  secret-key: test
  s3:
    bucket-uploads: app-uploads
    bucket-archive: app-archive
  sqs:
    order-events-queue: order-events
    notifications-queue: notifications

# Spring Cloud AWS SQS
spring.cloud.aws:
  region.static: us-east-1
  endpoint: http://localhost:4566
  credentials:
    access-key: test
    secret-key: test

# Temporal
temporal:
  serviceAddress: localhost:7233
  namespace: default
  workers:
    - name: order-worker
      taskQueue: ORDER_TASK_QUEUE
      capacity:
        maxConcurrentWorkflowTaskExecutors: 50
        maxConcurrentActivityExecutors: 50

# Feature flags injected via @Value (perfect ReflectionTestUtils targets)
feature:
  enableArchive: true
  enableNotifications: true
  maxRetries: 3

# Actuator
management:
  endpoints.web.exposure.include: health,info,metrics,prometheus
  endpoint.health.show-details: when-authorized

logging:
  level:
    org.springframework.web: INFO
    com.example: DEBUG
    org.hibernate.SQL: DEBUG

package com.example.foundations;

import org.junit.jupiter.api.*;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.ValueSource;

import java.math.BigDecimal;
import java.util.List;

import static org.assertj.core.api.Assertions.*;

@DisplayName("Money — value object")
class MoneyTest {

    private Money usd10;

    @BeforeEach
    void setUp() {
        usd10 = Money.of("10.00", "USD");
    }

    @Test
    @DisplayName("addition keeps the same currency")
    void add_sameCurrency_works() {
        Money result = usd10.add(Money.of("5.50", "USD"));

        assertThat(result.amount()).isEqualByComparingTo("15.50");
        assertThat(result.currency()).isEqualTo("USD");
    }

    @Test
    void add_differentCurrency_throws() {
        assertThatThrownBy(() -> usd10.add(Money.of("5", "EUR")))
            .isInstanceOf(CurrencyMismatchException.class)
            .hasMessageContaining("USD")
            .hasMessageContaining("EUR");
    }

    @ParameterizedTest(name = "negative amount [{0}] is rejected")
    @ValueSource(strings = {"-0.01", "-1", "-1000.00"})
    void rejectNegative(String amount) {
        assertThatIllegalArgumentException()
            .isThrownBy(() -> Money.of(amount, "USD"))
            .withMessage("amount must be non-negative");
    }

    @Nested
    @DisplayName("when summing a list")
    class Summing {
        @Test
        void emptyListReturnsZero() {
            assertThat(Money.sum(List.of(), "USD"))
                .isEqualTo(Money.of("0.00", "USD"));
        }

        @Test
        void mixedAmountsAreCombined() {
            List coins = List.of(
                Money.of("1.10", "USD"),
                Money.of("2.20", "USD"),
                Money.of("0.05", "USD"));

            assertThat(Money.sum(coins, "USD"))
                .isEqualTo(Money.of("3.35", "USD"));
        }
    }
}

// ▸ Collections — chain everything
assertThat(orders)
    .hasSize(3)
    .extracting(Order::status)
    .containsExactly(NEW, PAID, SHIPPED);

assertThat(orders)
    .filteredOn(o -> o.total().compareTo(BigDecimal.valueOf(100)) > 0)
    .hasSize(1);

// ▸ Object graphs — recursive comparison ignores transient fields
assertThat(actualOrder)
    .usingRecursiveComparison()
    .ignoringFields("createdAt", "updatedAt", "version")
    .isEqualTo(expectedOrder);

// ▸ Optional
assertThat(repo.findById(id))
    .isPresent()
    .get()
    .extracting(User::email)
    .isEqualTo("alice@example.com");

// ▸ Exceptions — fluent
assertThatThrownBy(service::process)
    .isInstanceOf(ValidationException.class)
    .hasMessageContaining("invalid")
    .hasNoCause();

// ▸ JSON — with JsonPath
assertThat(responseJson)
    .extractingJsonPathStringValue("$.user.email").isEqualTo("a@b.com")
    .extractingJsonPathArrayValue("$.user.roles").contains("ADMIN");

// ▸ SoftAssertions — collect every failure, don't bail on the first
assertSoftly(softly -> {
    softly.assertThat(order.id()).isNotNull();
    softly.assertThat(order.total()).isPositive();
    softly.assertThat(order.items()).isNotEmpty();
});

import org.springframework.test.util.ReflectionTestUtils;

// 1. setField — inject into a private field
ReflectionTestUtils.setField(service, "enableFeature", true);
ReflectionTestUtils.setField(service, "maxRetries", 5);

// 2. getField — read a private field for assertion
boolean flag = (Boolean) ReflectionTestUtils.getField(service, "enableFeature");
assertThat(flag).isTrue();

// 3. invokeMethod — call a private method (varargs)
boolean eligible = ReflectionTestUtils
    .invokeMethod(service, "isEligible", "USR-001");

// 4. setField on a superclass field (overload with target class)
ReflectionTestUtils.setField(child, Parent.class, "active", true, boolean.class);

// ─── PRODUCTION CODE ───────────────────────────────────────────
@Service
public class FeatureService {

    @Value("${feature.enableArchive}")
    private boolean enableArchive;

    @Value("${feature.maxRetries:3}")
    private int maxRetries;

    private final ArchiveClient archiveClient;
    private final NotificationService notifications;

    public FeatureService(ArchiveClient archiveClient,
                          NotificationService notifications) {
        this.archiveClient = archiveClient;
        this.notifications = notifications;
    }

    public ProcessResult process(Order order) {
        if (enableArchive) {
            archiveClient.store(order);
        }
        for (int attempt = 1; attempt <= maxRetries; attempt++) {
            try {
                notifications.send(order);
                return ProcessResult.success(attempt);
            } catch (TransientFailure e) {
                if (attempt == maxRetries) throw e;
            }
        }
        throw new IllegalStateException("unreachable");
    }
}

// ─── REQUEST DTO ───────────────────────────────────────────────
public record CreateOrderRequest(
    @NotBlank(message = "userId is required")
    String userId,

    @NotEmpty(message = "items must contain at least one entry")
    @Valid
    List items,

    @Email
    @Size(max = 255)
    String contactEmail,

    @PastOrPresent
    LocalDate orderDate
) {
    public record OrderLine(
        @NotBlank String sku,
        @Positive @Max(100) int quantity,
        @NotNull @PositiveOrZero BigDecimal unitPrice
    ) {}
}

// ─── RESPONSE DTO ──────────────────────────────────────────────
public record OrderResponse(
    UUID id,
    String userId,
    OrderStatus status,
    List lines,
    BigDecimal total,
    Instant createdAt
) {
    public static OrderResponse from(Order entity) {
        return new OrderResponse(
            entity.getId(),
            entity.getUserId(),
            entity.getStatus(),
            entity.getLines().stream().map(LineResponse::from).toList(),
            entity.total(),
            entity.getCreatedAt()
        );
    }

    public record LineResponse(String sku, int quantity, BigDecimal lineTotal) {
        static LineResponse from(OrderLine l) {
            return new LineResponse(l.getSku(), l.getQuantity(),
                l.getUnitPrice().multiply(BigDecimal.valueOf(l.getQuantity())));
        }
    }
}

class CreateOrderRequestTest {

    private final Validator validator = Validation
        .buildDefaultValidatorFactory().getValidator();

    @Test
    void validRequest_hasNoViolations() {
        CreateOrderRequest req = sample();

        Set> v = validator.validate(req);

        assertThat(v).isEmpty();
    }

    @ParameterizedTest(name = "blank userId [\"{0}\"] is rejected")
    @ValueSource(strings = {"", " ", "\t"})
    void blankUserId_isRejected(String userId) {
        CreateOrderRequest req = sample().withUserId(userId);

        assertThat(validator.validate(req))
            .extracting(ConstraintViolation::getMessage)
            .contains("userId is required");
    }

    @Test
    void emptyItems_isRejected() {
        CreateOrderRequest req = sample().withItems(List.of());

        assertThat(validator.validate(req))
            .extracting(v -> v.getPropertyPath().toString())
            .contains("items");
    }

    @Test
    void zeroQuantity_isRejected() {
        var bad = new CreateOrderRequest.OrderLine("SKU-1", 0, BigDecimal.ONE);
        CreateOrderRequest req = sample().withItems(List.of(bad));

        assertThat(validator.validate(req))
            .extracting(v -> v.getPropertyPath().toString())
            .contains("items[0].quantity");
    }

    @Test
    void negativePrice_isRejected() {
        var bad = new CreateOrderRequest.OrderLine("SKU-1", 1, new BigDecimal("-0.01"));

        assertThat(validator.validate(sample().withItems(List.of(bad))))
            .extracting(v -> v.getPropertyPath().toString())
            .contains("items[0].unitPrice");
    }

    @Test
    void responseFrom_mapsLinesAndTotal() {
        Order entity = OrderFixtures.withLines(
            new OrderLine("SKU-A", 2, new BigDecimal("10.00")),
            new OrderLine("SKU-B", 1, new BigDecimal("5.50"))
        );

        OrderResponse res = OrderResponse.from(entity);

        assertThat(res.total()).isEqualByComparingTo("25.50");
        assertThat(res.lines())
            .extracting(OrderResponse.LineResponse::sku)
            .containsExactly("SKU-A", "SKU-B");
    }

    private static CreateOrderRequest sample() {
        return new CreateOrderRequest(
            "USR-1",
            List.of(new CreateOrderRequest.OrderLine("SKU-1", 2, new BigDecimal("9.99"))),
            "alice@example.com",
            LocalDate.now()
        );
    }
}

@RestController
@RequestMapping("/api/v1/orders")
@RequiredArgsConstructor
@Validated
public class OrderController {

    private final OrderService orderService;

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    @PreAuthorize("hasRole('USER')")
    public OrderResponse create(@Valid @RequestBody CreateOrderRequest request,
                                @AuthenticationPrincipal Jwt principal) {
        Order created = orderService.create(request, principal.getSubject());
        return OrderResponse.from(created);
    }

    @GetMapping("/{id}")
    @PreAuthorize("hasRole('USER')")
    public OrderResponse getById(@PathVariable UUID id) {
        return orderService.findById(id)
            .map(OrderResponse::from)
            .orElseThrow(() -> new NotFoundException("Order " + id));
    }

    @GetMapping
    @PreAuthorize("hasRole('USER')")
    public Page list(
            @RequestParam(required = false) OrderStatus status,
            @PageableDefault(size = 20, sort = "createdAt") Pageable pageable) {
        return orderService.find(status, pageable).map(OrderResponse::from);
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    @PreAuthorize("hasRole('MANAGER') or hasRole('ADMIN')")
    public void cancel(@PathVariable UUID id) {
        orderService.cancel(id);
    }

    @ExceptionHandler(NotFoundException.class)
    public ResponseEntity notFound(NotFoundException e) {
        return ResponseEntity.status(404)
            .body(new ApiError("NOT_FOUND", e.getMessage()));
    }
}

@WebMvcTest(OrderController.class)
@Import(SecurityConfig.class)
class OrderControllerTest {

    @Autowired MockMvc mvc;
    @MockitoBean OrderService orderService;
    @Autowired ObjectMapper objectMapper;

    @Test
    @WithMockUser(roles = "USER")
    void create_validBody_returns201() throws Exception {
        UUID id = UUID.randomUUID();
        when(orderService.create(any(), any()))
            .thenReturn(OrderFixtures.persistedWithId(id));

        var body = """
            {
              "userId": "USR-1",
              "items": [{"sku":"SKU-1","quantity":2,"unitPrice":9.99}],
              "contactEmail": "a@b.com",
              "orderDate": "2026-04-28"
            }
            """;

        mvc.perform(post("/api/v1/orders")
                .with(csrf())
                .contentType(MediaType.APPLICATION_JSON)
                .content(body))
            .andExpect(status().isCreated())
            .andExpect(jsonPath("$.id").value(id.toString()))
            .andExpect(jsonPath("$.lines[0].sku").value("SKU-1"))
            .andExpect(jsonPath("$.total").value(19.98));
    }

    @Test
    @WithMockUser(roles = "USER")
    void create_invalidBody_returns400() throws Exception {
        var body = """
            { "userId": "", "items": [] }
            """;

        mvc.perform(post("/api/v1/orders")
                .with(csrf())
                .contentType(MediaType.APPLICATION_JSON)
                .content(body))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.errors[?(@.field=='userId')]").exists())
            .andExpect(jsonPath("$.errors[?(@.field=='items')]").exists());

        verifyNoInteractions(orderService);
    }

    @Test
    @WithMockUser(roles = "USER")
    void getById_notFound_returns404() throws Exception {
        UUID id = UUID.randomUUID();
        when(orderService.findById(id)).thenReturn(Optional.empty());

        mvc.perform(get("/api/v1/orders/{id}", id))
            .andExpect(status().isNotFound())
            .andExpect(jsonPath("$.code").value("NOT_FOUND"));
    }

    @Test
    void getById_anonymous_returns401() throws Exception {
        mvc.perform(get("/api/v1/orders/{id}", UUID.randomUUID()))
            .andExpect(status().isUnauthorized());
    }

    @Test
    @WithMockUser(roles = "USER")
    void cancel_userRole_returns403() throws Exception {
        mvc.perform(delete("/api/v1/orders/{id}", UUID.randomUUID()).with(csrf()))
            .andExpect(status().isForbidden());
    }

    @Test
    @WithMockUser(roles = "MANAGER")
    void cancel_managerRole_returns204() throws Exception {
        UUID id = UUID.randomUUID();

        mvc.perform(delete("/api/v1/orders/{id}", id).with(csrf()))
            .andExpect(status().isNoContent());

        verify(orderService).cancel(id);
    }
}

@Entity
@Table(name = "orders")
@Getter @NoArgsConstructor(access = AccessLevel.PROTECTED)
public class Order {

    @Id
    @GeneratedValue(strategy = GenerationType.UUID)
    private UUID id;

    @Column(nullable = false)
    private String userId;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    private OrderStatus status;

    @OneToMany(mappedBy = "order", cascade = CascadeType.ALL, orphanRemoval = true)
    private List lines = new ArrayList<>();

    @Column(nullable = false, columnDefinition = "jsonb")
    @JdbcTypeCode(SqlTypes.JSON)
    private Map metadata = new HashMap<>();

    @CreationTimestamp Instant createdAt;
    @UpdateTimestamp   Instant updatedAt;
    @Version           long    version;

    public static Order newOrder(String userId, List lines) {
        Order o = new Order();
        o.userId = userId;
        o.status = OrderStatus.NEW;
        lines.forEach(l -> { l.setOrder(o); o.lines.add(l); });
        return o;
    }

    public BigDecimal total() {
        return lines.stream()
            .map(l -> l.getUnitPrice().multiply(BigDecimal.valueOf(l.getQuantity())))
            .reduce(BigDecimal.ZERO, BigDecimal::add);
    }
}

public interface OrderRepository extends JpaRepository {

    List findByUserIdAndStatus(String userId, OrderStatus status);

    @Query("""
        select o from Order o
        where o.status = :status
        and o.createdAt between :from and :to
        """)
    Page findByStatusInRange(@Param("status") OrderStatus status,
                                    @Param("from") Instant from,
                                    @Param("to") Instant to,
                                    Pageable pageable);

    @Modifying
    @Query("update Order o set o.status = :status where o.id = :id")
    int updateStatus(@Param("id") UUID id, @Param("status") OrderStatus status);
}

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class OrderRepositoryTest {

    @Container
    @ServiceConnection
    static PostgreSQLContainer postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @Autowired OrderRepository repo;
    @Autowired TestEntityManager em;

    @Test
    void save_andRoundtrip() {
        Order saved = repo.save(OrderFixtures.simple("USR-1"));

        em.flush();
        em.clear();

        Order loaded = repo.findById(saved.getId()).orElseThrow();
        assertThat(loaded.getStatus()).isEqualTo(OrderStatus.NEW);
        assertThat(loaded.getLines()).hasSize(2);
        assertThat(loaded.total()).isEqualByComparingTo("25.50");
    }

    @Test
    void findByUserIdAndStatus_filtersCorrectly() {
        repo.save(OrderFixtures.simple("USR-1"));
        repo.save(OrderFixtures.simple("USR-2"));
        repo.save(OrderFixtures.paidFor("USR-1"));
        em.flush();

        List result = repo.findByUserIdAndStatus("USR-1", OrderStatus.NEW);

        assertThat(result).hasSize(1);
        assertThat(result.get(0).getUserId()).isEqualTo("USR-1");
    }

    @Test
    void uniqueConstraint_onIdempotencyKey_throws() {
        Order a = OrderFixtures.simple("USR-1").withIdempotencyKey("KEY-1");
        Order b = OrderFixtures.simple("USR-2").withIdempotencyKey("KEY-1");

        repo.save(a);
        assertThatThrownBy(() -> { repo.save(b); em.flush(); })
            .isInstanceOf(DataIntegrityViolationException.class);
    }

    @Test
    void optimisticLock_concurrentUpdates_throwsOnSecond() {
        Order saved = repo.save(OrderFixtures.simple("USR-1"));
        em.flush(); em.clear();

        Order loadedA = repo.findById(saved.getId()).orElseThrow();
        Order loadedB = repo.findById(saved.getId()).orElseThrow();

        repo.updateStatus(loadedA.getId(), OrderStatus.PAID);
        em.flush();

        assertThatThrownBy(() -> {
            ReflectionTestUtils.setField(loadedB, "status", OrderStatus.SHIPPED);
            repo.save(loadedB);
            em.flush();
        }).isInstanceOf(ObjectOptimisticLockingFailureException.class);
    }
}

@SpringBootTest
@Testcontainers
class FlywayMigrationTest {

    @Container @ServiceConnection
    static PostgreSQLContainer postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @Autowired Flyway flyway;
    @Autowired DataSource dataSource;

    @Test
    void allMigrationsApply() {
        MigrationInfo[] applied = flyway.info().applied();
        assertThat(applied).isNotEmpty();
        assertThat(applied[applied.length-1].getState()).isEqualTo(MigrationState.SUCCESS);
    }

    @Test
    void schema_hasExpectedTables() throws Exception {
        try (Connection c = dataSource.getConnection();
             Statement s = c.createStatement();
             ResultSet rs = s.executeQuery(
                "select table_name from information_schema.tables where table_schema='public'")) {
            List tables = new ArrayList<>();
            while (rs.next()) tables.add(rs.getString(1));
            assertThat(tables).contains("orders", "order_lines", "users");
        }
    }
}

@Configuration
@EnableCaching
public class CacheConfig {

    @Bean
    public RedisCacheManager cacheManager(RedisConnectionFactory cf) {
        RedisCacheConfiguration defaults = RedisCacheConfiguration.defaultCacheConfig()
            .entryTtl(Duration.ofMinutes(10))
            .disableCachingNullValues()
            .serializeKeysWith(SerializationPair.fromSerializer(new StringRedisSerializer()))
            .serializeValuesWith(SerializationPair.fromSerializer(
                new GenericJackson2JsonRedisSerializer()));

        return RedisCacheManager.builder(cf)
            .cacheDefaults(defaults)
            .withCacheConfiguration("orders", defaults.entryTtl(Duration.ofMinutes(5)))
            .withCacheConfiguration("users",  defaults.entryTtl(Duration.ofHours(1)))
            .build();
    }
}

@Service
@RequiredArgsConstructor
public class OrderQueryService {

    private final OrderRepository repo;

    @Cacheable(value = "orders", key = "#id", unless = "#result == null")
    public Optional findById(UUID id) {
        return repo.findById(id);
    }

    @CacheEvict(value = "orders", key = "#id")
    public void evict(UUID id) {}

    @CachePut(value = "orders", key = "#order.id")
    public Order updateAndCache(Order order) {
        return repo.save(order);
    }
}

@SpringBootTest
@Testcontainers
@AutoConfigureCache
class OrderQueryServiceCacheTest {

    @Container @ServiceConnection
    static GenericContainer redis = new GenericContainer<>("redis:7-alpine")
        .withExposedPorts(6379)
        .withCommand("redis-server", "--requirepass", "redispass");

    @Container @ServiceConnection
    static PostgreSQLContainer postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @DynamicPropertySource
    static void redisAuth(DynamicPropertyRegistry r) {
        r.add("spring.data.redis.password", () -> "redispass");
    }

    @Autowired OrderQueryService service;
    @Autowired CacheManager cacheManager;
    @SpyBean OrderRepository repo;

    @BeforeEach
    void clearCache() {
        Objects.requireNonNull(cacheManager.getCache("orders")).clear();
    }

    @Test
    void firstCall_hitsDb_secondCall_hitsCache() {
        UUID id = persistOrder().getId();

        Optional a = service.findById(id);
        Optional b = service.findById(id);
        Optional c = service.findById(id);

        assertThat(a).isPresent();
        assertThat(b).isPresent();
        assertThat(c).isPresent();
        verify(repo, times(1)).findById(id);   // only ONE DB call
    }

    @Test
    void evict_invalidatesCache() {
        UUID id = persistOrder().getId();

        service.findById(id);
        service.evict(id);
        service.findById(id);

        verify(repo, times(2)).findById(id);
    }

    @Test
    void cache_serializesAsJson() {
        UUID id = persistOrder().getId();
        service.findById(id);

        Cache cache = cacheManager.getCache("orders");
        Cache.ValueWrapper raw = cache.get(id);

        assertThat(raw).isNotNull();
        assertThat(raw.get()).isInstanceOf(Optional.class);
    }

    @Test
    void cache_respectsConfiguredTtl() throws InterruptedException {
        UUID id = persistOrder().getId();

        service.findById(id);
        Thread.sleep(100);
        service.findById(id);

        verify(repo, times(1)).findById(id);
    }
}

@Service
@RequiredArgsConstructor
public class OrderEnrichmentService {

    private final UserClient userClient;
    private final InventoryClient inventoryClient;
    private final PricingClient pricingClient;
    private final Executor enrichmentExecutor;   // injected, swappable

    public CompletableFuture enrich(Order order) {
        var userF = CompletableFuture.supplyAsync(
            () -> userClient.fetch(order.getUserId()), enrichmentExecutor);

        var skus = order.getLines().stream().map(OrderLine::getSku).toList();

        var stockF = CompletableFuture.supplyAsync(
            () -> inventoryClient.checkAll(skus), enrichmentExecutor);

        var priceF = CompletableFuture.supplyAsync(
            () -> pricingClient.quote(skus), enrichmentExecutor);

        return userF.thenCombine(stockF, Pair::of)
            .thenCombine(priceF, (pair, prices) ->
                new EnrichedOrder(order, pair.first(), pair.second(), prices))
            .orTimeout(5, TimeUnit.SECONDS)
            .exceptionally(ex -> EnrichedOrder.failed(order, ex));
    }
}

@ExtendWith(MockitoExtension.class)
class OrderEnrichmentServiceTest {

    @Mock UserClient userClient;
    @Mock InventoryClient inventoryClient;
    @Mock PricingClient pricingClient;

    OrderEnrichmentService service;

    @BeforeEach
    void setUp() {
        // Same-thread executor → deterministic, no sleeps, no flakes
        service = new OrderEnrichmentService(
            userClient, inventoryClient, pricingClient, Runnable::run);
    }

    @Test
    void enrich_combinesAllSources() throws Exception {
        Order order = OrderFixtures.simple("USR-1");
        when(userClient.fetch("USR-1")).thenReturn(new User("USR-1", "alice@x"));
        when(inventoryClient.checkAll(any())).thenReturn(Map.of("SKU-1", 10, "SKU-2", 5));
        when(pricingClient.quote(any())).thenReturn(Map.of("SKU-1", new BigDecimal("9.99")));

        CompletableFuture result = service.enrich(order);

        EnrichedOrder enriched = result.get(2, TimeUnit.SECONDS);
        assertThat(enriched.user().email()).isEqualTo("alice@x");
        assertThat(enriched.stock()).containsEntry("SKU-1", 10);
    }

    @Test
    void enrich_oneSourceFails_returnsFailedOrder() throws Exception {
        Order order = OrderFixtures.simple("USR-1");
        when(userClient.fetch(any())).thenThrow(new ServiceUnavailableException("user svc down"));
        when(inventoryClient.checkAll(any())).thenReturn(Map.of());
        when(pricingClient.quote(any())).thenReturn(Map.of());

        EnrichedOrder result = service.enrich(order).get(2, TimeUnit.SECONDS);

        assertThat(result.isFailed()).isTrue();
        assertThat(result.errorCause()).isInstanceOf(ServiceUnavailableException.class);
    }
}

@Test
void enrich_oneSlowSource_triggersTimeout() {
    var realExecutor = Executors.newFixedThreadPool(4);
    var svc = new OrderEnrichmentService(
        userClient, inventoryClient, pricingClient, realExecutor);

    when(userClient.fetch(any())).thenAnswer(inv -> {
        Thread.sleep(10_000);
        return new User("u","e");
    });
    when(inventoryClient.checkAll(any())).thenReturn(Map.of());
    when(pricingClient.quote(any())).thenReturn(Map.of());

    Order order = OrderFixtures.simple("USR-1");

    EnrichedOrder result = svc.enrich(order).join();

    assertThat(result.isFailed()).isTrue();
    assertThat(result.errorCause()).isInstanceOf(TimeoutException.class);
    realExecutor.shutdownNow();
}

@Test
void publishEvent_async_eventuallyArrives() {
    AtomicReference captured = new AtomicReference<>();
    bus.subscribe(captured::set);

    publisher.publish(new OrderEvent("ORD-1", "PAID"));

    await().atMost(Duration.ofSeconds(2))
           .untilAsserted(() -> {
               assertThat(captured.get()).isNotNull();
               assertThat(captured.get().status()).isEqualTo("PAID");
           });
}

spring:
  threads:
    virtual:
      enabled: true

@Service
@RequiredArgsConstructor
public class FanoutService {

    private final HttpClient httpClient;

    public List fetchAll(List userIds) {
        try (var scope = StructuredTaskScope.open(
                Joiner.allSuccessfulOrThrow())) {

            List> tasks = userIds.stream()
                .map(id -> scope.fork(() -> fetchOne(id)))
                .toList();

            scope.join();

            return tasks.stream().map(Subtask::get).toList();
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            throw new RuntimeException(e);
        }
    }

    private UserProfile fetchOne(String id) throws Exception {
        var req = HttpRequest.newBuilder()
            .uri(URI.create("http://users/api/" + id))
            .GET().build();
        var res = httpClient.send(req, HttpResponse.BodyHandlers.ofString());
        return UserProfile.parse(res.body());
    }
}

@SpringBootTest(webEnvironment = WebEnvironment.NONE)
class FanoutServiceTest {

    static WireMockServer wireMock;

    @BeforeAll
    static void startMock() {
        wireMock = new WireMockServer(0);
        wireMock.start();
        wireMock.stubFor(get(urlMatching("/api/.*"))
            .willReturn(aResponse()
                .withFixedDelay(200)
                .withBody("{\"id\":\"u\",\"email\":\"u@x\"}")));
    }
    @AfterAll static void stopMock() { wireMock.stop(); }

    @Autowired FanoutService service;

    @Test
    void fetchAll_100users_underOneSecond() {
        List ids = IntStream.range(0, 100)
            .mapToObj(i -> "USR-" + i).toList();

        long t0 = System.nanoTime();
        List result = service.fetchAll(ids);
        Duration elapsed = Duration.ofNanos(System.nanoTime() - t0);

        assertThat(result).hasSize(100);
        // 100 calls × 200ms each = 20s sequential.
        // With virtual threads ≈ 200-400ms total.
        assertThat(elapsed).isLessThan(Duration.ofSeconds(1));
    }

    @Test
    void runsOnVirtualThreads() throws Exception {
        AtomicBoolean wasVirtual = new AtomicBoolean();

        Thread t = Thread.ofVirtual().start(() -> {
            wasVirtual.set(Thread.currentThread().isVirtual());
        });
        t.join();

        assertThat(wasVirtual).isTrue();
    }
}

@Configuration
@RequiredArgsConstructor
public class AwsConfig {

    @Value("${aws.region}")        String region;
    @Value("${aws.endpoint}")      String endpoint;
    @Value("${aws.access-key}")    String accessKey;
    @Value("${aws.secret-key}")    String secretKey;

    @Bean
    public S3Client s3Client() {
        var creds = AwsBasicCredentials.create(accessKey, secretKey);
        return S3Client.builder()
            .region(Region.of(region))
            .endpointOverride(URI.create(endpoint))
            .credentialsProvider(StaticCredentialsProvider.create(creds))
            .forcePathStyle(true)            // REQUIRED for LocalStack
            .build();
    }

    @Bean
    public S3Presigner s3Presigner() {
        return S3Presigner.builder()
            .region(Region.of(region))
            .endpointOverride(URI.create(endpoint))
            .credentialsProvider(StaticCredentialsProvider.create(
                AwsBasicCredentials.create(accessKey, secretKey)))
            .serviceConfiguration(S3Configuration.builder().pathStyle(true).build())
            .build();
    }
}

@Service
@RequiredArgsConstructor
public class InvoiceStorageService {

    private final S3Client s3;
    private final S3Presigner presigner;

    @Value("${aws.s3.bucket-uploads}")
    private String bucket;

    public StoredFile store(UUID orderId, byte[] content) {
        String key = "invoices/%s/%s.pdf".formatted(
            LocalDate.now(), orderId);

        s3.putObject(PutObjectRequest.builder()
                .bucket(bucket)
                .key(key)
                .contentType("application/pdf")
                .metadata(Map.of("orderId", orderId.toString()))
                .build(),
            RequestBody.fromBytes(content));

        return new StoredFile(bucket, key, content.length);
    }

    public byte[] download(String key) {
        return s3.getObjectAsBytes(GetObjectRequest.builder()
                .bucket(bucket).key(key).build())
            .asByteArray();
    }

    public URL presignedDownloadUrl(String key, Duration ttl) {
        var req = GetObjectPresignRequest.builder()
            .signatureDuration(ttl)
            .getObjectRequest(b -> b.bucket(bucket).key(key))
            .build();
        return presigner.presignGetObject(req).url();
    }
}

@SpringBootTest(webEnvironment = WebEnvironment.NONE)
@Testcontainers
class InvoiceStorageServiceTest {

    @Container
    static LocalStackContainer localStack = new LocalStackContainer(
            DockerImageName.parse("localstack/localstack:3.8"))
        .withServices(Service.S3);

    @DynamicPropertySource
    static void awsProps(DynamicPropertyRegistry r) {
        r.add("aws.endpoint",   localStack::getEndpoint);
        r.add("aws.region",     localStack::getRegion);
        r.add("aws.access-key", localStack::getAccessKey);
        r.add("aws.secret-key", localStack::getSecretKey);
        r.add("aws.s3.bucket-uploads", () -> "app-uploads");
    }

    @BeforeAll
    static void setupBucket() throws Exception {
        localStack.execInContainer("awslocal", "s3", "mb", "s3://app-uploads");
    }

    @Autowired InvoiceStorageService service;
    @Autowired S3Client s3;

    @Test
    void store_uploadsBytes_setsMetadata() {
        UUID orderId = UUID.randomUUID();
        byte[] pdf = "FAKE PDF CONTENT".getBytes(UTF_8);

        StoredFile result = service.store(orderId, pdf);

        assertThat(result.size()).isEqualTo(pdf.length);
        assertThat(result.key()).contains(orderId.toString());

        byte[] downloaded = s3.getObjectAsBytes(b ->
            b.bucket("app-uploads").key(result.key())).asByteArray();
        assertThat(downloaded).isEqualTo(pdf);

        var head = s3.headObject(b -> b.bucket("app-uploads").key(result.key()));
        assertThat(head.metadata()).containsEntry("orderid", orderId.toString());
    }

    @Test
    void presignedUrl_canBeFetchedExternally() throws Exception {
        UUID orderId = UUID.randomUUID();
        var stored = service.store(orderId, "X".getBytes());

        URL url = service.presignedDownloadUrl(stored.key(), Duration.ofMinutes(5));

        try (HttpClient client = HttpClient.newHttpClient()) {
            HttpResponse response = client.send(
                HttpRequest.newBuilder(url.toURI()).GET().build(),
                HttpResponse.BodyHandlers.ofByteArray());

            assertThat(response.statusCode()).isEqualTo(200);
            assertThat(response.body()).isEqualTo("X".getBytes());
        }
    }

    @Test
    void download_missingKey_throwsNoSuchKey() {
        assertThatThrownBy(() -> service.download("does/not/exist"))
            .isInstanceOf(NoSuchKeyException.class);
    }
}

@Service
@RequiredArgsConstructor
public class OrderEventPublisher {

    private final SqsTemplate sqs;

    public void publish(OrderEvent event) {
        sqs.send(to -> to
            .queue("order-events")
            .payload(event)
            .messageGroupId(event.orderId().toString()));
    }
}

@Component
@RequiredArgsConstructor
public class OrderEventListener {

    private final OrderProjector projector;

    @SqsListener("order-events")
    public void onMessage(OrderEvent event,
                          @Header("ApproximateReceiveCount") Integer receiveCount) {
        if (receiveCount > 5) {
            throw new PoisonMessageException("retried " + receiveCount + " times");
        }
        projector.apply(event);
    }
}

@SpringBootTest
@Testcontainers
class OrderEventFlowIT {

    @Container
    static LocalStackContainer localStack = new LocalStackContainer(
            DockerImageName.parse("localstack/localstack:3.8"))
        .withServices(Service.SQS);

    @DynamicPropertySource
    static void awsProps(DynamicPropertyRegistry r) {
        r.add("spring.cloud.aws.endpoint", localStack::getEndpoint);
        r.add("spring.cloud.aws.region.static", localStack::getRegion);
        r.add("spring.cloud.aws.credentials.access-key", localStack::getAccessKey);
        r.add("spring.cloud.aws.credentials.secret-key", localStack::getSecretKey);
        r.add("aws.endpoint", localStack::getEndpoint);
        r.add("aws.region", localStack::getRegion);
    }

    @BeforeAll
    static void createQueue() throws Exception {
        localStack.execInContainer("awslocal", "sqs", "create-queue",
            "--queue-name", "order-events");
    }

    @Autowired OrderEventPublisher publisher;
    @MockitoBean OrderProjector projector;

    @Test
    void publish_isReceivedByListener() {
        OrderEvent event = new OrderEvent(
            UUID.randomUUID(), "PAID", Instant.now());

        publisher.publish(event);

        await().atMost(Duration.ofSeconds(10))
            .untilAsserted(() -> verify(projector).apply(eq(event)));
    }

    @Test
    void poisonMessage_endsUpInDlq() {
        OrderEvent event = new OrderEvent(UUID.randomUUID(), "BAD", Instant.now());
        doThrow(new RuntimeException("boom"))
            .when(projector).apply(any());

        publisher.publish(event);

        await().atMost(Duration.ofSeconds(20))
            .untilAsserted(() -> verify(projector, atLeast(2)).apply(any()));
    }
}

@WorkflowInterface
public interface OrderFulfillmentWorkflow {

    @WorkflowMethod
    OrderResult fulfil(UUID orderId);

    @SignalMethod
    void cancelRequested();

    @QueryMethod
    OrderStatus currentStatus();
}

@ActivityInterface
public interface FulfillmentActivities {

    @ActivityMethod
    PaymentResult chargePayment(UUID orderId, BigDecimal amount);

    @ActivityMethod
    String reserveInventory(UUID orderId, List lines);

    @ActivityMethod
    String shipOrder(UUID orderId, String reservationId);

    @ActivityMethod
    void notifyCustomer(UUID orderId, String message);

    @ActivityMethod
    void releaseInventory(String reservationId);
}

public class OrderFulfillmentWorkflowImpl implements OrderFulfillmentWorkflow {

    private final FulfillmentActivities activities = Workflow.newActivityStub(
        FulfillmentActivities.class,
        ActivityOptions.newBuilder()
            .setStartToCloseTimeout(Duration.ofSeconds(30))
            .setRetryOptions(RetryOptions.newBuilder()
                .setMaximumAttempts(3)
                .setInitialInterval(Duration.ofSeconds(1))
                .build())
            .build());

    private OrderStatus status = OrderStatus.NEW;
    private boolean cancelRequested = false;

    @Override
    public OrderResult fulfil(UUID orderId) {
        Order order = Workflow.sideEffect(Order.class, () -> OrderRegistry.fetch(orderId));

        status = OrderStatus.PAYING;
        PaymentResult payment = activities.chargePayment(orderId, order.total());
        if (!payment.success()) return OrderResult.failed("payment_declined");

        status = OrderStatus.RESERVING;
        String reservation = activities.reserveInventory(orderId, order.lines());

        boolean cancelled = Workflow.await(Duration.ofMinutes(5), () -> cancelRequested);
        if (cancelled) {
            activities.releaseInventory(reservation);
            return OrderResult.cancelled();
        }

        status = OrderStatus.SHIPPING;
        String tracking = activities.shipOrder(orderId, reservation);

        activities.notifyCustomer(orderId, "Shipped: " + tracking);
        status = OrderStatus.SHIPPED;
        return OrderResult.success(tracking);
    }

    @Override public void cancelRequested() { cancelRequested = true; }
    @Override public OrderStatus currentStatus()  { return status; }
}

class OrderFulfillmentWorkflowTest {

    @RegisterExtension
    public static final TestWorkflowExtension testWf = TestWorkflowExtension.newBuilder()
        .setWorkflowTypes(OrderFulfillmentWorkflowImpl.class)
        .setDoNotStart(true)
        .build();

    private FulfillmentActivities activities;

    @BeforeEach
    void registerActivities(TestWorkflowEnvironment env, Worker worker) {
        activities = mock(FulfillmentActivities.class);
        worker.registerActivitiesImplementations(activities);
        env.start();
    }

    @Test
    void fulfil_happyPath_returnsTracking(TestWorkflowEnvironment env,
                                           OrderFulfillmentWorkflow wf) {
        UUID orderId = UUID.randomUUID();
        when(activities.chargePayment(any(), any())).thenReturn(PaymentResult.ok());
        when(activities.reserveInventory(any(), any())).thenReturn("RES-1");
        when(activities.shipOrder(any(), any())).thenReturn("TRK-9");

        OrderResult result = wf.fulfil(orderId);

        assertThat(result.success()).isTrue();
        assertThat(result.trackingNumber()).isEqualTo("TRK-9");

        InOrder order = inOrder(activities);
        order.verify(activities).chargePayment(eq(orderId), any());
        order.verify(activities).reserveInventory(eq(orderId), any());
        order.verify(activities).shipOrder(eq(orderId), eq("RES-1"));
        order.verify(activities).notifyCustomer(eq(orderId), contains("TRK-9"));
    }

    @Test
    void fulfil_paymentDeclined_doesNotReserveInventory(
            TestWorkflowEnvironment env, OrderFulfillmentWorkflow wf) {
        when(activities.chargePayment(any(), any()))
            .thenReturn(PaymentResult.declined("insufficient_funds"));

        OrderResult result = wf.fulfil(UUID.randomUUID());

        assertThat(result.success()).isFalse();
        verify(activities, never()).reserveInventory(any(), any());
        verify(activities, never()).shipOrder(any(), any());
    }
}

@Test
void cancelSignal_triggersInventoryRelease(
        TestWorkflowEnvironment env,
        WorkflowClient client,
        OrderFulfillmentWorkflow wf) {

    when(activities.chargePayment(any(), any())).thenReturn(PaymentResult.ok());
    when(activities.reserveInventory(any(), any())).thenReturn("RES-2");

    UUID orderId = UUID.randomUUID();

    WorkflowClient.start(wf::fulfil, orderId);

    env.sleep(Duration.ofSeconds(5));
    assertThat(wf.currentStatus()).isEqualTo(OrderStatus.RESERVING);

    wf.cancelRequested();

    OrderResult result = WorkflowStub.fromTyped(wf).getResult(OrderResult.class);
    assertThat(result.cancelled()).isTrue();

    verify(activities).releaseInventory("RES-2");
    verify(activities, never()).shipOrder(any(), any());
}

@Test
void shipOrder_failsTwice_succeedsThirdTime(
        TestWorkflowEnvironment env, OrderFulfillmentWorkflow wf) {

    when(activities.chargePayment(any(), any())).thenReturn(PaymentResult.ok());
    when(activities.reserveInventory(any(), any())).thenReturn("RES-3");
    when(activities.shipOrder(any(), any()))
        .thenThrow(new RuntimeException("carrier offline"))
        .thenThrow(new RuntimeException("carrier offline"))
        .thenReturn("TRK-FINAL");

    OrderResult result = wf.fulfil(UUID.randomUUID());

    assertThat(result.success()).isTrue();
    assertThat(result.trackingNumber()).isEqualTo("TRK-FINAL");
    verify(activities, times(3)).shipOrder(any(), any());
}

@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        return http
            .csrf(csrf -> csrf.disable())
            .sessionManagement(s -> s.sessionCreationPolicy(STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/actuator/health", "/actuator/info").permitAll()
                .anyRequest().authenticated())
            .oauth2ResourceServer(oauth -> oauth
                .jwt(jwt -> jwt.jwtAuthenticationConverter(keycloakConverter())))
            .build();
    }

    private Converter keycloakConverter() {
        var converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(jwt -> {
            Map realmAccess = jwt.getClaim("realm_access");
            if (realmAccess == null) return List.of();

            @SuppressWarnings("unchecked")
            List roles = (List) realmAccess.getOrDefault("roles", List.of());

            return roles.stream()
                .map(r -> new SimpleGrantedAuthority("ROLE_" + r))
                .collect(toList());
        });
        return converter;
    }
}

@WebMvcTest(OrderController.class)
@Import(SecurityConfig.class)
class OrderControllerSecurityTest {

    @Autowired MockMvc mvc;
    @MockitoBean OrderService orderService;

    @Test
    void anonymousRequest_returns401() throws Exception {
        mvc.perform(get("/api/v1/orders/{id}", UUID.randomUUID()))
            .andExpect(status().isUnauthorized());
    }

    @Test
    @WithMockUser(roles = "USER")
    void userRole_canRead() throws Exception {
        when(orderService.findById(any())).thenReturn(Optional.of(OrderFixtures.simple("u")));

        mvc.perform(get("/api/v1/orders/{id}", UUID.randomUUID()))
            .andExpect(status().isOk());
    }

    @Test
    @WithMockUser(roles = "USER")
    void userRole_cannotCancel() throws Exception {
        mvc.perform(delete("/api/v1/orders/{id}", UUID.randomUUID()).with(csrf()))
            .andExpect(status().isForbidden());
    }

    @Test
    @WithMockUser(roles = {"MANAGER","USER"})
    void managerRole_canCancel() throws Exception {
        mvc.perform(delete("/api/v1/orders/{id}", UUID.randomUUID()).with(csrf()))
            .andExpect(status().isNoContent());
    }
}

@Test
void create_usesSubFromJwt() throws Exception {
    when(orderService.create(any(), eq("USR-42")))
        .thenReturn(OrderFixtures.persistedFor("USR-42"));

    var body = """
        {"userId":"USR-42","items":[{"sku":"SKU-1","quantity":1,"unitPrice":9.99}],
         "contactEmail":"a@b.com","orderDate":"2026-04-28"}
        """;

    mvc.perform(post("/api/v1/orders")
            .with(jwt()
                .jwt(j -> j.subject("USR-42")
                           .claim("realm_access", Map.of("roles", List.of("USER"))))
                .authorities(new SimpleGrantedAuthority("ROLE_USER")))
            .with(csrf())
            .contentType(MediaType.APPLICATION_JSON)
            .content(body))
        .andExpect(status().isCreated());

    verify(orderService).create(any(), eq("USR-42"));
}

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@Testcontainers
@AutoConfigureMockMvc
class KeycloakIntegrationIT {

    @Container
    static KeycloakContainer keycloak = new KeycloakContainer("quay.io/keycloak/keycloak:26.0")
        .withRealmImportFile("/realm-export.json");

    @DynamicPropertySource
    static void jwt(DynamicPropertyRegistry r) {
        r.add("spring.security.oauth2.resourceserver.jwt.issuer-uri",
            () -> keycloak.getAuthServerUrl() + "/realms/tdd-app");
        r.add("spring.security.oauth2.resourceserver.jwt.jwk-set-uri",
            () -> keycloak.getAuthServerUrl()
                + "/realms/tdd-app/protocol/openid-connect/certs");
    }

    @LocalServerPort int port;
    @Autowired RestClient.Builder restBuilder;

    @Test
    void aliceWithAdminRole_canAccessProtectedEndpoint() {
        String accessToken = fetchToken("alice", "password");

        ResponseEntity response = restBuilder.build()
            .get()
            .uri("http://localhost:" + port + "/api/v1/orders")
            .header("Authorization", "Bearer " + accessToken)
            .retrieve()
            .toEntity(String.class);

        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    }

    @Test
    void bobWithUserRole_cannotCancelOrder() {
        String accessToken = fetchToken("bob", "password");

        assertThatThrownBy(() -> restBuilder.build()
            .delete()
            .uri("http://localhost:" + port + "/api/v1/orders/{id}", UUID.randomUUID())
            .header("Authorization", "Bearer " + accessToken)
            .retrieve()
            .toBodilessEntity())
            .isInstanceOf(HttpClientErrorException.Forbidden.class);
    }

    private String fetchToken(String username, String password) {
        var form = new LinkedMultiValueMap();
        form.add("client_id", "tdd-app-backend");
        form.add("client_secret", "backend-secret-change-me");
        form.add("grant_type", "password");
        form.add("username", username);
        form.add("password", password);

        Map body = restBuilder.build()
            .post()
            .uri(keycloak.getAuthServerUrl() + "/realms/tdd-app/protocol/openid-connect/token")
            .contentType(MediaType.APPLICATION_FORM_URLENCODED)
            .body(form)
            .retrieve()
            .body(new ParameterizedTypeReference<>() {});

        return (String) body.get("access_token");
    }
}

@RestControllerAdvice
public class ApiExceptionHandler {

    @ExceptionHandler(MethodArgumentNotValidException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ApiError onValidation(MethodArgumentNotValidException e) {
        List<FieldError> fieldErrors = e.getBindingResult().getFieldErrors().stream()
            .map(fe -> new FieldError(fe.getField(), fe.getDefaultMessage(),
                String.valueOf(fe.getRejectedValue())))
            .toList();
        return new ApiError("VALIDATION_FAILED", "Request body invalid", fieldErrors);
    }

    @ExceptionHandler(ConstraintViolationException.class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    public ApiError onConstraint(ConstraintViolationException e) {
        var fieldErrors = e.getConstraintViolations().stream()
            .map(cv -> new FieldError(
                cv.getPropertyPath().toString(),
                cv.getMessage(),
                String.valueOf(cv.getInvalidValue())))
            .toList();
        return new ApiError("VALIDATION_FAILED", "Parameter invalid", fieldErrors);
    }

    @ExceptionHandler(NotFoundException.class)
    @ResponseStatus(HttpStatus.NOT_FOUND)
    public ApiError onNotFound(NotFoundException e) {
        return new ApiError("NOT_FOUND", e.getMessage(), List.of());
    }

    @ExceptionHandler(DataIntegrityViolationException.class)
    @ResponseStatus(HttpStatus.CONFLICT)
    public ApiError onIntegrity(DataIntegrityViolationException e) {
        String message = e.getMostSpecificCause().getMessage();
        if (message != null && message.contains("idempotency_key"))
            return new ApiError("DUPLICATE", "Request already processed", List.of());
        return new ApiError("CONFLICT", "Resource already exists", List.of());
    }
}

// ▸ basic — type + message
assertThatThrownBy(() -> service.process(badInput))
    .isInstanceOf(ValidationException.class)
    .hasMessageContaining("invalid sku")
    .hasMessageMatching(".*SKU-\\d+.*");

// ▸ specific exception types — sugar for IllegalArgumentException, etc.
assertThatIllegalArgumentException()
    .isThrownBy(() -> Money.of("-1", "USD"))
    .withMessage("amount must be non-negative");

// ▸ assert no exception thrown
assertThatNoException().isThrownBy(() -> service.process(validInput));

// ▸ inspect a wrapped cause
assertThatThrownBy(() -> service.callRemote())
    .isInstanceOf(ServiceException.class)
    .hasCauseInstanceOf(ConnectException.class)
    .rootCause()
    .hasMessageContaining("connection refused");

// ▸ extract and inspect a custom exception's fields
assertThatThrownBy(() -> service.charge(card, amount))
    .asInstanceOf(InstanceOfAssertFactories.type(PaymentException.class))
    .extracting(PaymentException::getDeclineCode)
    .isEqualTo("INSUFFICIENT_FUNDS");

// ▸ Future / CompletableFuture — unwrap CompletionException
CompletableFuture<Order> future = service.processAsync(badInput);
assertThatThrownBy(future::get)
    .isInstanceOf(ExecutionException.class)
    .hasCauseInstanceOf(ValidationException.class);

// or use AssertJ's CompletableFuture support
assertThat(future)
    .failsWithin(Duration.ofSeconds(2))
    .withThrowableOfType(ExecutionException.class)
    .withCauseInstanceOf(ValidationException.class);

@DataJpaTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@Testcontainers
class OrderTransactionTest {

    @Container @ServiceConnection
    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");

    @Autowired OrderRepository repo;
    @Autowired TestEntityManager em;
    @Autowired TransactionTemplate tx;

    @Test
    void duplicateIdempotencyKey_throwsAndRollsBack() {
        Order first = repo.save(OrderFixtures.simple("USR-1").withIdempotencyKey("KEY-1"));
        em.flush();
        long countBefore = repo.count();

        assertThatThrownBy(() -> tx.execute(status -> {
            Order dup = OrderFixtures.simple("USR-2").withIdempotencyKey("KEY-1");
            repo.save(dup);
            em.flush();
            return null;
        }))
        .isInstanceOf(DataIntegrityViolationException.class)
        .hasMessageContaining("idempotency_key");

        assertThat(repo.count()).isEqualTo(countBefore);   // rollback
    }

    @Test
    void notNullConstraint_isEnforced() {
        Order broken = OrderFixtures.simple("USR-1");
        ReflectionTestUtils.setField(broken, "userId", null);

        assertThatThrownBy(() -> { repo.save(broken); em.flush(); })
            .isInstanceOf(DataIntegrityViolationException.class);
    }

    @Test
    void uniqueViolation_translatesToConflict() {
        Order a = repo.save(OrderFixtures.simple("USR-1").withCorrelationId("CORR-1"));
        em.flush();

        assertThatThrownBy(() -> {
            Order b = OrderFixtures.simple("USR-2").withCorrelationId("CORR-1");
            repo.save(b);
            em.flush();
        }).isInstanceOf(DataIntegrityViolationException.class)
          .hasRootCauseInstanceOf(SQLException.class);
    }
}

@Service
public class ResilientPaymentClient {

    private final RestClient http;

    @Retryable(retryFor = TransientFailure.class,
               maxAttempts = 4,
               backoff = @Backoff(delay = 100, multiplier = 2))
    public PaymentResult charge(ChargeRequest req) {
        try {
            return http.post().uri("/charge").body(req)
                .retrieve().body(PaymentResult.class);
        } catch (ResourceAccessException e) {
            throw new TransientFailure(e);
        }
    }

    @Recover
    public PaymentResult fallback(TransientFailure e, ChargeRequest req) {
        return PaymentResult.deferred(req.id());
    }
}

@SpringBootTest(webEnvironment = WebEnvironment.NONE)
class UserClientErrorTest {

    static WireMockServer wm;

    @BeforeAll static void start() {
        wm = new WireMockServer(0); wm.start();
    }
    @AfterAll  static void stop()  { wm.stop(); }
    @BeforeEach void reset()       { wm.resetAll(); }

    @DynamicPropertySource
    static void wireProps(DynamicPropertyRegistry r) {
        r.add("user-service.base-url", () -> "http://localhost:" + wm.port());
    }

    @Autowired UserClient client;

    @Test
    void notFound_returnsEmptyOptional() {
        wm.stubFor(get(urlEqualTo("/users/USR-404"))
            .willReturn(aResponse().withStatus(404)));

        Optional<User> u = client.findById("USR-404");

        assertThat(u).isEmpty();
    }

    @Test
    void serverError_throwsServiceException() {
        wm.stubFor(get(urlPathMatching("/users/.+"))
            .willReturn(aResponse().withStatus(503)
                .withBody("{\"error\":\"upstream_unavailable\"}")));

        assertThatThrownBy(() -> client.findById("USR-1"))
            .isInstanceOf(ServiceUnavailableException.class)
            .hasMessageContaining("upstream_unavailable");
    }

    @Test
    void slowResponse_triggersTimeout() {
        wm.stubFor(get(urlPathMatching("/users/.+"))
            .willReturn(aResponse().withFixedDelay(5_000).withStatus(200)));

        assertThatThrownBy(() -> client.findById("USR-1"))
            .hasRootCauseInstanceOf(SocketTimeoutException.class);
    }

    @Test
    void malformedJson_throwsDeserializationError() {
        wm.stubFor(get(urlPathMatching("/users/.+"))
            .willReturn(aResponse().withStatus(200)
                .withHeader("Content-Type", "application/json")
                .withBody("{ not valid json")));

        assertThatThrownBy(() -> client.findById("USR-1"))
            .hasCauseInstanceOf(JsonProcessingException.class);
    }

    @Test
    void rateLimited_retriesAfterDelay() {
        wm.stubFor(get(urlPathMatching("/users/.+"))
            .inScenario("rl").whenScenarioStateIs(STARTED)
            .willReturn(aResponse().withStatus(429).withHeader("Retry-After", "1"))
            .willSetStateTo("recovered"));
        wm.stubFor(get(urlPathMatching("/users/.+"))
            .inScenario("rl").whenScenarioStateIs("recovered")
            .willReturn(okJson("{\"id\":\"USR-1\",\"email\":\"a@b.com\"}")));

        Optional<User> u = client.findById("USR-1");

        assertThat(u).isPresent();
        wm.verify(2, getRequestedFor(urlPathMatching("/users/.+")));
    }
}

@Test
void concurrentSave_oneSucceeds_othersGetOptimisticLockException() throws Exception {
    UUID id = repo.save(OrderFixtures.simple("USR-1")).getId();
    em.flush(); em.clear();

    int threads = 10;
    ExecutorService exec = Executors.newFixedThreadPool(threads);
    CountDownLatch start = new CountDownLatch(1);
    AtomicInteger successes = new AtomicInteger();
    AtomicInteger conflicts = new AtomicInteger();

    List<Future<?>> futures = IntStream.range(0, threads).mapToObj(i ->
        exec.submit(() -> {
            start.await();
            try {
                tx.execute(status -> {
                    Order loaded = repo.findById(id).orElseThrow();
                    ReflectionTestUtils.setField(loaded, "status",
                        i % 2 == 0 ? OrderStatus.PAID : OrderStatus.SHIPPED);
                    repo.saveAndFlush(loaded);
                    return null;
                });
                successes.incrementAndGet();
            } catch (ObjectOptimisticLockingFailureException e) {
                conflicts.incrementAndGet();
            }
            return null;
        })).toList();

    start.countDown();
    for (Future<?> f : futures) f.get(5, TimeUnit.SECONDS);
    exec.shutdown();

    assertThat(successes).hasValue(1);
    assertThat(conflicts).hasValue(threads - 1);
}

@Test
void createOrder_s3Down_orderStillPersists_invoiceQueuedForRetry() {
    // simulate S3 outage by stopping the LocalStack S3 service mid-test
    localStack.execInContainer("supervisorctl", "stop", "s3");

    String token = tokenFor("alice");
    var response = restBuilder.build()
        .post().uri("http://localhost:" + port + "/api/v1/orders")
        .header("Authorization", "Bearer " + token)
        .contentType(MediaType.APPLICATION_JSON)
        .body(sampleOrder())
        .retrieve()
        .toEntity(OrderResponse.class);

    assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
    UUID orderId = response.getBody().id();

    // Order persisted in Postgres despite S3 failure
    assertThat(orderRepo.findById(orderId)).isPresent();

    // Invoice landed in retry queue, not the dead-letter
    await().atMost(Duration.ofSeconds(10)).untilAsserted(() -> {
        var msgs = sqs.receiveMessage(b -> b
            .queueUrl(queueUrl("invoice-retry"))).messages();
        assertThat(msgs).extracting(Message::body)
            .anyMatch(m -> m.contains(orderId.toString()));
    });
}

@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
@Testcontainers
@ActiveProfiles("test")
public abstract class FullStackTest {

    @Container @ServiceConnection
    static PostgreSQLContainer postgres =
        new PostgreSQLContainer<>("postgres:16-alpine").withReuse(true);

    @Container @ServiceConnection
    static GenericContainer redis =
        new GenericContainer<>("redis:7-alpine")
            .withExposedPorts(6379)
            .withReuse(true);

    @Container
    static LocalStackContainer localStack = new LocalStackContainer(
            DockerImageName.parse("localstack/localstack:3.8"))
        .withServices(Service.S3, Service.SQS).withReuse(true);

    @Container
    static KeycloakContainer keycloak = new KeycloakContainer("quay.io/keycloak/keycloak:26.0")
        .withRealmImportFile("/realm-export.json").withReuse(true);

    @DynamicPropertySource
    static void wireEverything(DynamicPropertyRegistry r) {
        // AWS SDK + Spring Cloud AWS
        r.add("aws.endpoint", localStack::getEndpoint);
        r.add("aws.region",   localStack::getRegion);
        r.add("aws.access-key", localStack::getAccessKey);
        r.add("aws.secret-key", localStack::getSecretKey);
        r.add("spring.cloud.aws.endpoint", localStack::getEndpoint);
        r.add("spring.cloud.aws.region.static", localStack::getRegion);

        // Keycloak
        r.add("spring.security.oauth2.resourceserver.jwt.issuer-uri",
            () -> keycloak.getAuthServerUrl() + "/realms/tdd-app");
        r.add("spring.security.oauth2.resourceserver.jwt.jwk-set-uri",
            () -> keycloak.getAuthServerUrl()
                + "/realms/tdd-app/protocol/openid-connect/certs");

        // Temporal — start an in-process test server
        r.add("temporal.serviceAddress", () -> TestEnv.testServerAddress());
    }

    @BeforeAll
    static void provision() throws Exception {
        localStack.execInContainer("awslocal", "s3",  "mb",            "s3://app-uploads");
        localStack.execInContainer("awslocal", "sqs", "create-queue",  "--queue-name", "order-events");
    }

    protected String tokenFor(String username) { /* password grant against keycloak */ }
}

class CreateOrderE2EIT extends FullStackTest {

    @LocalServerPort int port;
    @Autowired OrderRepository orderRepo;
    @Autowired CacheManager cacheManager;
    @Autowired S3Client s3;
    @Autowired SqsClient sqs;
    @Autowired WorkflowClient workflowClient;
    @Autowired RestClient.Builder restBuilder;

    @Test
    void createOrder_orchestratesEntireSystem() {
        String token = tokenFor("alice");
        var body = Map.of(
            "userId", "USR-alice",
            "items", List.of(Map.of("sku","SKU-1","quantity",2,"unitPrice",9.99)),
            "contactEmail", "alice@example.com",
            "orderDate", LocalDate.now().toString());

        // 1) Hit the API with a real Keycloak token
        ResponseEntity response = restBuilder.build()
            .post().uri("http://localhost:" + port + "/api/v1/orders")
            .header("Authorization", "Bearer " + token)
            .contentType(MediaType.APPLICATION_JSON)
            .body(body)
            .retrieve()
            .toEntity(OrderResponse.class);

        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.CREATED);
        UUID orderId = response.getBody().id();

        // 2) Postgres persisted the order
        await().atMost(Duration.ofSeconds(5)).untilAsserted(() ->
            assertThat(orderRepo.findById(orderId)).isPresent());

        // 3) Redis cached the read-side projection
        await().atMost(Duration.ofSeconds(5)).untilAsserted(() ->
            assertThat(cacheManager.getCache("orders").get(orderId)).isNotNull());

        // 4) S3 received the invoice PDF
        await().atMost(Duration.ofSeconds(10)).untilAsserted(() -> {
            ListObjectsV2Response listing = s3.listObjectsV2(b -> b.bucket("app-uploads"));
            assertThat(listing.contents())
                .extracting(S3Object::key)
                .anyMatch(k -> k.contains(orderId.toString()));
        });

        // 5) SQS got the OrderCreated event
        await().atMost(Duration.ofSeconds(10)).untilAsserted(() -> {
            var msgs = sqs.receiveMessage(b -> b
                .queueUrl(queueUrl("order-events"))
                .waitTimeSeconds(2)).messages();
            assertThat(msgs)
                .extracting(Message::body)
                .anyMatch(s -> s.contains(orderId.toString()));
        });

        // 6) A Temporal workflow was scheduled for fulfillment
        await().atMost(Duration.ofSeconds(10)).untilAsserted(() -> {
            DescribeWorkflowExecutionResponse desc = workflowClient
                .getWorkflowServiceStubs()
                .blockingStub()
                .describeWorkflowExecution(DescribeWorkflowExecutionRequest.newBuilder()
                    .setNamespace("default")
                    .setExecution(WorkflowExecution.newBuilder()
                        .setWorkflowId("order-" + orderId).build())
                    .build());
            assertThat(desc.getWorkflowExecutionInfo().getStatus())
                .isIn(WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_RUNNING,
                      WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_COMPLETED);
        });
    }
}

// Set / read private fields
ReflectionTestUtils.setField(target, "fieldName", value);
Object v = ReflectionTestUtils.getField(target, "fieldName");

// Set field declared on a superclass
ReflectionTestUtils.setField(target, Parent.class, "name", "x", String.class);

// Invoke private method (varargs)
Object out = ReflectionTestUtils.invokeMethod(target, "doStuff", arg1, arg2);

// Invoke a setter (rare)
ReflectionTestUtils.invokeSetterMethod(target, "user", aUser);

// Wait until a condition becomes true
await().atMost(Duration.ofSeconds(5))
       .until(() -> repo.count() == 1);

// Wait until an assertion stops failing
await().atMost(Duration.ofSeconds(5))
       .untilAsserted(() ->
            assertThat(captured.get()).isNotNull());

// Polling interval + ignore exceptions during ramp-up
await().pollInterval(Duration.ofMillis(50))
       .pollDelay(Duration.ofMillis(200))
       .atMost(Duration.ofSeconds(10))
       .ignoreExceptionsInstanceOf(NoSuchKeyException.class)
       .untilAsserted(() ->
            assertThat(s3.headObject(req)).isNotNull());