aigroup-workflow 2.1.2 → 2.2.0

package/skills/java/java-architect/references/testing-patterns.md

@@ -0,0 +1,500 @@
+# Testing Patterns
+
+## Unit Testing with JUnit 5
+
+```java
+package com.example.application.service;
+
+import com.example.application.dto.UserRequest;
+import com.example.application.dto.UserResponse;
+import com.example.application.mapper.UserMapper;
+import com.example.domain.model.User;
+import com.example.domain.repository.UserRepository;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.ValueSource;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.util.Optional;
+
+import static org.assertj.core.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+@DisplayName("User Service Tests")
+class UserServiceTest {
+
+    @Mock
+    private UserRepository userRepository;
+
+    @Mock
+    private UserMapper userMapper;
+
+    @InjectMocks
+    private UserService userService;
+
+    private User testUser;
+    private UserRequest userRequest;
+    private UserResponse userResponse;
+
+    @BeforeEach
+    void setUp() {
+        testUser = User.builder()
+            .id(1L)
+            .email("test@example.com")
+            .username("testuser")
+            .active(true)
+            .build();
+
+        userRequest = new UserRequest("test@example.com", "testuser");
+        userResponse = new UserResponse(1L, "test@example.com", "testuser");
+    }
+
+    @Test
+    @DisplayName("Should find user by ID successfully")
+    void shouldFindUserById() {
+        // Given
+        when(userRepository.findById(1L)).thenReturn(Optional.of(testUser));
+        when(userMapper.toResponse(testUser)).thenReturn(userResponse);
+
+        // When
+        UserResponse result = userService.findById(1L);
+
+        // Then
+        assertThat(result).isNotNull();
+        assertThat(result.email()).isEqualTo("test@example.com");
+        verify(userRepository).findById(1L);
+        verify(userMapper).toResponse(testUser);
+    }
+
+    @Test
+    @DisplayName("Should throw exception when user not found")
+    void shouldThrowWhenUserNotFound() {
+        // Given
+        when(userRepository.findById(anyLong())).thenReturn(Optional.empty());
+
+        // When / Then
+        assertThatThrownBy(() -> userService.findById(999L))
+            .isInstanceOf(EntityNotFoundException.class)
+            .hasMessageContaining("User not found");
+
+        verify(userRepository).findById(999L);
+        verifyNoInteractions(userMapper);
+    }
+
+    @Test
+    @DisplayName("Should create user successfully")
+    void shouldCreateUser() {
+        // Given
+        when(userMapper.toEntity(userRequest)).thenReturn(testUser);
+        when(userRepository.save(any(User.class))).thenReturn(testUser);
+        when(userMapper.toResponse(testUser)).thenReturn(userResponse);
+
+        // When
+        UserResponse result = userService.create(userRequest);
+
+        // Then
+        assertThat(result).isNotNull();
+        assertThat(result.id()).isEqualTo(1L);
+        verify(userRepository).save(any(User.class));
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {"admin", "user", "moderator"})
+    @DisplayName("Should validate different user roles")
+    void shouldValidateUserRoles(String role) {
+        // Test with multiple roles
+        assertThat(role).isNotBlank();
+    }
+}
+```
+
+## Integration Testing with TestContainers
+
+```java
+package com.example.integration;
+
+import com.example.application.dto.UserRequest;
+import com.example.application.dto.UserResponse;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.web.client.TestRestTemplate;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@Testcontainers
+class UserIntegrationTest {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine")
+        .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);
+    }
+
+    @Autowired
+    private TestRestTemplate restTemplate;
+
+    @BeforeEach
+    void setUp() {
+        // Clean up database before each test
+    }
+
+    @Test
+    void shouldCreateAndRetrieveUser() {
+        // Create user
+        UserRequest request = new UserRequest("test@example.com", "testuser");
+        ResponseEntity<UserResponse> createResponse = restTemplate.postForEntity(
+            "/api/users",
+            request,
+            UserResponse.class
+        );
+
+        assertThat(createResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+        assertThat(createResponse.getBody()).isNotNull();
+        Long userId = createResponse.getBody().id();
+
+        // Retrieve user
+        ResponseEntity<UserResponse> getResponse = restTemplate.getForEntity(
+            "/api/users/" + userId,
+            UserResponse.class
+        );
+
+        assertThat(getResponse.getStatusCode()).isEqualTo(HttpStatus.OK);
+        assertThat(getResponse.getBody().email()).isEqualTo("test@example.com");
+    }
+}
+```
+
+## Repository Testing
+
+```java
+package com.example.domain.repository;
+
+import com.example.domain.model.User;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.jdbc.AutoConfigureTestDatabase;
+import org.springframework.boot.test.autoconfigure.orm.jpa.DataJpaTest;
+import org.springframework.boot.test.autoconfigure.orm.jpa.TestEntityManager;
+import org.testcontainers.containers.PostgreSQLContainer;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+
+import java.util.Optional;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+@DataJpaTest
+@Testcontainers
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+class UserRepositoryTest {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
+
+    @Autowired
+    private TestEntityManager entityManager;
+
+    @Autowired
+    private UserRepository userRepository;
+
+    @Test
+    void shouldFindUserByEmail() {
+        // Given
+        User user = User.builder()
+            .email("test@example.com")
+            .username("testuser")
+            .active(true)
+            .build();
+        entityManager.persistAndFlush(user);
+
+        // When
+        Optional<User> found = userRepository.findByEmail("test@example.com");
+
+        // Then
+        assertThat(found).isPresent();
+        assertThat(found.get().getEmail()).isEqualTo("test@example.com");
+    }
+
+    @Test
+    void shouldCountActiveUsers() {
+        // Given
+        User activeUser = User.builder()
+            .email("active@example.com")
+            .username("active")
+            .active(true)
+            .build();
+        User inactiveUser = User.builder()
+            .email("inactive@example.com")
+            .username("inactive")
+            .active(false)
+            .build();
+        entityManager.persist(activeUser);
+        entityManager.persist(inactiveUser);
+        entityManager.flush();
+
+        // When
+        long count = userRepository.countByActiveTrue();
+
+        // Then
+        assertThat(count).isEqualTo(1);
+    }
+}
+```
+
+## REST Controller Testing
+
+```java
+package com.example.presentation.rest;
+
+import com.example.application.dto.UserRequest;
+import com.example.application.dto.UserResponse;
+import com.example.application.service.UserService;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
+import org.springframework.boot.test.mock.mockito.MockBean;
+import org.springframework.http.MediaType;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.test.web.servlet.MockMvc;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.when;
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.csrf;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Autowired
+    private ObjectMapper objectMapper;
+
+    @MockBean
+    private UserService userService;
+
+    @Test
+    @WithMockUser
+    void shouldGetUserById() throws Exception {
+        // Given
+        UserResponse response = new UserResponse(1L, "test@example.com", "testuser");
+        when(userService.findById(1L)).thenReturn(response);
+
+        // When / Then
+        mockMvc.perform(get("/api/users/1"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.id").value(1))
+            .andExpect(jsonPath("$.email").value("test@example.com"));
+    }
+
+    @Test
+    @WithMockUser
+    void shouldCreateUser() throws Exception {
+        // Given
+        UserRequest request = new UserRequest("test@example.com", "testuser");
+        UserResponse response = new UserResponse(1L, "test@example.com", "testuser");
+        when(userService.create(any(UserRequest.class))).thenReturn(response);
+
+        // When / Then
+        mockMvc.perform(post("/api/users")
+                .with(csrf())
+                .contentType(MediaType.APPLICATION_JSON)
+                .content(objectMapper.writeValueAsString(request)))
+            .andExpect(status().isCreated())
+            .andExpect(jsonPath("$.id").value(1));
+    }
+
+    @Test
+    void shouldReturn401WhenNotAuthenticated() throws Exception {
+        mockMvc.perform(get("/api/users/1"))
+            .andExpect(status().isUnauthorized());
+    }
+}
+```
+
+## Test Configuration
+
+```java
+package com.example.config;
+
+import org.springframework.boot.test.context.TestConfiguration;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Primary;
+import org.springframework.security.crypto.password.NoOpPasswordEncoder;
+import org.springframework.security.crypto.password.PasswordEncoder;
+
+@TestConfiguration
+public class TestSecurityConfig {
+
+    @Bean
+    @Primary
+    public PasswordEncoder passwordEncoder() {
+        return NoOpPasswordEncoder.getInstance();
+    }
+}
+```
+
+## Test Data Builders
+
+```java
+package com.example.test.builders;
+
+import com.example.domain.model.User;
+
+public class UserTestBuilder {
+
+    private Long id = 1L;
+    private String email = "test@example.com";
+    private String username = "testuser";
+    private Boolean active = true;
+
+    public static UserTestBuilder aUser() {
+        return new UserTestBuilder();
+    }
+
+    public UserTestBuilder withId(Long id) {
+        this.id = id;
+        return this;
+    }
+
+    public UserTestBuilder withEmail(String email) {
+        this.email = email;
+        return this;
+    }
+
+    public UserTestBuilder inactive() {
+        this.active = false;
+        return this;
+    }
+
+    public User build() {
+        return User.builder()
+            .id(id)
+            .email(email)
+            .username(username)
+            .active(active)
+            .build();
+    }
+}
+
+// Usage
+User user = aUser()
+    .withEmail("custom@example.com")
+    .inactive()
+    .build();
+```
+
+## Performance Testing with JMH
+
+```java
+package com.example.benchmark;
+
+import org.openjdk.jmh.annotations.*;
+import org.openjdk.jmh.runner.Runner;
+import org.openjdk.jmh.runner.options.Options;
+import org.openjdk.jmh.runner.options.OptionsBuilder;
+
+import java.util.concurrent.TimeUnit;
+
+@BenchmarkMode(Mode.AverageTime)
+@OutputTimeUnit(TimeUnit.MICROSECONDS)
+@State(Scope.Benchmark)
+@Fork(value = 2, warmups = 1)
+@Warmup(iterations = 3)
+@Measurement(iterations = 5)
+public class UserServiceBenchmark {
+
+    private UserService userService;
+
+    @Setup
+    public void setup() {
+        // Initialize test data
+        userService = new UserService();
+    }
+
+    @Benchmark
+    public void benchmarkFindUser() {
+        userService.findById(1L);
+    }
+
+    public static void main(String[] args) throws Exception {
+        Options opt = new OptionsBuilder()
+            .include(UserServiceBenchmark.class.getSimpleName())
+            .build();
+        new Runner(opt).run();
+    }
+}
+```
+
+## Test Containers Shared Instance
+
+```java
+package com.example.test;
+
+import org.springframework.test.context.DynamicPropertyRegistry;
+import org.springframework.test.context.DynamicPropertySource;
+import org.testcontainers.containers.PostgreSQLContainer;
+
+public abstract class AbstractIntegrationTest {
+
+    static final PostgreSQLContainer<?> postgres;
+
+    static {
+        postgres = new PostgreSQLContainer<>("postgres:16-alpine")
+            .withReuse(true);
+        postgres.start();
+    }
+
+    @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);
+    }
+}
+```
+
+## Quick Reference
+
+| Annotation | Purpose |
+|-----------|---------|
+| `@Test` | Mark test method |
+| `@BeforeEach` | Run before each test |
+| `@AfterEach` | Run after each test |
+| `@DisplayName` | Readable test name |
+| `@ParameterizedTest` | Data-driven tests |
+| `@ExtendWith` | Register extensions |
+| `@SpringBootTest` | Full application context |
+| `@WebMvcTest` | Test MVC layer only |
+| `@DataJpaTest` | Test repository layer |
+| `@MockBean` | Mock Spring bean |
+| `@WithMockUser` | Mock authenticated user |
+| `assertThat()` | AssertJ fluent assertions |
+| `verify()` | Mockito verification |

