@ngxtm/devkit 3.4.0 → 3.5.0

package/rules/java/testing-junit-mockito/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: Testing with JUnit & Mockito
+description: JUnit 5, Mockito, Spring test slices, integration testing, and test organization.
+metadata:
+  labels: [java, testing, junit, mockito]
+  triggers:
+    files: ['**/*Test.java', '**/*IT.java', '**/*Tests.java']
+    keywords: [JUnit, Jupiter, Mockito, '@Test', '@ExtendWith', '@MockBean', '@SpringBootTest', '@DataJpaTest', '@WebMvcTest']
+---
+
+# Testing Standards
+
+## JUnit 5 Basics
+
+```java
+class UserServiceTest {
+
+    @Test
+    @DisplayName("should create user with valid data")
+    void shouldCreateUser() {
+        // Given
+        var request = new CreateUserRequest("John", "john@example.com");
+
+        // When
+        var user = userService.create(request);
+
+        // Then
+        assertThat(user.getName()).isEqualTo("John");
+        assertThat(user.getEmail()).isEqualTo("john@example.com");
+    }
+
+    @ParameterizedTest
+    @ValueSource(strings = {"", " ", "invalid"})
+    void shouldRejectInvalidEmail(String email) {
+        var request = new CreateUserRequest("John", email);
+
+        assertThatThrownBy(() -> userService.create(request))
+            .isInstanceOf(ValidationException.class);
+    }
+
+    @BeforeEach
+    void setUp() {
+        // Setup before each test
+    }
+
+    @AfterEach
+    void tearDown() {
+        // Cleanup after each test
+    }
+}
+```
+
+## Mockito
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+
+    @Mock
+    OrderRepository orderRepository;
+
+    @Mock
+    InventoryService inventoryService;
+
+    @InjectMocks
+    OrderService orderService;
+
+    @Test
+    void shouldCreateOrder() {
+        // Given
+        var request = new CreateOrderRequest("product-1", 2);
+        when(inventoryService.checkStock("product-1")).thenReturn(true);
+        when(orderRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
+
+        // When
+        var order = orderService.create(request);
+
+        // Then
+        assertThat(order).isNotNull();
+        verify(inventoryService).checkStock("product-1");
+        verify(orderRepository).save(any(Order.class));
+    }
+}
+```
+
+## Spring Test Slices
+
+```java
+// Full context
+@SpringBootTest
+class ApplicationTests {}
+
+// Web layer only
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+    @Autowired MockMvc mockMvc;
+    @MockBean UserService userService;
+
+    @Test
+    void shouldReturnUser() throws Exception {
+        when(userService.findById(1L)).thenReturn(Optional.of(new User(1L, "John")));
+
+        mockMvc.perform(get("/api/users/1"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.name").value("John"));
+    }
+}
+
+// JPA layer only
+@DataJpaTest
+class UserRepositoryTest {
+    @Autowired UserRepository repository;
+    @Autowired TestEntityManager entityManager;
+
+    @Test
+    void shouldFindByEmail() {
+        entityManager.persist(new User("john@example.com"));
+        var user = repository.findByEmail("john@example.com");
+        assertThat(user).isPresent();
+    }
+}
+```
+
+## Best Practices
+
+1. **Given-When-Then** structure for readability
+2. **One assertion concept per test**
+3. **Use test slices** to minimize context
+4. **AssertJ** for fluent assertions
+5. **Parameterized tests** for multiple inputs
+
+## References
+
+- [Test Slices](references/test-slices.md) - Available slices, customization
+- [Mockito Patterns](references/mockito-patterns.md) - Stubbing, verification, argument captors

package/rules/java/testing-junit-mockito/references/REFERENCE.md

@@ -0,0 +1,15 @@
+# JUnit and Mockito Testing References
+
+## References
+
+- [**JUnit 5 Patterns**](junit5-patterns.md) - Test structure, parameterized tests, assertions
+- [**Mockito Patterns**](mockito-patterns.md) - Mocking, stubbing, verification, spying
+- [**Spring Boot Testing**](spring-boot-testing.md) - Slice tests, integration, Testcontainers
+
+## Quick Checks
+
+- [ ] Use @ExtendWith(MockitoExtension.class)
+- [ ] @DisplayName for readable test names
+- [ ] Parameterized tests for multiple inputs
+- [ ] Slice tests (@WebMvcTest, @DataJpaTest) for focused testing
+- [ ] Testcontainers for real database tests

package/rules/java/testing-junit-mockito/references/junit5-patterns.md

@@ -0,0 +1,159 @@
+# JUnit 5 Testing Patterns
+
+## Basic Test Structure
+
+```java
+import org.junit.jupiter.api.*;
+import static org.junit.jupiter.api.Assertions.*;
+
+class UserServiceTest {
+
+    private UserService userService;
+
+    @BeforeEach
+    void setUp() {
+        userService = new UserService();
+    }
+
+    @Test
+    @DisplayName("Should find user by ID")
+    void shouldFindUserById() {
+        User user = userService.findById(1L);
+        
+        assertNotNull(user);
+        assertEquals("John", user.getName());
+    }
+
+    @Test
+    void shouldThrowWhenUserNotFound() {
+        assertThrows(UserNotFoundException.class, () -> {
+            userService.findById(999L);
+        });
+    }
+
+    @AfterEach
+    void tearDown() {
+        // cleanup
+    }
+}
+```
+
+## Parameterized Tests
+
+```java
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.*;
+
+class ValidationTest {
+
+    @ParameterizedTest
+    @ValueSource(strings = {"a@b.com", "test@example.org"})
+    void shouldAcceptValidEmails(String email) {
+        assertTrue(EmailValidator.isValid(email));
+    }
+
+    @ParameterizedTest
+    @NullAndEmptySource
+    @ValueSource(strings = {"invalid", "@no-local.com"})
+    void shouldRejectInvalidEmails(String email) {
+        assertFalse(EmailValidator.isValid(email));
+    }
+
+    @ParameterizedTest
+    @CsvSource({
+        "1, 1, 2",
+        "2, 3, 5",
+        "10, 20, 30"
+    })
+    void shouldAddNumbers(int a, int b, int expected) {
+        assertEquals(expected, Calculator.add(a, b));
+    }
+
+    @ParameterizedTest
+    @MethodSource("userProvider")
+    void shouldValidateUser(User user, boolean expected) {
+        assertEquals(expected, UserValidator.isValid(user));
+    }
+
+    static Stream<Arguments> userProvider() {
+        return Stream.of(
+            Arguments.of(new User("John", 25), true),
+            Arguments.of(new User("", 25), false),
+            Arguments.of(new User("John", -1), false)
+        );
+    }
+}
+```
+
+## Nested Tests
+
+```java
+@DisplayName("OrderService")
+class OrderServiceTest {
+
+    @Nested
+    @DisplayName("when creating order")
+    class WhenCreatingOrder {
+
+        @Test
+        void shouldCreateWithValidItems() { }
+
+        @Test
+        void shouldRejectEmptyCart() { }
+    }
+
+    @Nested
+    @DisplayName("when canceling order")
+    class WhenCancelingOrder {
+
+        @Test
+        void shouldCancelPendingOrder() { }
+
+        @Test
+        void shouldNotCancelShippedOrder() { }
+    }
+}
+```
+
+## Assertions
+
+```java
+// Multiple assertions
+assertAll("user",
+    () -> assertEquals("John", user.getName()),
+    () -> assertEquals(25, user.getAge()),
+    () -> assertTrue(user.isActive())
+);
+
+// Timeout
+assertTimeout(Duration.ofSeconds(2), () -> {
+    longRunningOperation();
+});
+
+// Exception details
+var exception = assertThrows(ValidationException.class, () -> {
+    service.validate(invalidData);
+});
+assertEquals("Invalid input", exception.getMessage());
+```
+
+## Test Lifecycle
+
+```java
+@TestInstance(TestInstance.Lifecycle.PER_CLASS)
+class ExpensiveResourceTest {
+
+    private Database db;
+
+    @BeforeAll
+    void initDatabase() {
+        db = new Database();
+        db.connect();
+    }
+
+    @AfterAll
+    void closeDatabase() {
+        db.disconnect();
+    }
+}
+```

package/rules/java/testing-junit-mockito/references/mockito-patterns.md

@@ -0,0 +1,148 @@
+# Mockito Testing Patterns
+
+## Basic Mocking
+
+```java
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+
+    @Mock
+    private UserRepository userRepository;
+
+    @Mock
+    private OrderRepository orderRepository;
+
+    @InjectMocks
+    private OrderService orderService;
+
+    @Test
+    void shouldCreateOrder() {
+        // Given
+        User user = new User(1L, "John");
+        when(userRepository.findById(1L)).thenReturn(Optional.of(user));
+        when(orderRepository.save(any(Order.class))).thenAnswer(inv -> {
+            Order order = inv.getArgument(0);
+            order.setId(100L);
+            return order;
+        });
+
+        // When
+        Order order = orderService.createOrder(1L, List.of(item1, item2));
+
+        // Then
+        assertNotNull(order);
+        assertEquals(100L, order.getId());
+        verify(orderRepository).save(any(Order.class));
+    }
+}
+```
+
+## Stubbing
+
+```java
+// Return value
+when(mock.method()).thenReturn(value);
+
+// Throw exception
+when(mock.method()).thenThrow(new RuntimeException());
+
+// Multiple calls
+when(mock.method())
+    .thenReturn(first)
+    .thenReturn(second)
+    .thenThrow(new RuntimeException());
+
+// Argument matchers
+when(userRepo.findByEmail(anyString())).thenReturn(user);
+when(userRepo.findByAge(argThat(age -> age > 18))).thenReturn(adults);
+
+// Void methods
+doNothing().when(mock).voidMethod();
+doThrow(new RuntimeException()).when(mock).voidMethod();
+```
+
+## Verification
+
+```java
+// Called once (default)
+verify(mock).method();
+
+// Called specific times
+verify(mock, times(3)).method();
+verify(mock, never()).method();
+verify(mock, atLeast(2)).method();
+verify(mock, atMost(5)).method();
+
+// With argument capture
+ArgumentCaptor<Order> captor = ArgumentCaptor.forClass(Order.class);
+verify(orderRepo).save(captor.capture());
+Order saved = captor.getValue();
+assertEquals(expectedTotal, saved.getTotal());
+
+// Verification order
+InOrder inOrder = inOrder(first, second);
+inOrder.verify(first).method();
+inOrder.verify(second).method();
+
+// No more interactions
+verifyNoMoreInteractions(mock);
+```
+
+## Spying
+
+```java
+// Partial mock - real object with stubbed methods
+@Spy
+private List<String> spiedList = new ArrayList<>();
+
+@Test
+void shouldSpyRealObject() {
+    spiedList.add("one");
+    spiedList.add("two");
+
+    verify(spiedList).add("one");
+    assertEquals(2, spiedList.size()); // Real behavior
+
+    // Override specific method
+    doReturn(100).when(spiedList).size();
+    assertEquals(100, spiedList.size());
+}
+```
+
+## BDD Style
+
+```java
+import static org.mockito.BDDMockito.*;
+
+@Test
+void shouldProcessPayment() {
+    // Given
+    given(paymentGateway.process(any())).willReturn(PaymentResult.SUCCESS);
+
+    // When
+    boolean result = paymentService.pay(order);
+
+    // Then
+    then(paymentGateway).should().process(any());
+    assertThat(result).isTrue();
+}
+```
+
+## Static Mocking
+
+```java
+try (MockedStatic<Utils> utilities = mockStatic(Utils.class)) {
+    utilities.when(() -> Utils.generateId()).thenReturn("mocked-id");
+    
+    String id = Utils.generateId();
+    
+    assertEquals("mocked-id", id);
+}
+```

package/rules/java/testing-junit-mockito/references/spring-boot-testing.md

@@ -0,0 +1,152 @@
+# Spring Boot Testing
+
+## Slice Tests
+
+```java
+// Web layer only
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @MockitoBean
+    private UserService userService;
+
+    @Test
+    void shouldGetUser() throws Exception {
+        when(userService.findById(1L)).thenReturn(new User(1L, "John"));
+
+        mockMvc.perform(get("/users/1"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.name").value("John"));
+    }
+
+    @Test
+    void shouldCreateUser() throws Exception {
+        mockMvc.perform(post("/users")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("""
+                    {"name": "John", "email": "john@example.com"}
+                    """))
+            .andExpect(status().isCreated());
+    }
+}
+
+// JPA layer only
+@DataJpaTest
+class UserRepositoryTest {
+
+    @Autowired
+    private TestEntityManager entityManager;
+
+    @Autowired
+    private UserRepository userRepository;
+
+    @Test
+    void shouldFindByEmail() {
+        entityManager.persist(new User("John", "john@example.com"));
+        
+        Optional<User> found = userRepository.findByEmail("john@example.com");
+        
+        assertThat(found).isPresent();
+        assertThat(found.get().getName()).isEqualTo("John");
+    }
+}
+```
+
+## Integration Tests
+
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+class OrderIntegrationTest {
+
+    @Autowired
+    private TestRestTemplate restTemplate;
+
+    @Test
+    void shouldCreateAndRetrieveOrder() {
+        // Create
+        OrderRequest request = new OrderRequest(List.of(item1, item2));
+        ResponseEntity<Order> createResponse = restTemplate
+            .postForEntity("/orders", request, Order.class);
+        
+        assertThat(createResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED);
+        Long orderId = createResponse.getBody().getId();
+
+        // Retrieve
+        ResponseEntity<Order> getResponse = restTemplate
+            .getForEntity("/orders/" + orderId, Order.class);
+        
+        assertThat(getResponse.getBody().getItems()).hasSize(2);
+    }
+}
+```
+
+## Testcontainers
+
+```java
+@SpringBootTest
+@Testcontainers
+class PostgresIntegrationTest {
+
+    @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);
+    }
+
+    @Autowired
+    private UserRepository userRepository;
+
+    @Test
+    void shouldPersistUser() {
+        User saved = userRepository.save(new User("John", "john@example.com"));
+        
+        assertThat(saved.getId()).isNotNull();
+        assertThat(userRepository.findById(saved.getId())).isPresent();
+    }
+}
+```
+
+## Test Configuration
+
+```java
+@TestConfiguration
+class TestConfig {
+
+    @Bean
+    @Primary
+    public EmailService mockEmailService() {
+        return mock(EmailService.class);
+    }
+}
+
+@SpringBootTest
+@Import(TestConfig.class)
+class ServiceTest {
+    // Uses mock EmailService
+}
+```
+
+## Test Properties
+
+```properties
+# src/test/resources/application-test.properties
+spring.datasource.url=jdbc:h2:mem:testdb
+spring.jpa.hibernate.ddl-auto=create-drop
+spring.jpa.show-sql=true
+```
+
+```java
+@SpringBootTest
+@ActiveProfiles("test")
+class TestWithProfile { }
+```

package/rules/javascript/best-practices/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: JavaScript Best Practices
+description: Idiomatic JavaScript patterns and conventions for maintainable code.
+metadata:
+  labels: [javascript, best-practices, conventions, code-quality]
+  triggers:
+    files: ['**/*.js', '**/*.mjs']
+    keywords: [module, import, export, error, validation]
+---
+
+# JavaScript Best Practices
+
+## **Priority: P1 (OPERATIONAL)**
+
+Conventions and patterns for writing maintainable JavaScript.
+
+## Implementation Guidelines
+
+- **Naming**: `camelCase` (vars/funcs), `PascalCase` (classes), `UPPER_SNAKE` (constants).
+- **Errors**: Throw `Error` objects only. Handle all async errors.
+- **Comments**: JSDoc for APIs. Explain "why" not "what".
+- **Files**: One entity per file. `index.js` for exports.
+- **Modules**: Named exports only. Order: Ext -> Int -> Rel.
+
+## Anti-Patterns
+
+- **No Globals**: Encapsulate state.
+- **No Magic Numbers**: Use `const`.
+- **No Nesting**: Guard clauses/early returns.
+- **No Defaults**: Use named exports.
+- **No Side Effects**: Keep functions pure.
+
+## Code
+
+```javascript
+// Constants
+const STATUS = { OK: 200, ERROR: 500 };
+
+// Errors
+class APIError extends Error {
+  constructor(msg, code) {
+    super(msg);
+    this.code = code;
+  }
+}
+
+// Async + JDoc
+/** @throws {APIError} */
+export async function getData(id) {
+  if (!id) throw new APIError('Missing ID', 400);
+  const res = await fetch(`/api/${id}`);
+  if (!res.ok) throw new APIError('Failed', res.status);
+  return res.json();
+}
+```
+
+## Reference & Examples
+
+For module patterns and project structure:
+See [references/REFERENCE.md](references/REFERENCE.md).
+
+## Related Topics
+
+language | tooling