theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/tdd-quarkus/SKILL.md

@@ -0,0 +1,817 @@
+---
+name: tdd-quarkus
+description: Desarrollo guiado por tests (TDD) para Quarkus 3.x LTS con JUnit 5, Mockito, REST Assured, testing de rutas Camel y JaCoCo. Úsala al añadir funcionalidades, corregir defectos o refactorizar servicios orientados a eventos.
+---
+
+# Flujo TDD para Quarkus
+
+Guía de TDD para servicios Quarkus 3.x con cobertura de 80 %+ (unitaria + integración). Optimizada para arquitecturas orientadas a eventos con Apache Camel.
+
+## Cuándo usarla
+
+- Nuevas funcionalidades o endpoints REST
+- Corrección de defectos o refactorizaciones
+- Al añadir lógica de acceso a datos, reglas de seguridad o streams reactivos
+- Al probar rutas de Apache Camel y manejadores de eventos
+- Al probar servicios orientados a eventos con RabbitMQ
+- Al probar lógica de flujos condicionales
+- Al validar operaciones asíncronas con CompletableFuture
+- Al probar la propagación de LogContext
+
+## Flujo de trabajo
+
+1. Escribe primero los tests (deben fallar)
+2. Implementa el mínimo código para que pasen
+3. Refactoriza con los tests en verde
+4. Exige la cobertura con JaCoCo (objetivo 80 %+)
+
+## Tests unitarios con organización @Nested
+
+Sigue este enfoque estructurado para tests completos y legibles:
+
+```java
+@ExtendWith(MockitoExtension.class)
+@DisplayName("Tests unitarios de OrderService")
+class OrderServiceTest {
+
+  @Mock
+  private OrderRepository orderRepository;
+
+  @Mock
+  private EventService eventService;
+
+  @Mock
+  private FulfillmentPublisher fulfillmentPublisher;
+
+  @InjectMocks
+  private OrderService orderService;
+
+  private CreateOrderCommand validCommand;
+
+  @BeforeEach
+  void setUp() {
+    validCommand = new CreateOrderCommand(
+        "customer-123",
+        List.of(new OrderLine("sku-123", 2))
+    );
+  }
+
+  @Nested
+  @DisplayName("Tests de createOrder")
+  class CreateOrder {
+
+    @Test
+    @DisplayName("Debe persistir la orden y publicar el evento de fulfillment")
+    void givenValidCommand_whenCreateOrder_thenPersistsAndPublishes() {
+      // PREPARAR
+      doNothing().when(orderRepository).persist(any(Order.class));
+
+      // ACTUAR
+      OrderReceipt receipt = orderService.createOrder(validCommand);
+
+      // VERIFICAR
+      assertThat(receipt).isNotNull();
+      assertThat(receipt.customerId()).isEqualTo("customer-123");
+      verify(orderRepository).persist(any(Order.class));
+      verify(fulfillmentPublisher).publishAsync(receipt);
+      verify(eventService).createSuccessEvent(receipt, "ORDER_CREATED");
+    }
+
+    @Test
+    @DisplayName("Debe rechazar un id de cliente ausente")
+    void givenMissingCustomerId_whenCreateOrder_thenThrowsBadRequest() {
+      // PREPARAR
+      CreateOrderCommand invalid = new CreateOrderCommand("", validCommand.lines());
+
+      // ACTUAR Y VERIFICAR
+      WebApplicationException exception = assertThrows(
+          WebApplicationException.class,
+          () -> orderService.createOrder(invalid)
+      );
+
+      assertThat(exception.getResponse().getStatus()).isEqualTo(400);
+      verify(orderRepository, never()).persist(any(Order.class));
+      verify(fulfillmentPublisher, never()).publishAsync(any());
+    }
+
+    @Test
+    @DisplayName("Debe registrar un evento de error cuando la persistencia falla")
+    void givenPersistenceFailure_whenCreateOrder_thenRecordsErrorEvent() {
+      // PREPARAR
+      doThrow(new PersistenceException("database unavailable"))
+          .when(orderRepository).persist(any(Order.class));
+
+      // ACTUAR Y VERIFICAR
+      PersistenceException exception = assertThrows(
+          PersistenceException.class,
+          () -> orderService.createOrder(validCommand)
+      );
+
+      assertThat(exception.getMessage()).contains("database unavailable");
+      verify(eventService).createErrorEvent(
+          eq(validCommand),
+          eq("ORDER_CREATE_FAILED"),
+          contains("database unavailable")
+      );
+      verify(fulfillmentPublisher, never()).publishAsync(any());
+    }
+
+    @Test
+    @DisplayName("Debe rechazar comandos nulos")
+    void givenNullCommand_whenCreateOrder_thenThrowsNullPointerException() {
+      // ACTUAR Y VERIFICAR
+      assertThrows(
+          NullPointerException.class,
+          () -> orderService.createOrder(null)
+      );
+
+      verify(orderRepository, never()).persist(any(Order.class));
+    }
+  }
+}
+```
+
+### Patrones clave de testing
+
+1. **Clases @Nested**: agrupa los tests por método bajo prueba
+2. **@DisplayName**: descripciones legibles para los reportes de tests
+3. **Convención de nombres**: `givenX_whenY_thenZ` para mayor claridad
+4. **Patrón AAA**: comentarios explícitos `// PREPARAR`, `// ACTUAR`, `// VERIFICAR`
+5. **@BeforeEach**: prepara datos comunes para reducir duplicación
+6. **assertDoesNotThrow**: prueba escenarios de éxito sin capturar excepciones
+7. **assertThrows**: prueba escenarios de excepción validando el mensaje con AssertJ
+8. **Cobertura exhaustiva**: prueba caminos felices, entradas nulas, casos límite y excepciones
+9. **Verificar interacciones**: usa `verify()` de Mockito para asegurar que los métodos se llaman correctamente
+10. **Verificar ausencia**: usa `never()` para asegurar que ciertos métodos NO se llaman en escenarios de error
+
+## Testing de rutas Camel
+
+```java
+@QuarkusTest
+@DisplayName("Tests de la ruta Camel de reglas de negocio")
+class BusinessRulesRouteTest {
+
+  @Inject
+  CamelContext camelContext;
+
+  @Inject
+  ProducerTemplate producerTemplate;
+
+  @InjectMock
+  EventService eventService;
+
+  @InjectMock
+  DocumentValidator documentValidator;
+
+  private BusinessRulesPayload testPayload;
+
+  @BeforeEach
+  void setUp() {
+    // PREPARAR - Datos de prueba
+    testPayload = new BusinessRulesPayload();
+    testPayload.setDocumentId(1L);
+    testPayload.setFlowProfile(FlowProfile.BASIC);
+  }
+
+  @Nested
+  @DisplayName("Tests de la ruta business-rules-publisher")
+  class BusinessRulesPublisher {
+
+    @Test
+    @DisplayName("Debe publicar correctamente el mensaje en RabbitMQ")
+    void givenValidPayload_whenPublish_thenMessageSentToQueue() throws Exception {
+      // PREPARAR
+      MockEndpoint mockRabbitMQ = camelContext.getEndpoint("mock:rabbitmq", MockEndpoint.class);
+      mockRabbitMQ.expectedMessageCount(1);
+
+      // Reemplaza el endpoint real por un mock para el test
+      camelContext.getRouteController().stopRoute("business-rules-publisher");
+      AdviceWith.adviceWith(camelContext, "business-rules-publisher", advice -> {
+        advice.replaceFromWith("direct:business-rules-publisher");
+        advice.weaveByToString(".*spring-rabbitmq.*").replace().to("mock:rabbitmq");
+      });
+      camelContext.getRouteController().startRoute("business-rules-publisher");
+
+      // ACTUAR
+      producerTemplate.sendBody("direct:business-rules-publisher", testPayload);
+
+      // VERIFICAR — el body es un String JSON tras .marshal().json(JsonLibrary.Jackson)
+      mockRabbitMQ.assertIsSatisfied(5000);
+
+      assertThat(mockRabbitMQ.getExchanges()).hasSize(1);
+      String body = mockRabbitMQ.getExchanges().get(0).getIn().getBody(String.class);
+      assertThat(body).contains("\"documentId\":1");
+    }
+
+    @Test
+    @DisplayName("Debe realizar el marshalling a JSON")
+    void givenPayload_whenPublish_thenMarshalledToJson() throws Exception {
+      // PREPARAR
+      MockEndpoint mockMarshal = new MockEndpoint("mock:marshal");
+      camelContext.addEndpoint("mock:marshal", mockMarshal);
+      mockMarshal.expectedMessageCount(1);
+
+      camelContext.getRouteController().stopRoute("business-rules-publisher");
+      AdviceWith.adviceWith(camelContext, "business-rules-publisher", advice -> {
+        advice.weaveAddLast().to("mock:marshal");
+      });
+      camelContext.getRouteController().startRoute("business-rules-publisher");
+
+      // ACTUAR
+      producerTemplate.sendBody("direct:business-rules-publisher", testPayload);
+
+      // VERIFICAR
+      mockMarshal.assertIsSatisfied(5000);
+
+      String body = mockMarshal.getExchanges().get(0).getIn().getBody(String.class);
+      assertThat(body).contains("\"documentId\":1");
+      assertThat(body).contains("\"flowProfile\":\"BASIC\"");
+    }
+  }
+
+  @Nested
+  @DisplayName("Tests de la ruta document-processing")
+  class DocumentProcessing {
+
+    @Test
+    @DisplayName("Debe enrutar la factura al procesador correcto")
+    void givenInvoiceType_whenProcess_thenRoutesToInvoiceProcessor() throws Exception {
+      // PREPARAR
+      MockEndpoint mockInvoice = camelContext.getEndpoint("mock:invoice", MockEndpoint.class);
+      mockInvoice.expectedMessageCount(1);
+
+      camelContext.getRouteController().stopRoute("document-processing");
+      AdviceWith.adviceWith(camelContext, "document-processing", advice -> {
+        advice.weaveByToString(".*direct:process-invoice.*").replace().to("mock:invoice");
+      });
+      camelContext.getRouteController().startRoute("document-processing");
+
+      // ACTUAR
+      producerTemplate.sendBodyAndHeader("direct:process-document",
+          testPayload, "documentType", "INVOICE");
+
+      // VERIFICAR
+      mockInvoice.assertIsSatisfied(5000);
+    }
+
+    @Test
+    @DisplayName("Debe manejar los errores de validación con elegancia")
+    void givenValidationError_whenProcess_thenRoutesToErrorHandler() throws Exception {
+      // PREPARAR
+      MockEndpoint mockError = camelContext.getEndpoint("mock:error", MockEndpoint.class);
+      mockError.expectedMessageCount(1);
+
+      camelContext.getRouteController().stopRoute("document-processing");
+      AdviceWith.adviceWith(camelContext, "document-processing", advice -> {
+        advice.weaveByToString(".*direct:validation-error-handler.*")
+            .replace().to("mock:error");
+      });
+      camelContext.getRouteController().startRoute("document-processing");
+
+      // Mockea el bean validador para que lance una excepción
+      when(documentValidator.validate(any())).thenThrow(new ValidationException("Invalid document"));
+
+      // ACTUAR
+      producerTemplate.sendBody("direct:process-document", testPayload);
+
+      // VERIFICAR
+      mockError.assertIsSatisfied(5000);
+
+      Exception exception = mockError.getExchanges().get(0).getException();
+      assertThat(exception).isInstanceOf(ValidationException.class);
+      assertThat(exception.getMessage()).contains("Invalid document");
+    }
+  }
+}
+```
+
+## Testing de servicios de eventos
+
+```java
+@ExtendWith(MockitoExtension.class)
+@DisplayName("Tests unitarios de EventService")
+class EventServiceTest {
+
+  @Mock
+  private EventRepository eventRepository;
+
+  @Mock
+  private ObjectMapper objectMapper;
+
+  @InjectMocks
+  private EventService eventService;
+
+  private BusinessRulesPayload testPayload;
+
+  @BeforeEach
+  void setUp() {
+    // PREPARAR
+    testPayload = new BusinessRulesPayload();
+    testPayload.setDocumentId(1L);
+  }
+
+  @Nested
+  @DisplayName("Tests de createSuccessEvent")
+  class CreateSuccessEvent {
+
+    @Test
+    @DisplayName("Debe crear un evento de éxito con los atributos correctos")
+    void givenValidPayload_whenCreateSuccessEvent_thenEventPersisted() throws Exception {
+      // PREPARAR
+      when(objectMapper.writeValueAsString(testPayload)).thenReturn("{\"documentId\":1}");
+
+      // ACTUAR
+      assertDoesNotThrow(() ->
+          eventService.createSuccessEvent(testPayload, "DOCUMENT_PROCESSED"));
+
+      // VERIFICAR
+      verify(eventRepository).persist(argThat(event ->
+          event.getType().equals("DOCUMENT_PROCESSED") &&
+          event.getStatus() == EventStatus.SUCCESS &&
+          event.getPayload().equals("{\"documentId\":1}") &&
+          event.getTimestamp() != null
+      ));
+    }
+
+    @Test
+    @DisplayName("Debe lanzar una excepción cuando el payload es nulo")
+    void givenNullPayload_whenCreateSuccessEvent_thenThrowsException() {
+      // PREPARAR
+      Object nullPayload = null;
+
+      // ACTUAR Y VERIFICAR
+      NullPointerException exception = assertThrows(
+          NullPointerException.class,
+          () -> eventService.createSuccessEvent(nullPayload, "EVENT_TYPE")
+      );
+
+      assertThat(exception.getMessage()).isEqualTo("El payload no puede ser nulo");
+      verify(eventRepository, never()).persist(any());
+    }
+  }
+
+  @Nested
+  @DisplayName("Tests de createErrorEvent")
+  class CreateErrorEvent {
+
+    @Test
+    @DisplayName("Debe crear un evento de error con el mensaje de error")
+    void givenError_whenCreateErrorEvent_thenEventPersistedWithMessage() throws Exception {
+      // PREPARAR
+      String errorMessage = "Processing failed";
+      when(objectMapper.writeValueAsString(testPayload)).thenReturn("{\"documentId\":1}");
+
+      // ACTUAR
+      assertDoesNotThrow(() ->
+          eventService.createErrorEvent(testPayload, "PROCESSING_ERROR", errorMessage));
+
+      // VERIFICAR
+      verify(eventRepository).persist(argThat(event ->
+          event.getType().equals("PROCESSING_ERROR") &&
+          event.getStatus() == EventStatus.ERROR &&
+          event.getErrorMessage().equals(errorMessage) &&
+          event.getPayload().equals("{\"documentId\":1}")
+      ));
+    }
+
+    @ParameterizedTest
+    @DisplayName("Debe rechazar mensajes de error inválidos")
+    @ValueSource(strings = {"", " "})
+    void givenBlankErrorMessage_whenCreateErrorEvent_thenThrowsException(String blankMessage) {
+      // ACTUAR Y VERIFICAR
+      IllegalArgumentException exception = assertThrows(
+          IllegalArgumentException.class,
+          () -> eventService.createErrorEvent(testPayload, "ERROR", blankMessage)
+      );
+
+      assertThat(exception.getMessage()).contains("El mensaje de error no puede estar en blanco");
+    }
+  }
+}
+```
+
+## Testing de CompletableFuture
+
+```java
+@ExtendWith(MockitoExtension.class)
+@DisplayName("Tests unitarios de FileStorageService")
+class FileStorageServiceTest {
+
+  @Mock
+  private S3Client s3Client;
+
+  @Mock
+  private ExecutorService executorService;
+
+  @InjectMocks
+  private FileStorageService fileStorageService;
+
+  private InputStream testInputStream;
+  private LogContext testLogContext;
+
+  @BeforeEach
+  void setUp() {
+    // PREPARAR
+    testInputStream = new ByteArrayInputStream("test content".getBytes());
+    testLogContext = new LogContext();
+    testLogContext.put("traceId", "trace-123");
+  }
+
+  @Nested
+  @DisplayName("Tests de uploadOriginalFile")
+  class UploadOriginalFile {
+
+    @Test
+    @DisplayName("Debe subir el archivo con éxito y devolver la info del documento")
+    void givenValidFile_whenUpload_thenReturnsDocumentInfo() throws Exception {
+      // PREPARAR
+      doAnswer(invocation -> {
+        ((Runnable) invocation.getArgument(0)).run();
+        return null;
+      }).when(executorService).execute(any(Runnable.class));
+
+      when(s3Client.putObject(any(PutObjectRequest.class), any(RequestBody.class)))
+          .thenReturn(PutObjectResponse.builder().build());
+
+      // ACTUAR
+      CompletableFuture<StoredDocumentInfo> future =
+          fileStorageService.uploadOriginalFile(testInputStream, 1024L,
+              testLogContext, InvoiceFormat.UBL);
+
+      StoredDocumentInfo result = future.join();
+
+      // VERIFICAR
+      assertThat(result).isNotNull();
+      assertThat(result.getPath()).isNotBlank();
+      assertThat(result.getSize()).isEqualTo(1024L);
+      assertThat(result.getUploadedAt()).isNotNull();
+
+      verify(s3Client).putObject(any(PutObjectRequest.class), any(RequestBody.class));
+    }
+
+    @Test
+    @DisplayName("Debe manejar el fallo de subida a S3")
+    void givenS3Failure_whenUpload_thenCompletableFutureFails() {
+      // PREPARAR — ejecuta de forma síncrona para que la excepción se propague por el future
+      doAnswer(invocation -> {
+        ((Runnable) invocation.getArgument(0)).run();
+        return null;
+      }).when(executorService).execute(any(Runnable.class));
+
+      when(s3Client.putObject(any(PutObjectRequest.class), any(RequestBody.class)))
+          .thenThrow(new StorageException("S3 unavailable"));
+
+      // ACTUAR
+      CompletableFuture<StoredDocumentInfo> future =
+          fileStorageService.uploadOriginalFile(testInputStream, 1024L,
+              testLogContext, InvoiceFormat.UBL);
+
+      // VERIFICAR
+      assertThatThrownBy(() -> future.join())
+          .isInstanceOf(CompletionException.class)
+          .hasCauseInstanceOf(StorageException.class)
+          .hasMessageContaining("S3 unavailable");
+    }
+
+    @Test
+    @DisplayName("Debe propagar el LogContext a la operación asíncrona")
+    void givenLogContext_whenUpload_thenContextPropagated() throws Exception {
+      // PREPARAR
+      AtomicReference<LogContext> capturedContext = new AtomicReference<>();
+
+      doAnswer(invocation -> {
+        capturedContext.set(CustomLog.getCurrentContext());
+        ((Runnable) invocation.getArgument(0)).run();
+        return null;
+      }).when(executorService).execute(any(Runnable.class));
+
+      // ACTUAR
+      fileStorageService.uploadOriginalFile(testInputStream, 1024L,
+          testLogContext, InvoiceFormat.UBL).join();
+
+      // VERIFICAR
+      assertThat(capturedContext.get()).isNotNull();
+      assertThat(capturedContext.get().get("traceId")).isEqualTo("trace-123");
+    }
+  }
+}
+```
+
+## Tests de la capa resource (REST Assured)
+
+```java
+@QuarkusTest
+@DisplayName("Tests de API de DocumentResource")
+class DocumentResourceTest {
+
+  @InjectMock
+  DocumentService documentService;
+
+  @Nested
+  @DisplayName("Tests de GET /api/documents")
+  class ListDocuments {
+
+    @Test
+    @DisplayName("Debe devolver la lista de documentos")
+    void givenDocumentsExist_whenList_thenReturnsOk() {
+      // PREPARAR
+      List<Document> documents = List.of(createDocument(1L, "DOC-001"));
+      when(documentService.list(0, 20)).thenReturn(documents);
+
+      // ACTUAR Y VERIFICAR
+      given()
+          .when().get("/api/documents")
+          .then()
+          .statusCode(200)
+          .body("$.size()", is(1))
+          .body("[0].referenceNumber", equalTo("DOC-001"));
+    }
+  }
+
+  @Nested
+  @DisplayName("Tests de POST /api/documents")
+  class CreateDocument {
+
+    @Test
+    @DisplayName("Debe crear el documento y devolver 201")
+    void givenValidRequest_whenCreate_thenReturns201() {
+      // PREPARAR
+      Document document = createDocument(1L, "DOC-001");
+      when(documentService.create(any())).thenReturn(document);
+
+      // ACTUAR Y VERIFICAR
+      given()
+          .contentType(ContentType.JSON)
+          .body("""
+              {
+                "referenceNumber": "DOC-001",
+                "description": "Documento de prueba",
+                "validUntil": "2030-01-01T00:00:00Z",
+                "categories": ["test"]
+              }
+              """)
+          .when().post("/api/documents")
+          .then()
+          .statusCode(201)
+          .header("Location", containsString("/api/documents/1"))
+          .body("referenceNumber", equalTo("DOC-001"));
+    }
+
+    @Test
+    @DisplayName("Debe devolver 400 ante entrada inválida")
+    void givenInvalidRequest_whenCreate_thenReturns400() {
+      // ACTUAR Y VERIFICAR
+      given()
+          .contentType(ContentType.JSON)
+          .body("""
+              {
+                "referenceNumber": "",
+                "description": "Prueba"
+              }
+              """)
+          .when().post("/api/documents")
+          .then()
+          .statusCode(400);
+    }
+  }
+
+  private Document createDocument(Long id, String referenceNumber) {
+    Document document = new Document();
+    document.setId(id);
+    document.setReferenceNumber(referenceNumber);
+    document.setStatus(DocumentStatus.PENDING);
+    return document;
+  }
+}
+```
+
+## Tests de integración con base de datos real
+
+```java
+@QuarkusTest
+@TestProfile(IntegrationTestProfile.class)
+@DisplayName("Tests de integración de documentos")
+class DocumentIntegrationTest {
+
+  @Test
+  @Transactional
+  @DisplayName("Debe crear y recuperar un documento vía API")
+  void givenNewDocument_whenCreateAndRetrieve_thenSuccessful() {
+    // ACTUAR - Crear vía API
+    Long id = given()
+        .contentType(ContentType.JSON)
+        .body("""
+            {
+              "referenceNumber": "INT-001",
+              "description": "Test de integración",
+              "validUntil": "2030-01-01T00:00:00Z",
+              "categories": ["test"]
+            }
+            """)
+        .when().post("/api/documents")
+        .then()
+        .statusCode(201)
+        .extract().path("id");
+
+    // VERIFICAR - Recuperar vía API
+    given()
+        .when().get("/api/documents/" + id)
+        .then()
+        .statusCode(200)
+        .body("referenceNumber", equalTo("INT-001"));
+  }
+}
+```
+
+## Cobertura con JaCoCo
+
+### Configuración Maven (completa)
+
+```xml
+<plugin>
+  <groupId>org.jacoco</groupId>
+  <artifactId>jacoco-maven-plugin</artifactId>
+  <version>0.8.13</version>
+  <executions>
+    <!-- Prepara el agente para la ejecución de tests -->
+    <execution>
+      <id>prepare-agent</id>
+      <goals>
+        <goal>prepare-agent</goal>
+      </goals>
+    </execution>
+
+    <!-- Genera el reporte de cobertura -->
+    <execution>
+      <id>report</id>
+      <phase>verify</phase>
+      <goals>
+        <goal>report</goal>
+      </goals>
+    </execution>
+
+    <!-- Exige los umbrales de cobertura -->
+    <execution>
+      <id>check</id>
+      <goals>
+        <goal>check</goal>
+      </goals>
+      <configuration>
+        <rules>
+          <rule>
+            <element>BUNDLE</element>
+            <limits>
+              <limit>
+                <counter>LINE</counter>
+                <value>COVEREDRATIO</value>
+                <minimum>0.80</minimum>
+              </limit>
+              <limit>
+                <counter>BRANCH</counter>
+                <value>COVEREDRATIO</value>
+                <minimum>0.70</minimum>
+              </limit>
+            </limits>
+          </rule>
+        </rules>
+      </configuration>
+    </execution>
+  </executions>
+</plugin>
+```
+
+Ejecuta los tests con cobertura:
+```bash
+mvn clean test
+mvn jacoco:report
+mvn jacoco:check
+
+# Reporte en: target/site/jacoco/index.html
+```
+
+## Dependencias de test
+
+```xml
+<dependencies>
+    <!-- Testing de Quarkus -->
+    <dependency>
+        <groupId>io.quarkus</groupId>
+        <artifactId>quarkus-junit5</artifactId>
+        <scope>test</scope>
+    </dependency>
+    <dependency>
+        <groupId>io.quarkus</groupId>
+        <artifactId>quarkus-junit5-mockito</artifactId>
+        <scope>test</scope>
+    </dependency>
+
+    <!-- Mockito -->
+    <dependency>
+        <groupId>org.mockito</groupId>
+        <artifactId>mockito-core</artifactId>
+        <scope>test</scope>
+    </dependency>
+
+    <!-- AssertJ (preferido sobre las aserciones de JUnit) -->
+    <dependency>
+        <groupId>org.assertj</groupId>
+        <artifactId>assertj-core</artifactId>
+        <version>3.24.2</version>
+        <scope>test</scope>
+    </dependency>
+
+    <!-- REST Assured -->
+    <dependency>
+        <groupId>io.rest-assured</groupId>
+        <artifactId>rest-assured</artifactId>
+        <scope>test</scope>
+    </dependency>
+
+    <!-- Testing de Camel -->
+    <dependency>
+        <groupId>org.apache.camel.quarkus</groupId>
+        <artifactId>camel-quarkus-junit5</artifactId>
+        <scope>test</scope>
+    </dependency>
+</dependencies>
+```
+
+## Buenas prácticas
+
+### Organización de tests
+- Usa clases `@Nested` para agrupar tests por método bajo prueba
+- Usa `@DisplayName` para descripciones legibles visibles en los reportes
+- Sigue la convención `givenX_whenY_thenZ` en los nombres de métodos de test
+- Usa `@BeforeEach` para preparar datos comunes y reducir duplicación
+
+### Estructura de tests
+- Sigue el patrón AAA con comentarios explícitos (`// PREPARAR`, `// ACTUAR`, `// VERIFICAR`)
+- Usa `assertDoesNotThrow` para escenarios de éxito
+- Usa `assertThrows` para escenarios de excepción validando el mensaje
+- Verifica que los mensajes de excepción coinciden con lo esperado usando `contains()` o `isEqualTo()` de AssertJ
+
+### Cobertura de tests
+- Prueba los caminos felices de todos los métodos públicos
+- Prueba el manejo de entradas nulas
+- Prueba casos límite (colecciones vacías, valores frontera, IDs negativos, strings en blanco)
+- Prueba exhaustivamente los escenarios de excepción
+- Mockea todas las dependencias externas (repositorios, servicios, endpoints de Camel)
+- Apunta a 80 %+ de cobertura de líneas y 70 %+ de ramas
+
+### Aserciones
+- **Prefiere AssertJ** (`assertThat`) sobre las aserciones de JUnit para comprobar valores
+- Usa la API fluida de AssertJ para legibilidad: `assertThat(list).hasSize(3).contains(item)`
+- Para excepciones: captura con `assertThrows` de JUnit y valida el mensaje con AssertJ
+- Para caminos de éxito sin excepciones: usa `assertDoesNotThrow` de JUnit
+- Para colecciones: `extracting()`, `filteredOn()`, `containsExactly()`
+
+### Integración en tests
+- Usa `@QuarkusTest` para tests de integración
+- Usa `@InjectMock` para mockear dependencias en tests de Quarkus
+- Prefiere REST Assured para probar la API
+- Usa `@TestProfile` para configuración específica de tests
+
+### Testing orientado a eventos
+- Prueba rutas de Camel con `AdviceWith` y `MockEndpoint`
+- Usa la anotación `@CamelQuarkusTest` (si usas tests independientes de Camel)
+- Verifica el contenido de los mensajes, cabeceras y lógica de enrutamiento
+- Prueba las rutas de manejo de errores por separado
+- Mockea sistemas externos (RabbitMQ, S3, bases de datos) en tests unitarios
+
+### Testing de rutas Camel
+- Usa `MockEndpoint` para verificar el flujo de mensajes
+- Usa `AdviceWith` para modificar rutas en tests (reemplazar endpoints por mocks)
+- Prueba la transformación y el marshalling de mensajes
+- Prueba el manejo de excepciones y las dead letter queues
+
+### Testing de operaciones asíncronas
+- Prueba los escenarios de éxito y fallo de CompletableFuture
+- Usa `.join()` en tests para esperar la finalización asíncrona
+- Prueba la propagación de excepciones desde CompletableFuture
+- Verifica la propagación del LogContext a las operaciones asíncronas
+
+### Rendimiento
+- Mantén los tests rápidos y aislados
+- Ejecuta los tests en modo continuo: `mvn quarkus:test`
+- Usa tests parametrizados (`@ParameterizedTest`) para variaciones de entrada
+- Construye builders de datos de prueba o métodos factory reutilizables
+
+### Específico de Quarkus
+- Mantente en la última versión LTS (Quarkus 3.x)
+- Prueba periódicamente la compatibilidad con compilación nativa
+- Usa perfiles de test de Quarkus para distintos escenarios
+- Aprovecha los dev services de Quarkus para pruebas locales
+- Usa `@InjectMock` en lugar de `@MockBean` (específico de Quarkus)
+
+### Buenas prácticas de verificación
+- Verifica siempre las interacciones sobre las dependencias mockeadas
+- Usa `verify(mock, never())` para asegurar que ciertos métodos NO se llaman en escenarios de error
+- Usa `argThat()` para coincidencia compleja de argumentos
+- Verifica el orden de las llamadas cuando importe: `InOrder` de Mockito
+
+## Skills relacionadas
+
+- `patrones-quarkus`
+- `seguridad-quarkus`
+- `verificacion-quarkus`
+- `flujo-tdd`