package/skills/java/kotlin-specialist/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: kotlin-specialist
+description: Provides idiomatic Kotlin implementation patterns including coroutine concurrency, Flow stream handling, multiplatform architecture, Compose UI construction, Ktor server setup, and type-safe DSL design. Use when building Kotlin applications requiring coroutines, multiplatform development, or Android with Compose. Invoke for Flow API, KMP projects, Ktor servers, DSL design, sealed classes, suspend function, Android Kotlin, Kotlin Multiplatform.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.1.0"
+  domain: language
+  triggers: Kotlin, coroutines, Kotlin Multiplatform, KMP, Jetpack Compose, Ktor, Flow, Android Kotlin, suspend function
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: test-master
+---
+
+# Kotlin Specialist
+
+Senior Kotlin developer with deep expertise in coroutines, Kotlin Multiplatform (KMP), and modern Kotlin 1.9+ patterns.
+
+## Core Workflow
+
+1. **Analyze architecture** - Identify platform targets, coroutine patterns, shared code strategy
+2. **Design models** - Create sealed classes, data classes, type hierarchies
+3. **Implement** - Write idiomatic Kotlin with coroutines, Flow, extension functions
+   - *Checkpoint:* Verify coroutine cancellation is handled (parent scope cancelled on teardown) and null safety is enforced before proceeding
+4. **Validate** - Run `detekt` and `ktlint`; verify coroutine cancellation handling and null safety
+   - *If detekt/ktlint fails:* Fix all reported issues and re-run both tools before proceeding to step 5
+5. **Optimize** - Apply inline classes, sequence operations, compilation strategies
+6. **Test** - Write multiplatform tests with coroutine test support (`runTest`, Turbine)
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Coroutines & Flow | `references/coroutines-flow.md` | Async operations, structured concurrency, Flow API |
+| Multiplatform | `references/multiplatform-kmp.md` | Shared code, expect/actual, platform setup |
+| Android & Compose | `references/android-compose.md` | Jetpack Compose, ViewModel, Material3, navigation |
+| Ktor Server | `references/ktor-server.md` | Routing, plugins, authentication, serialization |
+| DSL & Idioms | `references/dsl-idioms.md` | Type-safe builders, scope functions, delegates |
+
+## Key Patterns
+
+### Sealed Classes for State Modeling
+
+```kotlin
+sealed class UiState<out T> {
+    data object Loading : UiState<Nothing>()
+    data class Success<T>(val data: T) : UiState<T>()
+    data class Error(val message: String, val cause: Throwable? = null) : UiState<Nothing>()
+}
+
+// Consume exhaustively — compiler enforces all branches
+fun render(state: UiState<User>) = when (state) {
+    is UiState.Loading  -> showSpinner()
+    is UiState.Success  -> showUser(state.data)
+    is UiState.Error    -> showError(state.message)
+}
+```
+
+### Coroutines & Flow
+
+```kotlin
+// Use structured concurrency — never GlobalScope
+class UserRepository(private val api: UserApi, private val scope: CoroutineScope) {
+
+    fun userUpdates(id: String): Flow<UiState<User>> = flow {
+        emit(UiState.Loading)
+        try {
+            emit(UiState.Success(api.fetchUser(id)))
+        } catch (e: IOException) {
+            emit(UiState.Error("Network error", e))
+        }
+    }.flowOn(Dispatchers.IO)
+
+    private val _user = MutableStateFlow<UiState<User>>(UiState.Loading)
+    val user: StateFlow<UiState<User>> = _user.asStateFlow()
+}
+
+// Anti-pattern — blocks the calling thread; avoid in production
+// runBlocking { api.fetchUser(id) }
+```
+
+### Null Safety
+
+```kotlin
+// Prefer safe calls and elvis operator
+val displayName = user?.profile?.name ?: "Anonymous"
+
+// Use let to scope nullable operations
+user?.email?.let { email -> sendNotification(email) }
+
+// !! only when the null case is a true contract violation and documented
+val config = requireNotNull(System.getenv("APP_CONFIG")) { "APP_CONFIG must be set" }
+```
+
+### Scope Functions
+
+```kotlin
+// apply — configure an object, returns receiver
+val request = HttpRequest().apply {
+    url = "https://api.example.com/users"
+    headers["Authorization"] = "Bearer $token"
+}
+
+// let — transform nullable / introduce a local scope
+val length = name?.let { it.trim().length } ?: 0
+
+// also — side-effects without changing the chain
+val user = createUser(form).also { logger.info("Created user ${it.id}") }
+```
+
+## Constraints
+
+### MUST DO
+- Use null safety (`?`, `?.`, `?:`, `!!` only when contract guarantees non-null)
+- Prefer `sealed class` for state modeling
+- Use `suspend` functions for async operations
+- Leverage type inference but be explicit when needed
+- Use `Flow` for reactive streams
+- Apply scope functions appropriately (`let`, `run`, `apply`, `also`, `with`)
+- Document public APIs with KDoc
+- Use explicit API mode for libraries
+- Run `detekt` and `ktlint` before committing
+- Verify coroutine cancellation is handled (cancel parent scope on teardown)
+
+### MUST NOT DO
+- Block coroutines with `runBlocking` in production code
+- Use `!!` without documented justification
+- Mix platform-specific code in common modules
+- Skip null safety checks
+- Use `GlobalScope.launch` (use structured concurrency)
+- Ignore coroutine cancellation
+- Create memory leaks with coroutine scopes
+
+## Output Templates
+
+When implementing Kotlin features, provide:
+1. Data models (sealed classes, data classes)
+2. Implementation file (extension functions, suspend functions)
+3. Test file with coroutine test support
+4. Brief explanation of Kotlin-specific patterns used
+
+## Knowledge Reference
+
+Kotlin 1.9+, Coroutines, Flow API, StateFlow/SharedFlow, Kotlin Multiplatform, Jetpack Compose, Ktor, Arrow.kt, kotlinx.serialization, Detekt, ktlint, Gradle Kotlin DSL, JUnit 5, MockK, Turbine