@freshworks/shiftleft-tools 1.1.8

package/templates/skills/setup-api-tests/SKILL-java.md

@@ -0,0 +1,1094 @@
+# Setup API Tests Skill — Java Spring Boot
+
+Set up Postman/Newman integration test infrastructure for a Java Spring Boot service.
+
+## When to Use
+
+Invoke this skill when the user says:
+- "setup postman", "add postman to this project"
+- "setup integration tests", "add newman"
+- "create postman folder", "initialize postman"
+- "add API testing infrastructure"
+- "setup test suite", "setup tests"
+
+---
+
+# CRITICAL: Explore-First Methodology
+
+**NEVER assume conventions. ALWAYS verify by reading actual source files.**
+
+## The Pattern (MANDATORY for ALL work)
+
+```
+1. EXPLORE  → Read the actual source files that define the contract
+2. TEST     → Run/call something once to verify your understanding
+3. DOCUMENT → State what you found before proceeding
+4. IMPLEMENT → Only now write the code
+5. VERIFY   → Run it and confirm it works
+```
+
+## Why This Matters
+
+Every project has unique conventions:
+- JSON field naming (snake_case vs camelCase)
+- Enum values (VISIBLE vs public, ACTIVE vs active)
+- Request/response wrapper structures
+- Pagination field names (page vs current_page)
+- Shell compatibility (bash 3.2 vs 4+)
+- Classpath requirements (test-scoped dependencies)
+
+**You cannot guess these. You must read the actual code.**
+
+## Before Writing ANY Code
+
+| Task | MUST DO First |
+|------|---------------|
+| Writing Postman assertions | Read the Response DTO class, call endpoint with curl |
+| Writing request bodies | Read the Request DTO class, check validation annotations |
+| Using enum values | Read the actual Enum class definition |
+| Modifying shell scripts | Run `bash --version`, check for reserved variable names |
+| Modifying properties | Read existing properties, check parent config inheritance |
+| Writing field names | Check Jackson naming strategy AND actual DTO fields |
+
+## After Initial Setup
+
+**Run ONE test first and observe actual output:**
+
+1. Start the app with postman profile
+2. Call one real endpoint with `curl` and see actual JSON response
+3. Compare actual field names to your assertions
+4. Fix any mismatches before writing more tests
+
+**Do NOT write all tests assuming they'll work. Verify incrementally.**
+
+---
+
+# Phase 1: Project Analysis (REQUIRED)
+
+**Before generating ANY files, you MUST analyze the project thoroughly.**
+
+## 1.1 Check for Existing Integration Tests
+
+Search for existing test infrastructure:
+
+```
+Search for: *IntegrationTest.java, *IT.java, @SpringBootTest
+Check for: application-test.properties, application-integration.properties
+Check if: postman/ folder already exists
+```
+
+### Decision Point: ASK THE USER (MANDATORY)
+
+**If existing Java integration tests are found:**
+
+> **I found existing integration tests in your project:**
+> - Found X `*IntegrationTest.java` files
+> - Test configuration: [list files found]
+> - Database: [H2 / Testcontainers / etc.]
+>
+> **Options:**
+> 1. **Keep current setup** - I can help improve your existing tests
+> 2. **Add Postman tests alongside** - Adds API coverage reporting and contract testing
+>
+> **Which would you prefer?**
+
+**STOP AND WAIT for user response. Do NOT proceed without explicit choice.**
+
+If user chooses Option 1: Help improve existing tests, do not proceed with Postman setup.
+If user chooses Option 2: Continue with Phase 1.2.
+
+---
+
+## 1.2 Check JSON Serialization Strategy
+
+**CRITICAL: This determines field names in ALL test assertions.**
+
+Search for Jackson configuration:
+
+1. In `application.properties` or `application.yml`:
+   ```
+   spring.jackson.property-naming-strategy=SNAKE_CASE
+   ```
+
+2. In `@Configuration` classes, look for custom `ObjectMapper` beans
+
+3. **If SNAKE_CASE is configured:**
+   - All API responses use `snake_case` field names
+   - Use: `external_id`, `created_at`, `subscription_type`, `total_items`
+
+4. **If not configured (default LOWER_CAMEL_CASE):**
+   - All API responses use `camelCase` field names
+   - Use: `externalId`, `createdAt`, `subscriptionType`, `totalItems`
+
+**Record finding:**
+```
+JSON_NAMING = SNAKE_CASE | CAMEL_CASE
+```
+
+---
+
+## 1.3 Check Database Setup
+
+### In pom.xml:
+
+Check H2 dependency scope:
+```xml
+<dependency>
+    <groupId>com.h2database</groupId>
+    <artifactId>h2</artifactId>
+    <scope>test</scope>  <!-- or runtime -->
+</dependency>
+```
+
+**Record finding:**
+```
+H2_SCOPE = test | runtime | compile | not_present
+```
+
+**IMPORTANT:** If `H2_SCOPE = test`, the app cannot be started with `java -jar`.
+Must use `mvn spring-boot:run` OR `java -cp` with test classpath.
+
+### In application.properties:
+
+Check Flyway configuration:
+```
+spring.flyway.user=???
+spring.flyway.password=???
+spring.datasource.username=???
+```
+
+**Record finding:**
+```
+FLYWAY_USER = sa | root | <other>
+DATASOURCE_USER = sa | root | <other>
+```
+
+**IMPORTANT:** If `spring.flyway.user` is set to anything other than `sa`,
+you MUST override it in `application-postman.properties` to use `sa` for H2.
+
+---
+
+## 1.4 Check Server Configuration
+
+In `application.properties`:
+
+```
+server.port=???
+server.servlet.context-path=???
+management.server.port=???
+management.endpoints.web.exposure.include=???
+```
+
+**Record findings:**
+```
+APP_PORT = 8080 | 9090 | <other>
+CONTEXT_PATH = /api | /marketplace/api | <other>
+MANAGEMENT_PORT = same as APP_PORT | different (e.g., 9091)
+```
+
+**IMPORTANT:** If `MANAGEMENT_PORT` is different from `APP_PORT`:
+- Health checks on management port may fail due to Spring Security
+- Use main app port for health checks instead
+
+---
+
+## 1.5 Check Existing Test Profiles
+
+Look for existing test property files:
+- `src/test/resources/application-*.properties`
+- `src/main/resources/application-test.properties`
+- `src/main/resources/application-integration.properties`
+
+**If found:** REUSE their configuration patterns for consistency.
+
+**Record finding:**
+```
+EXISTING_TEST_PROFILE = test | integration | none
+```
+
+---
+
+## 1.6 Check Response Structure
+
+**Before writing assertions, understand the actual API response format:**
+
+1. Read DTO classes (e.g., `*Response.java`, `*DTO.java`)
+2. Check pagination wrapper classes for field names:
+   - `totalItems` vs `total` vs `count`
+   - `data` vs `items` vs `listings` vs `results`
+3. Note any nested structures
+
+---
+
+## 1.7 Record All Findings
+
+Document before proceeding:
+
+```
+JSON_NAMING = SNAKE_CASE | CAMEL_CASE
+H2_SCOPE = test | runtime
+FLYWAY_USER = sa | root | <other>
+APP_PORT = <port>
+CONTEXT_PATH = <path>
+MANAGEMENT_PORT = <port> (same | different)
+EXISTING_TEST_PROFILE = <name> | none
+```
+
+---
+
+# Phase 2: Generate Infrastructure
+
+## 2.1 Run shiftleft CLI
+
+```bash
+shiftleft init-postman
+```
+
+This creates:
+- `postman/` folder with all scripts
+- `runners/run-tests-local.sh`, `run-all.sh`, `report-generators/mutation-report.sh`
+- `report-generators/java-api-coverage-matrix.sh`, `lib/api_coverage.py`
+- `start-mocks.sh`, `stop-mocks.sh`
+
+---
+
+## 2.2 Create application-postman.properties
+
+**IMPORTANT:** Copy from `EXISTING_TEST_PROFILE` if available, then modify.
+
+Create `src/main/resources/application-postman.properties`:
+
+```properties
+# =============================================================================
+# POSTMAN API TESTS CONFIGURATION
+# =============================================================================
+
+spring.application.name=SERVICE_NAME
+
+# Server - use values from Phase 1.4
+server.port=APP_PORT
+server.servlet.context-path=CONTEXT_PATH
+
+# =============================================================================
+# H2 Database Configuration
+# =============================================================================
+spring.datasource.url=jdbc:h2:mem:testdb;MODE=MySQL;DATABASE_TO_LOWER=TRUE;CASE_INSENSITIVE_IDENTIFIERS=TRUE
+spring.datasource.driver-class-name=org.h2.Driver
+spring.datasource.username=sa
+spring.datasource.password=
+
+spring.jpa.database-platform=org.hibernate.dialect.H2Dialect
+spring.jpa.hibernate.ddl-auto=none
+
+# H2 JSON compatibility
+spring.jpa.properties.hibernate.type.preferred_jdbc_type_for_json=VARCHAR
+
+# =============================================================================
+# Flyway Configuration - ALWAYS OVERRIDE CREDENTIALS FOR H2
+# =============================================================================
+spring.flyway.enabled=true
+spring.flyway.locations=classpath:db/migration,classpath:db/test
+spring.flyway.baseline-on-migrate=true
+spring.flyway.url=${spring.datasource.url}
+spring.flyway.user=sa
+spring.flyway.password=
+
+# =============================================================================
+# Disable Features Not Needed for Local Tests
+# =============================================================================
+spring.cache.type=none
+
+# =============================================================================
+# External Service Configuration
+# =============================================================================
+# Point Feign clients to WireMock (update based on YOUR project's clients)
+# Example: freshid.api.base-url=http://localhost:8089
+```
+
+**CRITICAL:** The `spring.flyway.user=sa` and `spring.flyway.password=` lines
+MUST be included to prevent inheriting MySQL credentials from main config.
+
+---
+
+## 2.3 Customize run-tests-local.sh Based on H2_SCOPE
+
+Edit `postman/scripts/runners/run-tests-local.sh`:
+
+### If H2_SCOPE = test (most common):
+
+The app cannot be started with `java -jar`. Use one of:
+
+**Option A: Use mvn spring-boot:run**
+```bash
+mvn spring-boot:run -Dspring-boot.run.profiles=postman &
+```
+
+**Option B: Use java -cp with test classpath**
+```bash
+# Build classpath including test dependencies
+TEST_CLASSPATH=$(mvn dependency:build-classpath -DincludeScope=test -Dmdep.outputFile=/dev/stdout -q)
+CLASSES_DIR="$PROJECT_ROOT/target/classes:$PROJECT_ROOT/target/test-classes"
+
+java -cp "$CLASSES_DIR:$TEST_CLASSPATH" \
+    com.example.YourApplication \
+    --spring.profiles.active=postman \
+    --server.port=$APP_PORT &
+```
+
+### If H2_SCOPE = runtime:
+
+Standard approach works:
+```bash
+mvn clean package -DskipTests -q
+java -jar target/*.jar --spring.profiles.active=postman &
+```
+
+---
+
+## 2.4 Fix Health Check Logic
+
+Edit the health check section in `run-tests-local.sh`:
+
+### If MANAGEMENT_PORT = APP_PORT:
+
+```bash
+HEALTH_URL="http://localhost:$APP_PORT/actuator/health"
+until curl -s "$HEALTH_URL" | grep -q "UP"; do
+    sleep 2
+done
+```
+
+### If MANAGEMENT_PORT != APP_PORT (may have security issues):
+
+```bash
+# Use main app port - management port may have Spring Security issues
+HEALTH_URL="http://localhost:$APP_PORT$CONTEXT_PATH"
+
+MAX_WAIT=120
+COUNTER=0
+while [ $COUNTER -lt $MAX_WAIT ]; do
+    HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" "$HEALTH_URL" 2>/dev/null || echo "000")
+
+    case "$HTTP_CODE" in
+        2[0-9][0-9]|3[0-9][0-9]|4[0-9][0-9])
+            echo "Application ready (HTTP $HTTP_CODE)"
+            break
+            ;;
+    esac
+
+    sleep 2
+    COUNTER=$((COUNTER + 2))
+done
+```
+
+---
+
+# Phase 3: Create Postman Collections
+
+## 3.1 MANDATORY: Read Before Writing
+
+**Before writing ANY assertion, you MUST read the actual source files.**
+
+### For Response Assertions:
+
+1. **Find and read the Response DTO class:**
+   ```
+   Search for: *Response.java, *DTO.java, *Details.java
+   ```
+
+2. **Check the actual field names in the DTO:**
+   - Look for `@JsonProperty` annotations (override field names)
+   - Check if fields are wrapped in nested objects
+   - Note pagination fields exactly as defined
+
+3. **Check enum values:**
+   ```
+   Search for: enum *Status, enum *Type, enum *Visibility
+   Read the actual enum values - don't assume "public/private" or "active/inactive"
+   ```
+
+4. **Verify with curl BEFORE writing tests:**
+   ```bash
+   curl -s http://localhost:PORT/CONTEXT_PATH/v1/endpoint | jq .
+   ```
+   Use the ACTUAL field names from this response.
+
+### For Request Bodies:
+
+1. **Find and read the Request DTO class:**
+   ```
+   Search for: *Request.java, *CreateRequest.java, *UpdateRequest.java
+   ```
+
+2. **Check validation annotations:**
+   - `@NotNull` - field is required
+   - `@Size(min=X, max=Y)` - length constraints
+   - `@Pattern` - format requirements
+
+3. **Use exact field names from the Request DTO, not guesses.**
+
+### Common Mistakes to Avoid:
+
+| Mistake | Reality |
+|---------|---------|
+| Assuming `name` field | Might be `displayName` or `display_name` |
+| Assuming `public/private` | Might be `VISIBLE/HIDDEN` enum values |
+| Assuming `page/size` | Might be `current_page/page_size` |
+| Assuming direct array response | Might be wrapped: `{ "items": [...] }` |
+| Assuming `totalItems` | Might be `total_items`, `total`, `count`, or `size` |
+
+## 3.2 Use Correct JSON Field Names
+
+**Based on JSON_NAMING from Phase 1.2 AND actual DTO inspection:**
+
+### If JSON_NAMING = SNAKE_CASE:
+
+```javascript
+pm.test("Response has correct fields", function () {
+    const json = pm.response.json();
+    pm.expect(json.external_id).to.exist;
+    pm.expect(json.created_at).to.exist;
+    pm.expect(json.subscription_type).to.eql("FREE");
+    pm.expect(json.total_items).to.be.a("number");
+    pm.expect(json.display_name).to.eql("Test App");
+});
+```
+
+### If JSON_NAMING = CAMEL_CASE:
+
+```javascript
+pm.test("Response has correct fields", function () {
+    const json = pm.response.json();
+    pm.expect(json.externalId).to.exist;
+    pm.expect(json.createdAt).to.exist;
+    pm.expect(json.subscriptionType).to.eql("FREE");
+    pm.expect(json.totalItems).to.be.a("number");
+    pm.expect(json.displayName).to.eql("Test App");
+});
+```
+
+## 3.3 Use Variables for All Ports
+
+In collection JSON, never hardcode ports:
+
+```json
+{
+  "url": {
+    "raw": "{{base_url}}/v1/listings",
+    "host": ["{{base_url}}"],
+    "path": ["v1", "listings"]
+  }
+}
+```
+
+Environment should have:
+```json
+{
+  "key": "base_url",
+  "value": "http://localhost:APP_PORT/CONTEXT_PATH"
+}
+```
+
+---
+
+# Phase 4: H2 Migration Compatibility
+
+## 4.1 Check Existing Migrations
+
+Read migrations in `src/main/resources/db/migration/` and identify incompatible syntax:
+
+| MySQL Syntax | H2 Alternative |
+|-------------|----------------|
+| `DATETIME` | `TIMESTAMP` |
+| `TINYINT(1)` | `BOOLEAN` |
+| `ENGINE=InnoDB` | Remove |
+| `CHARSET=utf8mb4` | Remove |
+| `ON UPDATE CURRENT_TIMESTAMP` | Remove |
+| `JSON` | `CLOB` or `VARCHAR(4000)` |
+| `ENUM('A', 'B')` | `VARCHAR(50)` |
+
+## 4.2 Create H2-Specific Migrations (if needed)
+
+If incompatible syntax found, create override migrations in `src/main/resources/db/test/`:
+
+The Flyway config in `application-postman.properties` includes both locations:
+```properties
+spring.flyway.locations=classpath:db/migration,classpath:db/test
+```
+
+---
+
+# Phase 5: Add PIT Mutation Testing Plugin
+
+**Before running mutation tests, the PIT plugin must be configured in `pom.xml`.**
+
+## 5.1 Check if PIT Plugin Exists
+
+Search `pom.xml` for `pitest-maven`. If not found, add it.
+
+## 5.2 Add PIT Plugin to pom.xml
+
+Add inside `<build><plugins>`:
+
+```xml
+<!-- PIT Mutation Testing Plugin -->
+<plugin>
+    <groupId>org.pitest</groupId>
+    <artifactId>pitest-maven</artifactId>
+    <version>1.15.3</version>
+    <dependencies>
+        <dependency>
+            <groupId>org.pitest</groupId>
+            <artifactId>pitest-junit5-plugin</artifactId>
+            <version>1.2.1</version>
+        </dependency>
+    </dependencies>
+    <configuration>
+        <!-- Target classes to mutate - UPDATE THESE TO MATCH YOUR PROJECT -->
+        <targetClasses>
+            <param>com.yourcompany.yourproject.service.*</param>
+            <param>com.yourcompany.yourproject.mapper.*</param>
+            <param>com.yourcompany.yourproject.converter.*</param>
+            <param>com.yourcompany.yourproject.filter.*</param>
+            <param>com.yourcompany.yourproject.utils.*</param>
+            <param>com.yourcompany.yourproject.validator.*</param>
+        </targetClasses>
+        <!-- Target test classes - UPDATE THESE TO MATCH YOUR PROJECT -->
+        <targetTests>
+            <param>com.yourcompany.yourproject.service.*Test</param>
+            <param>com.yourcompany.yourproject.mapper.*Test</param>
+            <param>com.yourcompany.yourproject.utils.*Test</param>
+        </targetTests>
+        <!-- Exclude controller tests (too slow, use Postman for API tests) -->
+        <excludedTestClasses>
+            <param>com.yourcompany.yourproject.controller.*</param>
+        </excludedTestClasses>
+        <!-- Thresholds -->
+        <mutationThreshold>60</mutationThreshold>
+        <coverageThreshold>70</coverageThreshold>
+        <!-- Use STRONGER mutators for better test quality -->
+        <mutators>
+            <mutator>STRONGER</mutator>
+        </mutators>
+        <!-- Exclude classes that don't need mutation testing -->
+        <excludedClasses>
+            <param>*DTO</param>
+            <param>*Entity</param>
+            <param>*Config</param>
+            <param>*Exception</param>
+            <param>*Application</param>
+            <param>*MapperImpl</param>
+            <param>*Constants</param>
+        </excludedClasses>
+        <!-- Exclude generated methods -->
+        <excludedMethods>
+            <param>hashCode</param>
+            <param>equals</param>
+            <param>toString</param>
+        </excludedMethods>
+        <outputFormats>
+            <outputFormat>HTML</outputFormat>
+            <outputFormat>XML</outputFormat>
+        </outputFormats>
+        <timestampedReports>false</timestampedReports>
+        <threads>4</threads>
+        <timeoutConstant>8000</timeoutConstant>
+    </configuration>
+</plugin>
+```
+
+## 5.3 Customize PIT Configuration
+
+**IMPORTANT:** Update `targetClasses` and `targetTests` based on YOUR project's package structure.
+
+1. Read your project's package structure from `src/main/java/`
+2. Replace `com.yourcompany.yourproject` with actual package path
+3. Include only business logic packages (service, mapper, utils, validator)
+4. Exclude controllers, DTOs, entities, configs
+
+---
+
+# Phase 6: Run Tests and Generate Reports (MANDATORY)
+
+**After setup is complete, you MUST run tests and generate reports.**
+
+## 6.1 Run the Complete Test Suite
+
+Execute these commands IN ORDER:
+
+```bash
+# 1. Install dependencies
+cd postman && npm ci --ignore-scripts
+
+# 2. Run local tests (this starts app, runs Newman tests, stops app)
+cd scripts && ./runners/run-tests-local.sh
+```
+
+**Wait for run-tests-local.sh to complete, then continue:**
+
+```bash
+# 3. Generate API coverage report
+./report-generators/java-api-coverage-matrix.sh
+
+# 4. Run mutation tests (unit test quality)
+./report-generators/mutation-report.sh
+```
+
+## 6.2 Review and Report Results
+
+**After tests complete, you MUST:**
+
+1. **Check test results** - Report pass/fail count from Newman output
+2. **Check API coverage** - Run `./report-generators/java-api-coverage-matrix.sh` and report coverage percentage
+3. **Identify gaps** - List any endpoints without test coverage
+4. **Report to user** - Summarize results:
+
+> **Test Results:**
+> - Postman tests: X passed, Y failed
+> - API coverage: Z% of endpoints have 2xx tests
+> - Endpoints needing tests: [list any gaps]
+>
+> **Next steps:**
+> - [Fix any failing tests]
+> - [Add tests for uncovered endpoints]
+
+## 6.3 Verification Checklist
+
+Before considering setup COMPLETE, verify:
+
+- [ ] `application-postman.properties` exists with H2 config
+- [ ] `spring.flyway.user=sa` is explicitly set
+- [ ] H2 dependency exists in `pom.xml`
+- [ ] App starts successfully with postman profile
+- [ ] Flyway migrations complete without errors
+- [ ] Health check correctly waits for app readiness
+- [ ] `./runners/run-tests-local.sh` completes successfully
+- [ ] `./report-generators/java-api-coverage-matrix.sh` runs and shows coverage
+- [ ] All Postman assertions use correct field naming
+- [ ] All ports use variables, not hardcoded values
+
+---
+
+# Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| "Cannot load driver class: org.h2.Driver" | H2 is test-scoped, not in runtime classpath | Use `mvn spring-boot:run` or `java -cp` with test dependencies |
+| "Wrong user name or password" from Flyway | Flyway inheriting MySQL credentials | Add explicit `spring.flyway.user=sa` in postman profile |
+| "Failed to find servlet [dispatcherServletRegistration]" | Spring Security on separate management port | Use main app port for health checks |
+| Assertions fail: "expected 'externalId', got 'external_id'" | Jackson configured with SNAKE_CASE | Update all assertions to use snake_case field names |
+| "connect ECONNREFUSED" during tests | Health check passed before app ready | Use HTTP code pattern matching (2xx/3xx/4xx) |
+| Health check always passes immediately | curl returns multi-char codes like "000000" | Use case statement with proper patterns |
+| `shiftleft: command not found` | CLI not installed | Run `cd <dev-tools-path> && npm link` |
+
+## Script Compatibility Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `declare -A: command not found` | macOS default bash is 3.2, needs 4+ | Use `/opt/homebrew/bin/bash` or `/usr/local/bin/bash` |
+| `grep: command not found` inside script | Script overwrote PATH variable | Never use `PATH` as variable name; use `ENDPOINT_PATH` |
+| `tr: command not found` | Same as above - PATH overwritten | Rename any variable called PATH, HOME, USER, etc. |
+
+## Assertion Mismatch Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Expected `externalId`, got `external_id` | Jackson uses SNAKE_CASE | Read actual response or check `spring.jackson.property-naming-strategy` |
+| Expected `public`, got `VISIBLE` | Wrong enum value assumed | Read the actual Enum class definition |
+| Expected array, got object | Response is wrapped | Read DTO to see wrapper structure like `{ "items": [...] }` |
+| Expected `page`, got `current_page` | Pagination fields differ | Read PaginationDetails or PageResponse DTO |
+| Expected `name`, got `display_name` | Field name differs | Read actual DTO class fields |
+
+## Classpath Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| `ClassNotFoundException: org.h2.Driver` | H2 is test-scoped | Use `mvn spring-boot:run` or `java -cp` with test classpath |
+| `ClassNotFoundException: *MapperImpl` | MapStruct not on classpath | Include `target/generated-sources/annotations` in classpath |
+| Bean creation failures | Missing test resources | Include `src/test/resources` in classpath |
+| `NoSuchBeanDefinitionException` | Profile not active | Ensure `--spring.profiles.active=postman` is passed |
+
+---
+
+# Quick Reference
+
+## Required Configuration Overrides
+
+Always include in `application-postman.properties`:
+
+```properties
+# Datasource for H2
+spring.datasource.url=jdbc:h2:mem:testdb;MODE=MySQL;...
+spring.datasource.username=sa
+spring.datasource.password=
+
+# CRITICAL: Override Flyway credentials
+spring.flyway.url=${spring.datasource.url}
+spring.flyway.user=sa
+spring.flyway.password=
+
+# H2 JSON compatibility
+spring.jpa.properties.hibernate.type.preferred_jdbc_type_for_json=VARCHAR
+```
+
+## App Startup Based on H2 Scope
+
+| H2 Scope | Startup Command |
+|----------|-----------------|
+| `test` | `mvn spring-boot:run -Dspring-boot.run.profiles=postman` |
+| `runtime` | `java -jar target/*.jar --spring.profiles.active=postman` |
+
+## JSON Field Naming
+
+| Strategy | Example Fields |
+|----------|----------------|
+| SNAKE_CASE | `external_id`, `created_at`, `total_items` |
+| CAMEL_CASE | `externalId`, `createdAt`, `totalItems` |
+
+---
+
+# Phase 7: Collection Lifecycle Scaffolding
+
+A well-structured test suite uses a **numbered lifecycle** — not one large monolithic collection. The runner must execute them in order so later collections can reference data created by earlier ones.
+
+## 7.1 Required Collection Structure
+
+```
+postman/collections/
+  01-bootstrap.json         ← Creates all prerequisite test data, sets env vars
+  02-<concern>.json         ← e.g. happy path CRUD
+  03-<concern>.json         ← e.g. validation / negative tests
+  04-<concern>.json         ← e.g. auth / 401 tests
+  ...
+  99-cleanup.json           ← Deletes everything created in bootstrap, always runs last
+```
+
+**Rules:**
+- Bootstrap (01) always runs first — creates resources and exports IDs to env vars
+- Cleanup (99) always runs last — even if mid-collections fail
+- Mid-collections are grouped by concern, not by endpoint
+- Each collection is small and focused (under ~20 requests each)
+
+## 7.2 Bootstrap Collection Template
+
+The bootstrap collection should:
+1. Create the minimum set of entities needed for all subsequent tests
+2. Store each created ID in an environment variable via `pm.environment.set()`
+3. Never assert business logic — just create data and export IDs
+
+```javascript
+// Pre-request script (bootstrap): authenticate once
+pm.environment.set("auth_token", pm.variables.get("test_token"));
+
+// Test script (after create entity):
+pm.test("Bootstrap: entity created", function () {
+    pm.response.to.have.status(201);
+    const json = pm.response.json();
+    pm.environment.set("entity_id", json.id);
+});
+```
+
+## 7.3 Environment Variable Chaining
+
+The runner script must export the working environment after each collection so subsequent collections inherit variables set by earlier ones. Check `run-tests-local.sh` (or `run-tests-staging.sh`) for this pattern:
+
+```bash
+# Each collection: export env after run, pass it to next
+newman run collections/01-bootstrap.json \
+    --environment working-env.json \
+    --export-environment working-env.json
+
+newman run collections/02-happy-path.json \
+    --environment working-env.json \
+    --export-environment working-env.json
+
+# Cleanup always runs, even if tests failed
+newman run collections/99-cleanup.json \
+    --environment working-env.json
+```
+
+## 7.4 Cleanup Collection
+
+The cleanup collection must:
+- Delete every entity created in bootstrap (use stored IDs from env vars)
+- Run unconditionally — the runner must NOT skip it on test failure
+- Assert 200/204 on each delete (silent failures leave orphaned test data)
+
+```javascript
+// Test script (cleanup item):
+pm.test("Cleanup: entity deleted", function () {
+    pm.response.to.have.status(204);
+    pm.environment.unset("entity_id");
+});
+```
+
+---
+
+# Phase 8: CI Pipeline Integration
+
+**After local tests pass, add the integration test stage to your CI pipeline.**
+
+## 8.1 Jenkinsfile Integration Test Stage
+
+Add a shift-left integration stage to your `Jenkinsfile`. This stage:
+- Runs only when triggered by a PR comment starting with `shiftleft` (or on merge to main)
+- Sets up an isolated environment (isoforge) before tests
+- Tears down isolation even on failure
+- Posts the result back as a GitHub commit status
+
+```groovy
+stage('Shift Left Integration Test') {
+    when {
+        anyOf {
+            // Run when PR comment starts with "shiftleft"
+            expression {
+                return env.CHANGE_AUTHOR_DISPLAY_NAME != null &&
+                    env.ghprbCommentBody?.startsWith("shiftleft")
+            }
+            // Always run on main branch
+            branch 'main'
+        }
+    }
+    steps {
+        script {
+            try {
+                // 1. Set up isolation environment (isoforge or equivalent)
+                // Replace with your isolation setup command
+                sh """
+                    isoforge create --service ${SERVICE_NAME} --ref ${GIT_COMMIT}
+                """
+
+                // 2. Run the integration test suite
+                sh """
+                    cd postman
+                    npm ci --ignore-scripts
+                    cd scripts
+                    ./runners/run-tests-staging.sh
+                """
+            } finally {
+                // 3. Teardown always runs (even on failure)
+                sh """
+                    isoforge destroy --service ${SERVICE_NAME} || true
+                """
+
+                // 4. Publish per-collection HTML reports
+                publishHTML(target: [
+                    allowMissing: true,
+                    alwaysLinkToLastBuild: true,
+                    keepAll: true,
+                    reportDir: 'postman/reports',
+                    reportFiles: 'consolidated-*.html',
+                    reportName: 'Integration Test Report'
+                ])
+            }
+        }
+    }
+    post {
+        always {
+            // Post commit status back to the PR
+            step([
+                $class: 'GitHubCommitStatusSetter',
+                contextSource: [$class: 'ManuallyEnteredCommitContextSource', context: 'integration-tests'],
+                statusResultSource: [$class: 'ConditionalStatusResultSource', results: [
+                    [$class: 'AnyBuildResult', message: 'Integration tests', state: 'SUCCESS']
+                ]]
+            ])
+        }
+    }
+}
+```
+
+## 8.2 Combined Quality Report Stage
+
+Add a stage that aggregates unit test results, coverage, mutation score, and API test results into one HTML report:
+
+```groovy
+stage('Quality Report') {
+    steps {
+        script {
+            sh """
+                cd postman/scripts
+                ./run-all.sh --skip-app-start
+            """
+        }
+        publishHTML(target: [
+            allowMissing: false,
+            alwaysLinkToLastBuild: true,
+            keepAll: true,
+            reportDir: 'postman/reports',
+            reportFiles: 'quality-report-*.html',
+            reportName: 'Quality Report'
+        ])
+    }
+}
+```
+
+---
+
+# Phase 9: GitHub Actions Workflows
+
+**Two GitHub Actions workflows should be added. If your repo already has them, verify they cover these behaviours.**
+
+## 9.1 Postman Format Validation Workflow
+
+Triggers when any collection or environment file changes on a PR. Catches malformed JSON before CI fails.
+
+Create `.github/workflows/postman-format-check.yml`:
+
+```yaml
+name: Postman Format Check
+
+on:
+  pull_request:
+    paths:
+      - 'postman/**'
+
+jobs:
+  format-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install dependencies
+        working-directory: postman
+        run: npm ci --ignore-scripts
+
+      - name: Check collection JSON format
+        working-directory: postman
+        run: npm run format:check
+
+      - name: Validate collection schema
+        working-directory: postman
+        run: |
+          # Check that all collection files have required Postman schema fields
+          for f in collections/*.json; do
+            jq -e '.info.schema' "$f" > /dev/null || \
+              (echo "FAIL: $f missing .info.schema" && exit 1)
+          done
+          echo "All collections have valid schema"
+```
+
+Add to `postman/package.json`:
+
+```json
+{
+  "scripts": {
+    "format:check": "prettier --check 'collections/**/*.json' 'environments/**/*.json'",
+    "format:fix": "prettier --write 'collections/**/*.json' 'environments/**/*.json'"
+  },
+  "devDependencies": {
+    "prettier": "^3.0.0"
+  }
+}
+```
+
+## 9.2 Repository Authorization Workflow
+
+Prevents the pipeline from running if the repo is forked to an unauthorised account.
+
+Create `.github/workflows/security_verification.yml`:
+
+```yaml
+name: Security Verification
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  verify-repo-authorization:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify repository owner
+        run: |
+          OWNER="${{ github.repository_owner }}"
+          ALLOWED_ORGS="YOUR_ORG_NAME"   # Replace with your organisation(s)
+
+          if echo "$ALLOWED_ORGS" | grep -qw "$OWNER"; then
+            echo "Repository owner '$OWNER' is authorized."
+          else
+            echo "ERROR: Repository owner '$OWNER' is not in the authorized list."
+            echo "This workflow only runs in authorized organizations."
+            exit 1
+          fi
+```
+
+**IMPORTANT:** Replace `YOUR_ORG_NAME` with your actual GitHub organisation name(s).
+
+---
+
+# Phase 10: Isoforge / Isolation Environment Setup
+
+**If your service depends on other microservices, tests must run against an isolated stack — not shared staging data.**
+
+## 10.1 What Isolation Provides
+
+An isolation environment:
+- Routes test traffic to a dedicated instance of your service (and its dependencies)
+- Prevents tests from reading or writing data that other developers or users are touching
+- Allows teardown to clean up all test data automatically
+
+## 10.2 Check What Isolation Mechanism Is Available
+
+| Mechanism | When to use |
+|-----------|-------------|
+| isoforge | Freshworks-internal isolation platform — preferred if available |
+| docker-compose | Good for local development, harder to maintain in CI |
+| Testcontainers (Java) | In-process, no network isolation, good for unit/integration |
+| Feature flags | Route by header/flag — least isolation, easiest to set up |
+
+## 10.3 isoforge Integration Pattern
+
+If isoforge is available in your organisation:
+
+```bash
+# In run-tests-staging.sh: set isolation identifier before running Newman
+ISO_ID=$(isoforge create --service ${SERVICE_NAME} --branch ${BRANCH_NAME})
+export ISO_HEADER_VALUE="$ISO_ID"
+
+# Pass the isolation header to Newman via environment variable
+newman run collections/01-bootstrap.json \
+    --environment working-env.json \
+    --env-var "iso_header=${ISO_HEADER_VALUE}" \
+    --export-environment working-env.json
+
+# In each Postman request, add the isolation header:
+# Header: X-Isoforge-Id: {{iso_header}}
+```
+
+Teardown (always run, even on failure):
+
+```bash
+isoforge destroy --service ${SERVICE_NAME} || true
+```
+
+## 10.4 Postman Request Header for Isolation
+
+In each request that needs isolation routing, add:
+
+```json
+{
+  "key": "X-Isoforge-Id",
+  "value": "{{iso_header}}",
+  "description": "Routes request to isolated service instance"
+}
+```
+
+Or add it as a pre-request script in the collection-level scripts to apply to all requests automatically.
+
+---
+
+## Validation
+
+After completing setup, run the validation skill to confirm all checks pass:
+
+```
+/review-test-suite
+```
+
+This checks all 20 quality gates: unit tests, coverage, mutation testing, collection lifecycle, secret security, CI pipeline, GitHub Actions, and developer experience.