@freshworks/shiftleft-tools 1.1.8

package/templates/rules/testing.mdc

@@ -0,0 +1,248 @@
+---
+description: Test writing rules - MANDATORY when editing test files
+globs:
+  - "**/*Test.java"
+  - "**/*IntegrationTest.java"
+  - "**/src/test/**/*.java"
+  - "**/src/integration-test/**/*.java"
+---
+
+# Test Writing Rules - MANDATORY
+
+All tests MUST survive PIT mutation testing. Weak assertions WILL fail.
+
+## CRITICAL: Mutation Testing (PIT)
+
+- Target mutation score: **80%+**
+- Run mutation tests: `./postman/scripts/report-generators/mutation-report.sh`
+- Weak assertions allow mutants to survive = test is worthless
+
+## Assertion Strength - CRITICAL
+
+NEVER write weak assertions. They prove nothing and mutants will survive.
+
+### WRONG - Weak Assertions (DO NOT USE):
+
+```java
+assertNotNull(result);  // WRONG - proves nothing
+assertTrue(result.isPresent());  // WRONG - no value check
+assertThat(list).isNotEmpty();  // WRONG - no content check
+assertThat(count).isGreaterThan(0);  // WRONG - boundary not tested
+assertThat(result).isNotNull();  // WRONG - still proves nothing
+verify(repository).save(any());  // WRONG - content not verified
+```
+
+### CORRECT - Strong Assertions (USE THESE):
+
+```java
+assertThat(result.getId()).isEqualTo(expectedId);  // Specific value
+assertThat(result.getName()).isEqualTo("Expected Name");  // Exact match
+assertThat(result.getStatus()).isEqualTo(Status.ACTIVE);  // Enum value
+assertThat(list).containsExactly(item1, item2);  // Content verified
+assertThat(list).hasSize(3);  // Combined with content check
+```
+
+## Test All Output Fields
+
+If a method returns an object with 5 fields, you MUST assert on ALL 5 fields.
+
+### WRONG:
+
+```java
+AppDTO result = service.getApp("123");
+assertThat(result.getId()).isEqualTo("123");  // WRONG - only checking 1 field
+```
+
+### CORRECT:
+
+```java
+AppDTO result = service.getApp("123");
+assertThat(result.getId()).isEqualTo("123");
+assertThat(result.getName()).isEqualTo("Test App");
+assertThat(result.getType()).isEqualTo(AppType.PLATFORM);
+assertThat(result.getStatus()).isEqualTo(Status.ACTIVE);
+assertThat(result.getCreatedAt()).isNotNull();  // OK for timestamps
+```
+
+## Verify Saved Arguments with ArgumentCaptor
+
+### WRONG:
+
+```java
+verify(repository).save(any());  // Mutant survives - content not verified
+```
+
+### CORRECT:
+
+```java
+ArgumentCaptor<App> captor = ArgumentCaptor.forClass(App.class);
+verify(repository).save(captor.capture());
+App saved = captor.getValue();
+assertThat(saved.getName()).isEqualTo("Expected Name");
+assertThat(saved.getType()).isEqualTo(AppType.CUSTOM);
+assertThat(saved.getStatus()).isEqualTo(Status.PENDING);
+```
+
+## Exception Messages MUST Be Verified
+
+### WRONG:
+
+```java
+assertThrows(ResourceNotFoundException.class, () -> service.getApp("invalid"));
+```
+
+### CORRECT:
+
+```java
+var ex = assertThrows(ResourceNotFoundException.class, () -> service.getApp("invalid"));
+assertThat(ex.getMessage()).isEqualTo("App not found with id: invalid");
+```
+
+## Use Parameterized Tests for Combinations
+
+For methods with multiple inputs, you MUST use `@ParameterizedTest`:
+
+```java
+@ParameterizedTest
+@EnumSource(AppType.class)
+void getApps_shouldFilterByAllAppTypes(AppType type) {
+    // Test each enum value
+}
+
+@ParameterizedTest
+@MethodSource("invalidInputs")
+void create_shouldRejectInvalidInputs(String name, String expectedError) {
+    var ex = assertThrows(BadRequestException.class, () -> service.create(name));
+    assertThat(ex.getMessage()).contains(expectedError);
+}
+
+static Stream<Arguments> invalidInputs() {
+    return Stream.of(
+        Arguments.of(null, "Name is required"),
+        Arguments.of("", "Name is required"),
+        Arguments.of("a".repeat(256), "Name must not exceed 255")
+    );
+}
+```
+
+## Test Naming Convention
+
+Use: `methodName_whenCondition_shouldExpectedResult`
+
+```java
+@Test
+void getAppById_whenAppExists_shouldReturnAppDetails() { }
+
+@Test
+void getAppById_whenAppNotFound_shouldThrowResourceNotFoundException() { }
+
+@Test
+void createApp_whenValidRequest_shouldReturnCreatedApp() { }
+
+@Test
+void createApp_whenDuplicateName_shouldThrowConflictException() { }
+```
+
+## Unit Test Structure
+
+```java
+@ExtendWith(MockitoExtension.class)
+class AppServiceTest {
+    @Mock
+    private AppRepository appRepository;
+
+    @Mock
+    private AppMapper appMapper;
+
+    @InjectMocks
+    private AppService appService;
+
+    @Nested
+    class GetAppById {
+        @Test
+        void whenAppExists_shouldReturnAppDetails() {
+            // Given
+            String appId = "app-123";
+            App app = App.builder().externalId(appId).name("Test").build();
+            AppDetailsDTO expected = AppDetailsDTO.builder().id(appId).name("Test").build();
+
+            when(appRepository.findByExternalId(appId)).thenReturn(Optional.of(app));
+            when(appMapper.toDetailsDTO(app)).thenReturn(expected);
+
+            // When
+            AppDetailsDTO result = appService.getAppById(appId);
+
+            // Then
+            assertThat(result.getId()).isEqualTo(appId);
+            assertThat(result.getName()).isEqualTo("Test");
+            verify(appRepository).findByExternalId(appId);
+        }
+
+        @Test
+        void whenAppNotFound_shouldThrowException() {
+            // Given
+            when(appRepository.findByExternalId("invalid")).thenReturn(Optional.empty());
+
+            // When/Then
+            var ex = assertThrows(ResourceNotFoundException.class,
+                    () -> appService.getAppById("invalid"));
+            assertThat(ex.getMessage()).isEqualTo("App not found with id: invalid");
+        }
+    }
+}
+```
+
+## Integration Test Structure
+
+```java
+@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
+@AutoConfigureMockMvc
+@ActiveProfiles("integration")
+@Sql(scripts = "/data-sql/apps.sql", executionPhase = Sql.ExecutionPhase.BEFORE_TEST_METHOD)
+@Sql(scripts = "/data-sql/cleanup.sql", executionPhase = Sql.ExecutionPhase.AFTER_TEST_METHOD)
+class AppControllerIntegrationTest {
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Autowired
+    private JdbcTemplate jdbcTemplate;
+
+    @MockBean
+    private FreshIDApiClient freshIDApiClient;  // Mock external services only
+
+    @Test
+    void getApp_whenExists_shouldReturn200WithDetails() throws Exception {
+        mockMvc.perform(get("/api/v1/apps/{id}", "app-1")
+                .header("Authorization", "Bearer test-token"))
+            .andExpect(status().isOk())
+            .andExpect(jsonPath("$.id").value("app-1"))
+            .andExpect(jsonPath("$.name").value("Test App"))
+            .andExpect(jsonPath("$.type").value("PLATFORM"));
+    }
+
+    @Test
+    void getApp_whenNotFound_shouldReturn404() throws Exception {
+        mockMvc.perform(get("/api/v1/apps/{id}", "nonexistent")
+                .header("Authorization", "Bearer test-token"))
+            .andExpect(status().isNotFound())
+            .andExpect(jsonPath("$.detail").value("App not found with id: nonexistent"));
+    }
+}
+```
+
+## Running Tests
+
+| Command | What it runs |
+|---------|--------------|
+| `mvn test` | Unit tests only |
+| `./postman/scripts/report-generators/mutation-report.sh` | PIT mutation testing |
+| `cd postman/scripts && ./runners/run-tests-local.sh` | Postman API tests (local) |
+| `cd postman/scripts && ./run-all.sh` | Full test suite |
+| `./postman/scripts/report-generators/java-api-coverage-matrix.sh` | API coverage report |
+
+## Before Merge Checklist
+
+1. `mvn test` - all unit tests pass
+2. `./postman/scripts/runners/run-tests-local.sh` - all Postman tests pass
+3. `./postman/scripts/report-generators/java-api-coverage-matrix.sh` - 100% 2xx coverage
+4. `./postman/scripts/report-generators/mutation-report.sh` - 80%+ mutation score

