qa-skills 3.0.0

package/skills/qa-spring-test-writer/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: qa-spring-test-writer
+description: Generate Spring Boot integration tests with @SpringBootTest, MockMvc, TestContainers, @DataJpaTest, WebTestClient, and profile-based configuration.
+output_dir: tests/integration
+---
+
+# QA Spring Test Writer
+
+## Purpose
+
+Write Spring Boot integration tests from test case specifications. Transform structured test cases into executable Spring test files with @SpringBootTest, MockMvc for REST controller testing, TestContainers for database integration, @DataJpaTest for repository testing, and WebTestClient for WebFlux.
+
+## Trigger Phrases
+
+- "Write Spring Boot integration tests for [feature]"
+- "Generate MockMvc tests for [controller]"
+- "Create TestContainers tests for [entity/repository]"
+- "Add @DataJpaTest for [repository]"
+- "Spring Boot integration tests with MockMvc"
+- "WebTestClient tests for WebFlux [endpoint]"
+- "Spring integration tests with TestContainers"
+- "MockMvc tests with @MockBean"
+
+## Key Features
+
+| Feature | Description |
+| ------- | ----------- |
+| **@SpringBootTest** | Full application context; webEnvironment for servlet/reactive |
+| **MockMvc** | REST controller testing without HTTP; perform(get/post).andExpect |
+| **TestContainers** | @Container + PostgreSQLContainer, MySQLContainer for real DB |
+| **@DataJpaTest** | Slice test for JPA repositories; in-memory or TestContainer DB |
+| **WebTestClient** | WebFlux controller testing; bindToController or full server |
+| **@MockBean** | Mock service dependencies in integration tests |
+| **@TestPropertySource** | Override properties; use test profile |
+| **@Transactional** | Rollback after each test for data cleanup |
+
+## Workflow
+
+1. **Read test cases** — From specs, requirements, or API contracts
+2. **Analyze Java code** — Inspect controllers, services, repositories
+3. **Choose test type** — MockMvc (controller), @DataJpaTest (repository), full @SpringBootTest (integration)
+4. **Generate tests** — Produce `{Feature}IntegrationTest.java`
+5. **Configure TestContainers** — Add @Container for DB when needed
+6. **Run** — User runs `mvn test` or `./gradlew test`
+
+## Key Patterns
+
+| Pattern | Usage |
+| ------- | ----- |
+| `mockMvc.perform(get("/api/users")).andExpect(status().isOk())` | MockMvc GET |
+| `mockMvc.perform(post("/api/users").contentType(JSON).content(body)).andExpect(status().isCreated())` | MockMvc POST |
+| `jsonPath("$.id").value(1)` | JSON path assertion |
+| `@Container static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")` | TestContainers DB |
+| `@DataJpaTest` | Repository slice test |
+| `repository.save(entity); assertEquals(1, repository.findAll().size())` | Repository assertions |
+| `webTestClient.get().uri("/api/users").exchange().expectStatus().isOk()` | WebTestClient |
+| `@MockBean UserService userService` | Mock service in context |
+
+## MockMvc Patterns
+
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+class UserControllerIntegrationTest {
+    @Autowired MockMvc mockMvc;
+
+    @Test
+    void getUsers_returnsOk() throws Exception {
+        mockMvc.perform(get("/api/users"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$").isArray());
+    }
+
+    @Test
+    void createUser_returnsCreated() throws Exception {
+        String body = "{\"name\":\"John\",\"email\":\"john@example.com\"}";
+        mockMvc.perform(post("/api/users")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(body))
+            .andExpect(status().isCreated())
+            .andExpect(jsonPath("$.id").exists());
+    }
+}
+```
+
+## TestContainers + @DataJpaTest
+
+```java
+@DataJpaTest
+@Testcontainers
+class UserRepositoryIntegrationTest {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");
+
+    @DynamicPropertySource
+    static void configureProperties(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+    }
+
+    @Autowired UserRepository repository;
+
+    @Test
+    void save_findsById() {
+        User user = new User("John", "john@example.com");
+        User saved = repository.save(user);
+        assertThat(repository.findById(saved.getId())).isPresent();
+    }
+}
+```
+
+## File Naming
+
+- `{Feature}IntegrationTest.java` — Integration test classes (e.g., `UserControllerIntegrationTest.java`, `OrderRepositoryIntegrationTest.java`)
+- Place in `src/test/java` per Maven/Gradle convention
+
+## Scope
+
+**Can do (autonomous):**
+- Generate Spring Boot integration tests from test case specs
+- Use MockMvc for REST controller testing
+- Use TestContainers for database integration tests
+- Use @DataJpaTest for repository slice tests
+- Use WebTestClient for WebFlux controller testing
+- Apply @MockBean for service mocking
+- Use @TestPropertySource and profiles for configuration
+- Use @Transactional for test data cleanup
+
+**Cannot do (requires confirmation):**
+- Change production code structure
+- Add dependencies not in pom.xml/build.gradle
+- Override project Spring config without approval
+- Modify database schema
+
+**Will not do (out of scope):**
+- Execute tests (user runs `mvn test`)
+- Write unit tests without Spring (use qa-junit5-writer)
+- Modify CI/CD pipelines
+- Bypass security or access restricted areas
+
+## References
+
+- `references/patterns.md` — MockMvc, TestContainers, DataJpaTest, WebTestClient
+- `references/config.md` — Spring Boot test config, profiles, TestContainers setup
+- `references/best-practices.md` — Spring integration testing best practices
+
+## Quality Checklist
+
+- [ ] Appropriate test slice (@SpringBootTest, @DataJpaTest) for scope
+- [ ] MockMvc/WebTestClient used for controller tests; avoid full HTTP when possible
+- [ ] TestContainers for real DB when repository/DB behavior matters
+- [ ] @Transactional or @DirtiesContext for data isolation where needed
+- [ ] @MockBean only for external dependencies; avoid over-mocking
+- [ ] @TestPropertySource for test-specific config
+- [ ] Tests independent (no shared mutable state)
+- [ ] Traceability to test case IDs where applicable
+- [ ] No hardcoded secrets (use @TestPropertySource or env)
+- [ ] File naming follows `{Feature}IntegrationTest.java` convention
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| Context fails to load | Missing bean, circular dependency | Use @MockBean for problematic deps; check @ComponentScan |
+| MockMvc 404 | Wrong path, context path | Verify @RequestMapping paths; check base path |
+| TestContainers timeout | Image pull slow, resource limits | Use cached image; increase timeout; check Docker |
+| @DataJpaTest fails | Missing JPA config, wrong DB | Add @EntityScan if needed; configure TestContainers |
+| Flaky tests | Shared state, order-dependent | Use @Transactional; ensure test isolation |
+| WebTestClient fails | Wrong binding | Use bindToController or bindToServer; check WebFlux config |

package/skills/qa-spring-test-writer/references/best-practices.md

@@ -0,0 +1,57 @@
+# Spring Integration Testing Best Practices
+
+## Test Slice Selection
+
+| Slice | Use When | Avoid When |
+| ----- | -------- | ---------- |
+| @SpringBootTest | Full integration, multiple layers | Unit testing; slow feedback |
+| @WebMvcTest | Controller-only, mock services | Need real DB, security context |
+| @DataJpaTest | Repository behavior, queries | Need full app, controllers |
+| @JsonTest | JSON serialization | General integration |
+| @RestClientTest | RestTemplate/WebClient | Full HTTP integration |
+
+## MockMvc Best Practices
+
+1. **Prefer MockMvc over real HTTP** — Faster, no network; use RestTemplate/WebClient only when needed
+2. **Use ObjectMapper for JSON** — Avoid hand-crafted JSON strings
+3. **Assert status and body** — Always verify status and key response fields
+4. **Use @WithMockUser** — Test security without full auth flow
+5. **Extract common setup** — @BeforeEach for shared request builders
+
+## TestContainers Best Practices
+
+1. **Use specific image tags** — `postgres:15` not `postgres:latest` for reproducibility
+2. **Reuse containers** — Enable reuse for faster runs when safe
+3. **@DynamicPropertySource** — Prefer over application-test.yml for TestContainers URLs
+4. **One DB per test class** — Avoid shared mutable state; use @Container static
+5. **Consider Testcontainers Cloud** — For CI with limited Docker resources
+
+## Data Isolation
+
+1. **@Transactional** — Rollback after each test; no manual cleanup
+2. **@DirtiesContext** — Use sparingly when context must be refreshed
+3. **@Sql** — Load test data from scripts when needed
+4. **Avoid @Transactional with @DataJpaTest** — Default rollback; explicit only when testing commit behavior
+
+## Performance
+
+1. **Minimize @SpringBootTest** — Use slices (@WebMvcTest, @DataJpaTest) when possible
+2. **Lazy context** — Use @MockBean to avoid loading heavy beans
+3. **Parallel execution** — Surefire forkCount; ensure tests are isolated
+4. **Cache context** — Same configuration = cached context across test classes
+
+## Security Testing
+
+1. **@WithMockUser** — Simulate authenticated user
+2. **@WithAnonymousUser** — Test unauthenticated access
+3. **@WithUserDetails** — Load user from UserDetailsService
+4. **Custom SecurityContext** — For complex scenarios
+
+## Common Pitfalls
+
+| Pitfall | Fix |
+| ------- | --- |
+| Context loads too much | Use @WebMvcTest or @DataJpaTest; @MockBean external deps |
+| Flaky tests | Ensure @Transactional or proper cleanup; no static mutable state |
+| Slow tests | Use slices; reuse TestContainers; avoid full @SpringBootTest |
+| TestContainers fails in CI | Check Docker availability; use ryuk disabled only for debugging |

package/skills/qa-spring-test-writer/references/config.md

@@ -0,0 +1,179 @@
+# Spring Boot Test Configuration
+
+## Maven Dependencies
+
+```xml
+<dependencies>
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter-test</artifactId>
+        <scope>test</scope>
+    </dependency>
+    <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>testcontainers</artifactId>
+        <scope>test</scope>
+    </dependency>
+    <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>postgresql</artifactId>
+        <scope>test</scope>
+    </dependency>
+    <dependency>
+        <groupId>org.testcontainers</groupId>
+        <artifactId>junit-jupiter</artifactId>
+        <scope>test</scope>
+    </dependency>
+</dependencies>
+```
+
+## Gradle Dependencies
+
+```groovy
+testImplementation 'org.springframework.boot:spring-boot-starter-test'
+testImplementation 'org.testcontainers:testcontainers'
+testImplementation 'org.testcontainers:postgresql'
+testImplementation 'org.testcontainers:junit-jupiter'
+```
+
+## @SpringBootTest Options
+
+| Option | Values | Use Case |
+| ------ | ------ | -------- |
+| webEnvironment | NONE, MOCK, RANDOM_PORT, DEFINED_PORT | MOCK for no server; RANDOM_PORT for full integration |
+| classes | Application class | Limit context to specific classes |
+| properties | Key-value pairs | Override properties |
+
+```java
+@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
+class FullIntegrationTest { }
+
+@SpringBootTest(webEnvironment = WebEnvironment.MOCK)
+@AutoConfigureMockMvc
+class MockMvcTest { }
+```
+
+## Test Profiles
+
+### application-test.yml
+```yaml
+spring:
+  datasource:
+    url: jdbc:h2:mem:testdb
+    driver-class-name: org.h2.Driver
+  jpa:
+    hibernate:
+      ddl-auto: create-drop
+```
+
+### Activate in Test
+```java
+@SpringBootTest
+@ActiveProfiles("test")
+class ProfileIntegrationTest { }
+```
+
+## TestContainers Setup
+
+### JUnit 5 Integration
+```java
+@Testcontainers
+class MyTest {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");
+}
+```
+
+### Shared Container (Singleton)
+```java
+@Testcontainers
+class MyTest {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
+        .withReuse(true);  // Reuse across test classes (requires testcontainers.reuse.enable=true)
+}
+```
+
+### Dynamic Properties
+```java
+@DynamicPropertySource
+static void configureProperties(DynamicPropertyRegistry registry) {
+    registry.add("spring.datasource.url", postgres::getJdbcUrl);
+    registry.add("spring.datasource.username", postgres::getUsername);
+    registry.add("spring.datasource.password", postgres::getPassword);
+}
+```
+
+## MockMvc Configuration
+
+### Auto-configure (default with @SpringBootTest webEnvironment=MOCK)
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+class ControllerTest {
+    @Autowired MockMvc mockMvc;
+}
+```
+
+### Custom Configuration
+```java
+@Autowired
+void setMockMvc(MockMvcBuilder builder) {
+    mockMvc = builder
+        .apply(SecurityMockMvcConfigurers.springSecurity())
+        .build();
+}
+```
+
+## WebTestClient Configuration
+
+### With RANDOM_PORT
+```java
+@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
+class WebFluxTest {
+    @Autowired WebTestClient webTestClient;
+}
+```
+
+### With MockMvc (Servlet)
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+class WebTestClientTest {
+    @Autowired MockMvc mockMvc;
+    WebTestClient webTestClient;
+
+    @BeforeEach
+    void setUp() {
+        webTestClient = WebTestClient.bindTo(
+            MockMvcWebClientBuilder.mockMvcSetup(mockMvc).build()
+        ).build();
+    }
+}
+```
+
+## Surefire Configuration (Maven)
+
+```xml
+<plugin>
+    <groupId>org.apache.maven.plugins</groupId>
+    <artifactId>maven-surefire-plugin</artifactId>
+    <configuration>
+        <includes>
+            <include>**/*Test.java</include>
+            <include>**/*IntegrationTest.java</include>
+        </includes>
+        <excludes>
+            <exclude>**/Abstract*.java</exclude>
+        </excludes>
+    </configuration>
+</plugin>
+```
+
+## Testcontainers Properties
+
+### ~/.testcontainers.properties (optional)
+```
+docker.client.strategy=org.testcontainers.dockerclient.UnixSocketClientProviderStrategy
+testcontainers.reuse.enable=true
+```

package/skills/qa-spring-test-writer/references/patterns.md

@@ -0,0 +1,235 @@
+# Spring Test Patterns
+
+## MockMvc Patterns
+
+### Basic GET
+```java
+mockMvc.perform(get("/api/users"))
+    .andExpect(status().isOk())
+    .andExpect(content().contentType(MediaType.APPLICATION_JSON))
+    .andExpect(jsonPath("$").isArray());
+```
+
+### POST with JSON Body
+```java
+String body = objectMapper.writeValueAsString(new UserRequest("John", "john@example.com"));
+mockMvc.perform(post("/api/users")
+        .contentType(MediaType.APPLICATION_JSON)
+        .content(body))
+    .andExpect(status().isCreated())
+    .andExpect(jsonPath("$.id").exists())
+    .andExpect(jsonPath("$.name").value("John"));
+```
+
+### PUT / PATCH / DELETE
+```java
+mockMvc.perform(put("/api/users/1").contentType(JSON).content(body))
+    .andExpect(status().isOk());
+
+mockMvc.perform(delete("/api/users/1"))
+    .andExpect(status().isNoContent());
+```
+
+### Headers and Authentication
+```java
+mockMvc.perform(get("/api/users")
+        .header("Authorization", "Bearer " + token)
+        .header("X-Request-ID", "req-123"))
+    .andExpect(status().isOk());
+```
+
+### With Security (MockMvc + Spring Security)
+```java
+@WithMockUser(roles = "ADMIN")
+@Test
+void getUsers_asAdmin_returnsOk() throws Exception {
+    mockMvc.perform(get("/api/users")).andExpect(status().isOk());
+}
+
+@WithMockUser(username = "user", roles = "USER")
+@Test
+void getUsers_asUser_returnsForbidden() throws Exception {
+    mockMvc.perform(get("/api/admin/users")).andExpect(status().isForbidden());
+}
+```
+
+### JsonPath Assertions
+```java
+.andExpect(jsonPath("$.id").value(1))
+.andExpect(jsonPath("$.name").value("John"))
+.andExpect(jsonPath("$.items[0].name").value("Item1"))
+.andExpect(jsonPath("$.items", hasSize(2)))
+.andExpect(jsonPath("$.active").value(true))
+```
+
+## TestContainers Patterns
+
+### PostgreSQL
+```java
+@Container
+static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15")
+    .withDatabaseName("testdb")
+    .withUsername("test")
+    .withPassword("test");
+
+@DynamicPropertySource
+static void configureProperties(DynamicPropertyRegistry registry) {
+    registry.add("spring.datasource.url", postgres::getJdbcUrl);
+    registry.add("spring.datasource.username", postgres::getUsername);
+    registry.add("spring.datasource.password", postgres::getPassword);
+}
+```
+
+### MySQL
+```java
+@Container
+static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8")
+    .withDatabaseName("testdb")
+    .withUsername("test")
+    .withPassword("test");
+```
+
+### Redis
+```java
+@Container
+static GenericContainer<?> redis = new GenericContainer<>("redis:7-alpine")
+    .withExposedPorts(6379);
+
+@DynamicPropertySource
+static void configureRedis(DynamicPropertyRegistry registry) {
+    registry.add("spring.data.redis.host", redis::getHost);
+    registry.add("spring.data.redis.port", () -> redis.getMappedPort(6379).toString());
+}
+```
+
+## @DataJpaTest Patterns
+
+### Repository CRUD
+```java
+@DataJpaTest
+class UserRepositoryTest {
+    @Autowired UserRepository repository;
+
+    @Test
+    void saveAndFind() {
+        User user = new User("John", "john@example.com");
+        User saved = repository.save(user);
+        assertThat(repository.findById(saved.getId())).isPresent();
+        assertThat(repository.findAll()).hasSize(1);
+    }
+
+    @Test
+    void findByEmail() {
+        repository.save(new User("John", "john@example.com"));
+        assertThat(repository.findByEmail("john@example.com")).isPresent();
+    }
+}
+```
+
+### With TestContainers
+```java
+@DataJpaTest
+@Testcontainers
+class UserRepositoryTest {
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:15");
+
+    @DynamicPropertySource
+    static void configure(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+    }
+    // ...
+}
+```
+
+## WebTestClient Patterns
+
+### Bind to Controller (no full context)
+```java
+@ExtendWith(MockitoExtension.class)
+class UserControllerTest {
+    @Mock UserService userService;
+    WebTestClient webTestClient;
+
+    @BeforeEach
+    void setUp() {
+        webTestClient = WebTestClient.bindToController(new UserController(userService)).build();
+    }
+
+    @Test
+    void getUsers_returnsOk() {
+        when(userService.findAll()).thenReturn(List.of(new User(1L, "John")));
+        webTestClient.get().uri("/api/users")
+            .exchange()
+            .expectStatus().isOk()
+            .expectBodyList(User.class).hasSize(1);
+    }
+}
+```
+
+### Full Application (integration)
+```java
+@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
+class UserControllerIntegrationTest {
+    @Autowired WebTestClient webTestClient;
+
+    @Test
+    void getUsers_returnsOk() {
+        webTestClient.get().uri("/api/users")
+            .exchange()
+            .expectStatus().isOk()
+            .expectBody()
+            .jsonPath("$").isArray();
+    }
+}
+```
+
+## @MockBean Patterns
+
+### Mock Service in Integration Test
+```java
+@SpringBootTest
+@AutoConfigureMockMvc
+class OrderControllerIntegrationTest {
+    @Autowired MockMvc mockMvc;
+    @MockBean PaymentService paymentService;
+
+    @Test
+    void createOrder_mocksPayment() throws Exception {
+        when(paymentService.process(any())).thenReturn(new PaymentResult("ok", "tx-123"));
+        mockMvc.perform(post("/api/orders").contentType(JSON).content(orderJson))
+            .andExpect(status().isCreated());
+        verify(paymentService).process(any());
+    }
+}
+```
+
+## @Transactional and Data Cleanup
+
+```java
+@SpringBootTest
+@Transactional  // Rollback after each test
+class OrderServiceIntegrationTest {
+    @Autowired OrderRepository orderRepository;
+
+    @Test
+    void createOrder_persists() {
+        orderRepository.save(new Order(...));
+        assertThat(orderRepository.count()).isEqualTo(1);
+        // Rolled back automatically after test
+    }
+}
+```
+
+## @TestPropertySource
+
+```java
+@SpringBootTest
+@TestPropertySource(properties = {
+    "app.feature.enabled=true",
+    "spring.jpa.hibernate.ddl-auto=create-drop"
+})
+class FeatureIntegrationTest { }
+```