Copilot instructions

1---
2applyTo: "**/*Test.java, **/*IT.java, **/*Spec.java, **/*.spec.ts, **/*Tests.java"
3---
4 
5## Context
6 
7This instruction file applies to all test source files across the project. Tests are a first-class concern — untested code is unacceptable for production. This file governs test structure, naming, tooling, and quality standards across Java (JUnit 5) and Angular (Jasmine/Jest) test suites. Test code follows the same style and quality bar as production code: no magic numbers, no copy-paste, no meaningless assertions.
8 
9---
10 
11## Java Test Standards
12 
13### Framework Stack
14 
15| Tool | Role |
16|------|------|
17| JUnit 5 (`org.junit.jupiter`) | Test lifecycle and execution |
18| AssertJ | Fluent, readable assertions |
19| Mockito 5.x | Mocking and verification |
20| Awaitility | Async/concurrent test assertions |
21| Testcontainers | Real infrastructure in integration tests |
22| Spring Boot Test Slices | `@WebMvcTest`, `@DataJpaTest`, `@JsonTest` |
23| Pact / Spring Cloud Contract | Consumer-driven contract testing |
24 
25### Test Naming Convention
26 
27Use the pattern: `methodName_scenario_expectedResult`
28 
29```java
30@Test
31void findById_existingCustomer_returnsCustomerDto() { ... }
32 
33@Test
34void findById_nonExistentId_throwsCustomerNotFoundException() { ... }
35 
36@Test
37void createOrder_nullCustomerId_throwsIllegalArgumentException() { ... }
38 
39@Test
40void processPayment_insufficientBalance_returnsDeclinedResult() { ... }
41```
42 
43### Class Structure
44 
45```java
46@ExtendWith(MockitoExtension.class)
47class OrderServiceTest {
48 
49    @Mock
50    private OrderRepository orderRepository;
51 
52    @Mock
53    private PaymentGateway paymentGateway;
54 
55    @InjectMocks
56    private OrderService orderService;
57 
58    @BeforeEach
59    void setUp() {
60        // shared test data initialization
61    }
62 
63    @Test
64    void createOrder_validRequest_persistsAndReturnsOrder() {
65        // Arrange
66        var request = OrderTestFactory.validCreateRequest();
67        var savedOrder = OrderTestFactory.savedOrder();
68        when(orderRepository.save(any(Order.class))).thenReturn(savedOrder);
69 
70        // Act
71        OrderResponse response = orderService.createOrder(request);
72 
73        // Assert
74        assertThat(response).isNotNull();
75        assertThat(response.orderId()).isEqualTo(savedOrder.getId());
76        assertThat(response.status()).isEqualTo(OrderStatus.PENDING);
77        verify(orderRepository).save(any(Order.class));
78    }
79}
80```
81 
82### Assertions
83 
84```java
85// CORRECT: AssertJ fluent assertions
86assertThat(result).isNotNull();
87assertThat(result.getName()).isEqualTo("John Doe");
88assertThat(result.getItems()).hasSize(3).extracting("sku").contains("SKU-001", "SKU-002");
89assertThat(exception).isInstanceOf(OrderNotFoundException.class)
90    .hasMessageContaining("Order not found");
91 
92// Multi-field checks: use assertSoftly to report all failures at once
93assertSoftly(softly -> {
94    softly.assertThat(order.getId()).isNotNull();
95    softly.assertThat(order.getStatus()).isEqualTo(OrderStatus.CONFIRMED);
96    softly.assertThat(order.getCustomerId()).isEqualTo(expectedCustomerId);
97});
98 
99// WRONG: Never use JUnit assertEquals
100assertEquals("John Doe", result.getName());  // ❌
101assertTrue(result != null);                   // ❌
102```
103 
104### Parameterized Tests
105 
106```java
107@ParameterizedTest(name = "amount={0} should result in {1}")
108@MethodSource("paymentAmountProvider")
109void calculateFee_variousAmounts_returnsCorrectFee(BigDecimal amount, BigDecimal expectedFee) {
110    assertThat(feeCalculator.calculate(amount)).isEqualByComparingTo(expectedFee);
111}
112 
113private static Stream<Arguments> paymentAmountProvider() {
114    return Stream.of(
115        Arguments.of(new BigDecimal("100.00"), new BigDecimal("2.50")),
116        Arguments.of(new BigDecimal("0.00"), BigDecimal.ZERO),
117        Arguments.of(new BigDecimal("999.99"), new BigDecimal("24.99"))
118    );
119}
120```
121 
122### Exception Testing
123 
124```java
125@Test
126void findById_notFound_throwsOrderNotFoundException() {
127    when(orderRepository.findById(any(UUID.class))).thenReturn(Optional.empty());
128 
129    assertThatThrownBy(() -> orderService.findById(UUID.randomUUID()))
130        .isInstanceOf(OrderNotFoundException.class)
131        .hasMessageContaining("not found");
132}
133```
134 
135### Async Tests — Awaitility
136 
137```java
138@Test
139void processAsync_eventPublished_listenerReceivesEvent() {
140    orderService.processAsync(orderId);
141 
142    await()
143        .atMost(Duration.ofSeconds(5))
144        .pollInterval(Duration.ofMillis(200))
145        .untilAsserted(() ->
146            assertThat(eventCaptor.getEvents()).anyMatch(e -> e.getOrderId().equals(orderId))
147        );
148}
149```
150 
151### Spring MVC Controller Tests
152 
153```java
154@WebMvcTest(OrderController.class)
155class OrderControllerTest {
156 
157    @Autowired
158    private MockMvc mockMvc;
159 
160    @Autowired
161    private ObjectMapper objectMapper;
162 
163    @MockBean
164    private OrderService orderService;
165 
166    @Test
167    void getOrder_existingOrder_returns200WithBody() throws Exception {
168        var response = OrderTestFactory.orderResponse();
169        when(orderService.findById(response.orderId())).thenReturn(response);
170 
171        mockMvc.perform(get("/api/v1/orders/{id}", response.orderId())
172                .accept(MediaType.APPLICATION_JSON))
173            .andExpect(status().isOk())
174            .andExpect(jsonPath("$.orderId").value(response.orderId().toString()))
175            .andExpect(jsonPath("$.status").value("PENDING"));
176    }
177 
178    @Test
179    void createOrder_invalidBody_returns422WithViolations() throws Exception {
180        var invalidRequest = new CreateOrderRequest(null, List.of());
181 
182        mockMvc.perform(post("/api/v1/orders")
183                .contentType(MediaType.APPLICATION_JSON)
184                .content(objectMapper.writeValueAsString(invalidRequest)))
185            .andExpect(status().isUnprocessableEntity())
186            .andExpect(jsonPath("$.violations").isArray());
187    }
188}
189```
190 
191### Spring Data JPA Repository Tests
192 
193```java
194@DataJpaTest
195@Testcontainers
196class OrderRepositoryIT {
197 
198    @Container
199    static PostgreSQLContainer<?> db = new PostgreSQLContainer<>("postgres:16-alpine");
200 
201    @DynamicPropertySource
202    static void properties(DynamicPropertyRegistry registry) {
203        registry.add("spring.datasource.url", db::getJdbcUrl);
204        registry.add("spring.datasource.username", db::getUsername);
205        registry.add("spring.datasource.password", db::getPassword);
206    }
207 
208    @Autowired
209    private OrderRepository orderRepository;
210 
211    @Test
212    void findByIdWithLineItems_orderWithItems_fetchesEagerly() {
213        // given: pre-seeded test data via @Sql or test fixture
214        UUID orderId = UUID.fromString("...");
215 
216        // when
217        Optional<Order> result = orderRepository.findByIdWithLineItems(orderId);
218 
219        // then
220        assertThat(result).isPresent();
221        assertThat(result.get().getLineItems()).hasSize(2);
222    }
223}
224```
225 
226### Test Data — Factory Pattern
227 
228```java
229// Use static factory methods or builder pattern — never raw `new` in test body
230public final class OrderTestFactory {
231 
232    private OrderTestFactory() {}
233 
234    public static Order pendingOrder() {
235        return Order.builder()
236            .id(UUID.randomUUID())
237            .customerId(UUID.randomUUID())
238            .status(OrderStatus.PENDING)
239            .createdAt(Instant.now())
240            .lineItems(List.of(lineItem()))
241            .build();
242    }
243 
244    public static CreateOrderRequest validCreateRequest() {
245        return new CreateOrderRequest(UUID.randomUUID(), List.of(lineItemRequest()));
246    }
247}
248```
249 
250---
251 
252## Angular / TypeScript Test Standards
253 
254### Component Tests
255 
256```typescript
257describe('CustomerListComponent', () => {
258  let component: CustomerListComponent;
259  let fixture: ComponentFixture<CustomerListComponent>;
260  let customerServiceSpy: jasmine.SpyObj<CustomerService>;
261 
262  beforeEach(async () => {
263    customerServiceSpy = jasmine.createSpyObj('CustomerService', ['getAll']);
264    customerServiceSpy.getAll.and.returnValue(of([{ id: '1', name: 'Alice' }]));
265 
266    await TestBed.configureTestingModule({
267      imports: [CustomerListComponent],
268      providers: [{ provide: CustomerService, useValue: customerServiceSpy }],
269    }).compileComponents();
270 
271    fixture = TestBed.createComponent(CustomerListComponent);
272    component = fixture.componentInstance;
273    fixture.detectChanges();
274  });
275 
276  it('should display customers returned by service', () => {
277    const items = fixture.nativeElement.querySelectorAll('.customer-list__item');
278    expect(items.length).toBe(1);
279    expect(items[0].textContent).toContain('Alice');
280  });
281 
282  it('should call getAll on init', () => {
283    expect(customerServiceSpy.getAll).toHaveBeenCalledTimes(1);
284  });
285});
286```
287 
288### Service Tests
289 
290```typescript
291describe('CustomerService', () => {
292  let service: CustomerService;
293  let httpMock: HttpTestingController;
294 
295  beforeEach(() => {
296    TestBed.configureTestingModule({
297      imports: [HttpClientTestingModule],
298      providers: [CustomerService],
299    });
300    service = TestBed.inject(CustomerService);
301    httpMock = TestBed.inject(HttpTestingController);
302  });
303 
304  afterEach(() => httpMock.verify());
305 
306  it('getAll should return typed customer array', () => {
307    const mockCustomers: Customer[] = [{ id: '1', name: 'Alice', active: true }];
308 
309    service.getAll().subscribe(customers => {
310      expect(customers).toEqual(mockCustomers);
311    });
312 
313    const req = httpMock.expectOne('/api/v1/customers');
314    expect(req.request.method).toBe('GET');
315    req.flush(mockCustomers);
316  });
317});
318```
319 
320---
321 
322## Coverage Requirements
323 
324- **Business logic classes:** 80% line coverage, 70% branch coverage minimum
325- **Controllers:** All endpoints tested for happy path + at least one error case
326- **Repositories:** All custom queries tested
327- **Every `if` condition:** Must have at least one true-branch and one false-branch test
328- **Every `catch` block:** Must have a test that triggers the exception
329- **Every `Optional.empty()` path:** Must have a corresponding test
330 
331---
332 
333## What Copilot Must NOT Generate in Tests
334 
335| Anti-Pattern | Why |
336|-------------|-----|
337| `Thread.sleep(1000)` | Use `Awaitility` — sleep is flaky |
338| Empty `@Test` methods | A test with no assertions is misleading |
339| `assertTrue(true)` or `assertNotNull(result)` only | Must assert meaningful business outcomes |
340| Mocking the class under test | Defeats the purpose of the test |
341| `@SpringBootTest` for a pure unit test | Use slices or pure Mockito — full context is slow |
342| Test methods sharing mutable state | Tests must be independent and order-agnostic |
343| Raw `new` in test body for domain objects | Use factory methods or builders |
344| Testing private methods directly | Test behaviour through the public API |
345| Ignoring or disabling tests without explanation | `@Disabled` requires a comment with a tracking issue |
346