package/templates/skills/_shared/postman-standards.md

@@ -0,0 +1,380 @@
+# Postman/Newman Standards
+
+Language-agnostic standards for writing and organizing Postman integration tests. Referenced by all language-specific skill files.
+
+---
+
+## Library scripts are staged from the package — never copied or committed
+
+The pipeline's library scripts (`postman/scripts/lib/`, `runners/`,
+`report-generators/`, `auth/`, `infra/`, `database/`) are **not** vendored into
+the repo. They live in the installed `shiftleft-tools` package and are pulled in
+on demand:
+
+- `shiftleft test` (and the committed `postman/scripts/run-all.sh` shim) stage the
+  current scripts automatically before every run.
+- `shiftleft stage-scripts` stages them on their own — run this first if you need
+  to invoke an individual staged script directly (e.g.
+  `./postman/scripts/report-generators/...`).
+
+Staged scripts are gitignored and refreshed each run, so they always match the
+installed package. **Do not copy scripts from a templates directory, write them
+from scratch, or commit them.** Only `run-all.sh` (a thin shim) and repo-owned
+files (collections, config, environments, Node's `setup-mocks.js`, Java's
+`wiremock/mappings/`) are committed.
+
+**Exception — a customized library script.** If a repo must customize a library
+script (e.g. a service-specific `runners/run-tests-local.sh`), mark it protected
+so staging won't overwrite it: `shiftleft protect runners/run-tests-local.sh`.
+Protected paths are recorded in `.shiftleft.json` and must stay committed.
+
+---
+
+## Collection Organization
+
+Collections live in `postman/collections/` with numbered naming for execution order.
+
+**Naming convention**: `XX-description.json`
+
+**Example structure** (explore actual folder for this project's collections):
+```
+postman/collections/
+├── 01-bootstrap.json              # Creates prerequisite test data, sets env vars
+├── 02-core-crud.json              # Core CRUD operations
+├── 03-authorization.json          # Auth tests (may be STAGING ONLY)
+├── 04-query-params.json           # Sorting, filtering, pagination
+├── 05-validation.json             # Invalid input, 400 errors
+└── 99-cleanup.json                # Deletes all test data, always runs last
+```
+
+**Common patterns**:
+- Authorization tests often skip in local (no API gateway)
+- Internal/cache endpoints often skip in staging (not exposed)
+
+---
+
+## Writing Test Assertions
+
+### MANDATORY: One Status Code Per Test
+
+Each test request MUST assert exactly ONE HTTP status code:
+
+```javascript
+// CORRECT - Single status code
+pm.test("Status code is 200", function () {
+    pm.response.to.have.status(200);
+});
+
+// WRONG - Multiple status codes
+pm.test("Status is valid", function () {
+    pm.expect(pm.response.code).to.be.oneOf([200, 201]);  // NEVER do this
+});
+```
+
+### MANDATORY: Strong Value Assertions
+
+```javascript
+// WRONG - Weak assertions
+pm.test("Response has data", function () {
+    pm.expect(pm.response.json()).to.not.be.null;  // Proves nothing
+});
+
+// CORRECT - Strong assertions
+pm.test("Response has correct data", function () {
+    const json = pm.response.json();
+    pm.expect(json.id).to.eql("app-123");
+    pm.expect(json.name).to.eql("Expected Name");
+    pm.expect(json.type).to.eql("PLATFORM");
+});
+```
+
+### FORBIDDEN: 5xx Status Code Assertions
+
+NEVER assert on 5xx status codes - they indicate bugs, not expected behavior:
+
+```javascript
+// FORBIDDEN - Never do this
+pm.test("Status code is 500", function () {
+    pm.response.to.have.status(500);
+});
+```
+
+---
+
+## Environment-Specific Skip Pattern
+
+Some tests behave differently between local and staging. Use this pattern:
+
+### Skip in Local (Staging-Only Test)
+
+```javascript
+// Pre-request Script
+if (pm.environment.get('environment') === 'local') {
+    console.log('[SKIP] Reason: JWT validation happens at gateway, local has no gateway | Env: local');
+    pm.execution.skipRequest();
+}
+```
+
+### Skip in Staging (Local-Only Test)
+
+```javascript
+// Pre-request Script
+if (pm.environment.get('environment') !== 'local') {
+    console.log('[SKIP] Reason: Internal endpoint not exposed in staging | Env: staging');
+    pm.execution.skipRequest();
+}
+```
+
+### Skip Log Format (MANDATORY)
+
+```
+[SKIP] Reason: <why this test is skipped> | Env: <local|staging>
+```
+
+### Naming Convention for Environment-Specific Tests
+
+Append `(local)` or `(staging)` to test names:
+
+```
+"Create - Invalid Token (staging)"    // Expects 401, skipped in local
+"Create - Invalid Token (local)"      // Expects 400, skipped in staging
+"PATCH - 404 non-existent (staging)"  // Expects 404, skipped in local
+"PATCH - 403 non-existent (local)"    // Expects 403, skipped in staging
+```
+
+---
+
+## Why Tests Differ by Environment
+
+| Scenario | Local Behavior | Staging Behavior |
+|----------|---------------|------------------|
+| Invalid JWT token | 400 Bad Request | 401 Unauthorized (API Gateway) |
+| Non-existent resource with bad auth | 403 Forbidden | 404 Not Found |
+| Internal endpoints | Works | Not exposed |
+| Authorization checks | @PreAuthorize first | Resource lookup first |
+
+---
+
+## HTTP Status Coverage Requirements
+
+Every endpoint MUST have tests for:
+
+| Status | When | Priority |
+|--------|------|----------|
+| 200 OK | GET/PUT/PATCH success | High |
+| 201 Created | POST success | High |
+| 400 Bad Request | Invalid input/validation | High |
+| 401 Unauthorized | Missing/invalid auth | High |
+| 404 Not Found | Resource not found | High |
+| 204 No Content | DELETE success | Medium |
+| 409 Conflict | Duplicate/concurrent update | Medium |
+
+---
+
+## Query Parameter Coverage - MANDATORY
+
+For endpoints with query parameters, you MUST test each parameter with multiple values.
+
+### What to Test
+
+| Parameter Type | Required Tests |
+|---------------|----------------|
+| **Filter params** (type, status) | Each valid enum/value |
+| **Sort params** (sort, orderBy) | Ascending AND descending |
+| **Pagination** (page, size) | First page, middle page, edge cases |
+| **Search** (query, q) | Valid search, empty results |
+
+### Example: GET /apps with Query Params
+
+```javascript
+// Test each filter value
+GET /apps?type=PLATFORM
+GET /apps?type=CUSTOM
+GET /apps?type=NATIVE
+
+// Test sorting - BOTH directions
+GET /apps?sort=name,asc
+GET /apps?sort=name,desc
+GET /apps?sort=createdAt,desc
+
+// Test pagination
+GET /apps?page=0&size=10
+GET /apps?page=1&size=5
+GET /apps?size=100  // Max size
+
+// Test combinations
+GET /apps?type=PLATFORM&sort=name,asc&page=0&size=20
+```
+
+### Assertions for Query Params
+
+```javascript
+// For filter tests - verify filtered results
+pm.test("All results match filter", function () {
+    const json = pm.response.json();
+    json.content.forEach(item => {
+        pm.expect(item.type).to.eql("PLATFORM");
+    });
+});
+
+// For sort tests - verify order
+pm.test("Results sorted by name ascending", function () {
+    const json = pm.response.json();
+    const names = json.content.map(item => item.name);
+    const sorted = [...names].sort();
+    pm.expect(names).to.eql(sorted);
+});
+
+// For pagination - verify page metadata
+pm.test("Pagination metadata correct", function () {
+    const json = pm.response.json();
+    pm.expect(json.page).to.eql(0);
+    pm.expect(json.size).to.eql(10);
+    pm.expect(json.totalElements).to.be.a('number');
+});
+```
+
+---
+
+## Include Parameter Coverage - MANDATORY
+
+For endpoints with `include` parameter, test ALL expected values individually AND in combination.
+
+### Expected Include Values
+
+| Endpoint Type | Expected Values |
+|--------------|-----------------|
+| List endpoints (`/apps`, `/apps/{id}`) | `configs`, `oauth_configs_list`, `secure_iparams` |
+| Configuration endpoints | `secure_iparams`, `oauth_iparams`, `extension_type` |
+
+### Example: Testing Include Parameter
+
+```javascript
+// Test each include value INDIVIDUALLY
+GET /apps/{id}?include=configs
+GET /apps/{id}?include=oauth_configs_list
+GET /apps/{id}?include=secure_iparams
+
+// Test combinations
+GET /apps/{id}?include=configs,oauth_configs_list
+GET /apps/{id}?include=configs,oauth_configs_list,secure_iparams
+```
+
+### Assertions for Include Tests
+
+```javascript
+// Verify included data is present
+pm.test("Response includes configs", function () {
+    const json = pm.response.json();
+    pm.expect(json).to.have.property('configs');
+    pm.expect(json.configs).to.be.an('array');
+});
+
+// Verify data is NOT included when not requested
+pm.test("Response excludes oauth_configs when not requested", function () {
+    const json = pm.response.json();
+    pm.expect(json.oauthConfigs).to.be.undefined;
+});
+```
+
+---
+
+## Request Body Variations - For POST/PUT/PATCH
+
+For write operations, test different body scenarios to ensure validation works correctly.
+
+### Required Body Test Cases
+
+| Test Case | Purpose | Expected Status |
+|-----------|---------|-----------------|
+| All required fields | Happy path | 201/200 |
+| Required + optional fields | Full payload | 201/200 |
+| Minimal valid body | Edge case | 201/200 |
+| Missing required field | Validation | 400 |
+| Invalid field value | Validation | 400 |
+| Empty body | Validation | 400 |
+| Extra unknown fields | Ignored/rejected | 201 or 400 |
+
+### Example: POST /apps Body Variations
+
+```javascript
+// Test 1: All required fields
+{
+    "name": "Test App",
+    "type": "PLATFORM"
+}
+
+// Test 2: With optional fields
+{
+    "name": "Test App",
+    "type": "PLATFORM",
+    "description": "Optional description",
+    "tags": ["tag1", "tag2"]
+}
+
+// Test 3: Missing required field (400)
+{
+    "type": "PLATFORM"
+    // name is missing
+}
+
+// Test 4: Invalid enum value (400)
+{
+    "name": "Test App",
+    "type": "INVALID_TYPE"
+}
+
+// Test 5: Invalid field format (400)
+{
+    "name": "",  // Empty string
+    "type": "PLATFORM"
+}
+```
+
+### Assertions for Body Validation Tests
+
+```javascript
+// For 400 errors - verify error details
+pm.test("Error response has details", function () {
+    const json = pm.response.json();
+    pm.expect(json).to.have.property('detail');
+    pm.expect(json.detail).to.include('name');  // Field name in error
+});
+```
+
+---
+
+## Collection Variables
+
+Use variables for dynamic values:
+
+- `{{base_url}}` - API base URL
+- `{{auth_token}}` - JWT token
+- `{{app_id}}` - Created app ID (from previous request)
+- `{{version_id}}` - Created version ID
+- `{{tenant_id}}` - Test tenant identifier
+- `{{environment}}` - Current environment (local/staging)
+
+## Pre-request Script: Save Values
+
+```javascript
+// Save value from previous response for chaining
+pm.collectionVariables.set("app_id", pm.response.json().id);
+
+// Generate timestamp
+pm.collectionVariables.set("timestamp", Date.now());
+```
+
+---
+
+## Quick Checklist Before Submitting Tests
+
+- [ ] Each test asserts exactly ONE status code
+- [ ] No `oneOf`, `to.include([...])` for status codes
+- [ ] No 5xx status code assertions
+- [ ] All query parameters have tests with multiple values
+- [ ] All include values tested individually
+- [ ] POST/PUT/PATCH have body variation tests
+- [ ] Strong assertions on response fields (not just `isNotNull`)
+- [ ] Environment skips have `[SKIP] Reason: ... | Env: ...`
+- [ ] Coverage matrix shows 100% 2xx coverage