⬅️ Back to Architecture Index

Testing Strategy & Patterns

Overview

Smart Supply Pro implements a comprehensive, layered testing strategy using industry-standard tools and patterns. The test suite covers:

  • Unit Tests - Individual components in isolation (mappers, validators, services, repositories, enum helpers)
  • Integration Tests - Component interaction with databases and frameworks
  • Security Tests - OAuth2, authorization, RBAC, and API endpoints
  • Analytics Tests - Complex queries, converters, and reporting
  • Contract Tests - REST API endpoints, HTTP status codes, response formats

The project uses: - JUnit 5 - Test framework with parameterized tests and display names - Mockito - Mocking and behavior verification - Spring Test - Integration testing with @SpringBootTest, @DataJpaTest, @WebMvcTest - TestContainers - Database containerization for realistic testing - H2 Database - In-memory database for fast unit tests - JaCoCo - Code coverage reporting

Testing Pyramid

graph TB E2E["🏔️ E2E / Integration Tests
(~10%)
@SpringBootTest
Full context, real DB/cache"] Integration["📊 Integration Tests
(~25%)
@DataJpaTest, @WebMvcTest
Slice testing with mocks"] Unit["📝 Unit Tests
(~65%)
@ExtendWith(MockitoExtension)
Fast, isolated components"] Unit --> Integration Integration --> E2E style Unit fill:#c8e6c9 style Integration fill:#fff9c4 style E2E fill:#ffcdd2

Test Layers

Layer 1: Unit Tests (65% of suite)

Scope: Test individual classes in isolation with mocked dependencies

Tools: - JUnit 5 with @Test and @ParameterizedTest - Mockito with @ExtendWith(MockitoExtension.class) - @Mock for dependencies, @InjectMocks for target class

Examples: - Validator tests (InventoryItemValidatorTest, InventoryItemValidatorBusinessRulesTest, SupplierValidatorTest, SupplierValidatorUniquenessAndDeletionEdgeCasesTest, StockHistoryValidationTest, StockHistoryValidatorPriceChangeAndEnumValidationTest, InventoryItemSecurityValidatorTest) - Service method tests with mocked repositories - Converter tests (AnalyticsServiceImplConverterTest, AnalyticsConverterHelperTest) - Exception tests (e.g., GlobalExceptionHandlerTest, BusinessExceptionHandlerTest)

Characteristics: - ✅ Fast (milliseconds per test) - ✅ No database or Spring context needed - ✅ Easy to understand and maintain - ✅ Fail quickly for logic errors

@ExtendWith(MockitoExtension.class)
class InventoryItemValidatorTest {
    
    @Mock private InventoryItemRepository repo;
    
    @Test
    void validateDuplicate_NameAndPriceExist_ThrowsConflict() {
        when(repo.findByNameIgnoreCase("Widget"))
            .thenReturn(List.of(existingItem));
        
        assertThrows(DuplicateResourceException.class,
            () -> InventoryItemValidator.validateInventoryItemNotExists(
                "Widget", price, repo));
    }
}

Layer 2: Integration Tests (25% of suite)

Scope: Test component interactions with real infrastructure (DB, frameworks)

Tools: - @DataJpaTest - JPA repository testing with H2 - @WebMvcTest - Controller testing without full context - @SpringBootTest - Full application context for complex scenarios - MockMvc for HTTP testing - @MockitoBean for selective mocking

Examples: - Repository tests (SupplierRepositoryTest, InventoryItemRepositoryTest) - Controller tests (SupplierControllerTest) - Service integration tests

Characteristics: - ⏱️ Slower (100ms - 1s per test) - 📦 Uses real H2 database or TestContainers - 🔗 Tests component interaction - 🛡️ Validates persistence and HTTP contracts

@DataJpaTest
@AutoConfigureTestDatabase(replace = ANY)  // force H2
class SupplierRepositoryTest {
    
    @Autowired private SupplierRepository repo;
    
    @Test
    void findByNameIgnoreCase_caseInsensitive() {
        repo.save(Supplier.builder().name("Acme GmbH").build());
        
        assertTrue(repo.findByNameIgnoreCase("acme gmbh").isPresent());
    }
}

Layer 3: End-to-End Tests (10% of suite)

Scope: Full application in realistic conditions

Tools: - @SpringBootTest with real security - TestContainers for Oracle or real services - MockMvc or RestTemplate for HTTP - Full authentication/authorization

Examples: - Security smoke tests (SecuritySmokeTest) - Demo mode tests (DemoReadonlySecurityTest) - Full workflow tests

Characteristics: - 🐢 Slowest (seconds per test) - 🔐 Tests with real security context - 🌍 Validates end-to-end workflows - 🎯 High confidence, lower coverage

Test Organization

Directory Structure

src/test/java/com/smartsupplypro/inventory/
├── InventoryServiceApplicationTest.java          (Context load smoke test)
├── InventoryServiceApplicationMainTest.java      (Entry-point coverage: invokes main() and closes immediately)
│
├── enums/
│   └── StockChangeReasonTest.java                (Unit: enum helper methods + parsing)
│
├── mapper/
│   ├── InventoryItemMapperTest.java              (Unit: entity/DTO mapping + computed fields)
│   ├── StockHistoryMapperTest.java               (Unit: audit mapping + enum/string conversion)
│   └── SupplierMapperTest.java                   (Unit: sanitization + audit field handling)
│
├── model/
│   ├── InventoryItemTest.java                    (Unit: entity @PrePersist defaults + supplierId resolution)
│   └── StockHistoryTest.java                     (Unit: entity @PrePersist timestamp defaulting)
│
├── validation/
│   ├── InventoryItemValidatorTest.java           (Unit: 159 lines)
│   ├── InventoryItemValidatorBusinessRulesTest.java (Unit: incremental business rule branches)
│   ├── InventoryItemSecurityValidatorTest.java    (Unit: RBAC/field-level update guards)
│   ├── SupplierValidatorTest.java                (Unit: ~100 lines)
│   ├── SupplierValidatorUniquenessAndDeletionEdgeCasesTest.java (Unit: uniqueness + deletion edge cases)
│   ├── StockHistoryValidationTest.java           (Unit: ~100 lines)
│   └── StockHistoryValidatorPriceChangeAndEnumValidationTest.java (Unit: PRICE_CHANGE + enum whitelist)
│
├── service/
│   ├── SecurityServiceTest.java                  (Unit: demo-mode principal checks)
│   ├── CustomUserServiceTestSupport.java         (Shared fixture: upstream principals + service factories)
│   ├── CustomUserServiceNormalizationTest.java   (Unit: allow-list parsing + role authority normalization)
│   ├── CustomOAuth2UserServiceTest.java          (Unit: OAuth2 provisioning + error handling)
│   ├── CustomOAuth2UserServiceRoleHealingTest.java (Unit: role healing + idempotency)
│   ├── CustomOidcUserServiceTest.java            (Unit: OIDC provisioning + error handling)
│   ├── CustomOidcUserServiceRoleHealingTest.java (Unit: role healing + idempotency)
│   ├── inventoryitem/
│   │   ├── InventoryItemServiceSaveHappyPathTest.java (Unit: save happy paths + audit logging)
│   │   ├── InventoryItemServiceSaveValidationTest.java (Unit: save validation guards)
│   │   └── InventoryItemServiceSaveTestBase.java      (Shared fixture)
│   ├── supplier/
│   │   ├── SupplierServiceCreateTest.java            (Unit: create flows)
│   │   ├── SupplierServiceUpdateTest.java            (Unit: update flows)
│   │   ├── SupplierServiceDeleteTest.java            (Unit: delete flows)
│   │   ├── SupplierServiceReadCountTest.java         (Unit: read/query/count flows)
│   │   └── SupplierServiceTestBase.java              (Shared fixture)
│   ├── stockhistory/
│   │   ├── StockHistoryServiceLogTest.java           (Unit: audit logging + validation)
│   │   ├── StockHistoryServiceDeleteTest.java        (Unit: delete audit logging)
│   │   ├── StockHistoryServiceReadTest.java          (Unit: stock history queries)
│   │   ├── StockHistoryServiceSaveTest.java          (Unit: service-level save)
│   │   └── StockHistoryServiceTestBase.java          (Shared fixture)
│   └── impl/
│       ├── analytics/
│       │   ├── AnalyticsServiceImplTest.java
│       │   ├── AnalyticsServiceImplConverterTest.java (Unit: 150 lines)
│       │   ├── AnalyticsConverterHelperTest.java       (Unit: direct helper coverage)
│       │   ├── AnalyticsServiceImplQueryTest.java
│       │   ├── AnalyticsServiceImplValidationTest.java
│       │   ├── AnalyticsServiceImplWindowTest.java
│       │   ├── AnalyticsServiceImplWacTest.java
│       │   └── FinancialAnalyticsServiceWacBucketsTest.java (Unit: WAC branch coverage suite)
│       ├── inventory/
│       │   ├── InventoryItemValidationHelperTest.java  (Unit: server-side validation + field population)
│       │   └── InventoryItemAuditHelperTest.java       (Unit: stock-history audit logging)
│       └── inventoryitem/
│           ├── InventoryItemServiceImplSaveTest.java (Unit: 120 lines)
│           ├── InventoryItemServiceImplSearchTest.java
│           ├── InventoryItemServiceImplUpdateTest.java
│           ├── InventoryItemServiceImplDeleteTest.java
│           ├── InventoryItemServiceImplReadAndAdjustmentsTest.java
│           └── InventoryItemServiceImplTestHelper.java (Shared utilities)
│
├── repository/
│   ├── SupplierRepositoryTest.java               (Integration: 126 lines)
│   ├── InventoryItemRepositoryTest.java
│   ├── AppUserRepositoryTest.java
│   ├── StockHistoryRepositoryFilteringTest.java
│   ├── StockHistoryRepositoryAnalyticsTest.java
│   ├── InventoryItemRepositoryAnalyticsTest.java
│   └── custom/
│       ├── StockHistoryCustomRepositoryImplTest.java
│       ├── StockMetricsRepositoryImplTest.java
│       ├── StockDetailQueryRepositoryImplTest.java
│       ├── StockTrendAnalyticsRepositoryImplH2Test.java
│       ├── StockTrendAnalyticsRepositoryImplOracleDialectSelectionTest.java
│       └── util/
│           └── DatabaseDialectDetectorTest.java   (Unit: profile-based dialect detection branches)
│
├── controller/
│   ├── supplier/
│   │   └── SupplierControllerTest.java           (Integration: 404 lines)
│   ├── auth/
│   │   ├── AuthControllerTest.java               (Integration: @WebMvcTest /api/me)
│   │   ├── AuthControllerAuthoritiesTest.java    (Integration: @WebMvcTest /api/me/authorities)
│   │   ├── AuthControllerLogoutTest.java         (Integration: @WebMvcTest logout contract)
│   │   └── AuthControllerBranchUnitTest.java     (Unit: guard branches blocked by security filters)
│   ├── health/
│   │   ├── HealthCheckControllerHealthEndpointTest.java (Unit: /api/health response contract)
│   │   └── HealthCheckControllerDbEndpointTest.java     (Unit: /api/health/db response contract)
│   ├── inventoryitem/
│   ├── stockhistory/
│   │   ├── StockHistoryControllerEndpointsTest.java (Integration: @WebMvcTest endpoint contract)
│   │   └── StockHistoryControllerSearchTest.java    (Integration: @WebMvcTest search validation + paging)
│   ├── analytics/
│   │   ├── AnalyticsControllerBasicTest.java      (Integration: @WebMvcTest stock dashboard endpoints)
│   │   ├── AnalyticsControllerFilteringTest.java  (Integration: @WebMvcTest filtering/search endpoints)
│   │   ├── AnalyticsControllerFinancialTest.java  (Integration: @WebMvcTest financial analytics endpoints)
│   │   ├── AnalyticsControllerValidationHelperTest.java (Unit: request parameter validation rules)
│   │   └── AnalyticsDashboardHelperTest.java      (Unit: dashboard aggregation + supplier conditional branches)
│   └── security/
│
├── exception/
│   ├── InvalidRequestExceptionTest.java          (Unit: exception DTO/context branches)
│   ├── DuplicateResourceExceptionTest.java       (Unit: message/context branches)
│   ├── GlobalExceptionHandlerTest.java           (Unit: handler branch coverage)
│   ├── BusinessExceptionHandlerTest.java         (Unit: handler branch coverage)
│   └── ErrorResponseBuilderTest.java             (Unit: ErrorResponse.Builder fallback + generation branches)
│
├── security/
│   ├── SecuritySmokeTest.java                    (Integration: 297 lines)
│   ├── oauth2login/
│   │   ├── OAuth2LoginSuccessHandlerTestSupport.java
│   │   ├── OAuth2LoginSuccessHandlerProvisioningTest.java
│   │   ├── OAuth2LoginSuccessHandlerReturnCookieTest.java
│   │   └── OAuth2LoginSuccessHandlerCookieHeaderBuilderTest.java
│   ├── ApiEntryPointBehaviourTest.java
│   ├── DemoReadonlySecurityTest.java
│   ├── SecurityConfigAuthorizationRulesTest.java  (Integration: @WebMvcTest real authZ rules)
│   ├── SecurityConfigDemoReadonlyAuthorizationTest.java (Integration: demo-readonly branch)
│   ├── oauth2/
│   │   ├── CookieOAuth2AuthorizationRequestRepositoryTestSupport.java
│   │   ├── CookieOAuth2AuthorizationRequestRepositoryTest.java
│   │   ├── CookieOAuth2AuthorizationRequestRepositoryLoadTest.java
│   │   ├── CookieOAuth2AuthorizationRequestRepositorySaveTest.java
│   │   ├── CookieOAuth2AuthorizationRequestRepositorySerializationTest.java
│   │   └── CookieOAuth2AuthorizationRequestRepositorySameSiteTest.java
│   ├── TestApiStubController.java                (Probe endpoints)
│   └── AdminStubController.java
│
└── config/
    ├── TestSecurityConfig.java                    (Helper: simplified security for controller slices)
    ├── SecurityConfigUnitTest.java                (Unit: CORS/cookie/OAuth failure handler contracts)
    ├── SecurityFilterHelperTest.java              (Unit: API request classification filter)
    └── SecurityEntryPointHelperTest.java          (Unit: API 401 JSON vs web redirect entry points)

src/test/resources/
├── logback-test.xml                              (Test logging: reduce console noise)
└── testcontainers.properties                     (TestContainers config)

Test Coverage

Coverage Summary

Note: entity lifecycle hooks (for example @PrePersist) should be covered via pure unit tests under src/test/java/com/smartsupplypro/inventory/model/.

┌─────────────────────────────────────────────────────┐
│ Test Coverage (via JaCoCo Maven plugin)             │
├─────────────────────────────────────────────────────┤
│ Target: >80% code coverage                          │
│ Report: target/site/jacoco/index.html              │
│ Execution: mvn clean verify                         │
├─────────────────────────────────────────────────────┤
│ Coverage by Layer:                                  │
│ - Validation:    95%+ (critical business logic)    │
│ - Service:       85%+ (core operations)            │
│ - Repository:    80%+ (custom queries)             │
│ - Controller:    75%+ (HTTP endpoints)             │
│ - Security:      85%+ (auth flows)                 │
│ - Config:        60%+ (framework wiring)           │
└─────────────────────────────────────────────────────┘

JaCoCo Configuration

<!-- pom.xml -->
<plugin>
    <groupId>org.jacoco</groupId>
    <artifactId>jacoco-maven-plugin</artifactId>
    <version>0.8.12</version>
    <executions>
        <execution>
            <goals><goal>prepare-agent</goal></goals>
        </execution>
        <execution>
            <id>report</id>
            <phase>verify</phase>
            <goals><goal>report</goal></goals>
        </execution>
    </executions>
</plugin>

Test Dependencies

Testing Stack (from pom.xml)

<!-- JUnit 5 & Mockito (via spring-boot-starter-test) -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-test</artifactId>
    <scope>test</scope>
</dependency>
<!-- Includes: JUnit 5, Mockito, AssertJ, Hamcrest, JSONassert -->

<!-- Spring Test Utilities -->
<dependency>
    <groupId>org.springframework.security</groupId>
    <artifactId>spring-security-test</artifactId>
    <scope>test</scope>
</dependency>

<!-- TestContainers for Database Isolation -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-testcontainers</artifactId>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>oracle-free</artifactId>
    <scope>test</scope>
</dependency>

<!-- H2 for Unit Tests (in-memory, fast) -->
<dependency>
    <groupId>com.h2database</groupId>
    <artifactId>h2</artifactId>
    <scope>test</scope>
</dependency>

Running Tests

Maven Commands

# Run all tests
mvn test

# Run tests with coverage report
mvn clean verify

# Run specific test class
mvn test -Dtest=SupplierRepositoryTest

# Run tests matching pattern
# Note: validator-related tests include both *Validator*Test and *Validation*Test suites.
mvn test -Dtest=*Validator*Test,*Validation*Test

# Run with detailed output
mvn test -X

# Skip tests during build
mvn clean package -DskipTests

IDE Integration

IntelliJ IDEA: - Right-click test class → Run ‘TestClassName’ - Right-click test method → Run ‘methodName()’ - Coverage: Run → Run with Coverage

VS Code (with Extension Pack for Java): - CodeLens link above test methods - Click “Run Test” or “Debug Test”

Test Profiles

test Profile (application-test.yml)

  • Uses H2 in-memory database (Oracle compatibility mode)
  • Disables Testcontainers checks
  • Configures test-specific properties

Rationale: H2 is fast and reliable for repository and MVC slice tests, and it works in any CI environment. Running against the real Oracle Free Tier database in CI is intentionally avoided because:

  • Access typically requires an Oracle Wallet on the runner and correct client configuration.
  • Oracle Free Tier commonly enforces IP allowlisting; GitHub-hosted runners use dynamic egress IPs, so you cannot reliably pre-allowlist them without a dedicated VM, self-hosted runner, or tunneling.

If a test must validate Oracle-specific behavior, prefer: - TestContainers (local/dev environments with Docker), or - A controlled CI environment with a stable outbound IP (self-hosted runner/VM) where allowlisting is feasible.

For manual testing against Oracle Free Tier from a developer machine, use the opt-in oracle-it profile (wallet-based connectivity). It is intentionally disabled by default and only activates when you explicitly set ENABLE_WALLET_TEST=true for InventoryServiceApplicationTest.

# Spring profile for testing
spring.profiles.active=test

# H2 embedded database (Oracle mode)
spring.datasource.url=jdbc:h2:mem:testdb;MODE=Oracle
spring.jpa.database-platform=org.hibernate.dialect.H2Dialect

# Disable unnecessary services
spring.h2.console.enabled=false
management.endpoints.web.exposure.exclude=*

Test Fixtures & Helpers

Test Helper Classes

Class Purpose
InventoryItemServiceImplTestHelper OAuth2 authentication setup, test data builders
TestSecurityConfig Mock OAuth2 config for @WebMvcTest
TestApiStubController Probe endpoints for security testing
AdminStubController Admin-protected endpoints for RBAC tests

Common Patterns

// 1. Authentication setup in service tests
@BeforeEach
void setup() {
    InventoryItemServiceImplTestHelper.authenticateAsOAuth2("admin", "ADMIN");
}

// 2. Build test DTOs
private InventoryItemDTO validDTO() {
    return InventoryItemDTO.builder()
        .name("Widget")
        .quantity(100)
        .price(BigDecimal.TEN)
        .supplierId("SUPP-001")
        .build();
}

// 3. Controller testing with MockMvc
mockMvc.perform(post("/api/suppliers")
    .contentType(MediaType.APPLICATION_JSON)
    .content(objectMapper.writeValueAsString(dto))
    .with(user("admin").roles("ADMIN")))
    .andExpect(status().isCreated())
    .andExpect(jsonPath("$.id").exists());

TestContainers Configuration

testcontainers.properties

Location: src/test/resources/testcontainers.properties

Purpose: Configures TestContainers behavior during test execution.

Content:

checks.enabled=false

What This Does:

Property Value Meaning
checks.enabled false Disables startup checks and health verification for TestContainers

Why Disable Checks?

TestContainers normally performs startup verification checks before running tests: - Validates container health and readiness - Checks database connectivity - Verifies all dependencies are ready

Performance Impact: - ✅ Faster test startup - Skips checks, reduces ~2-5 second overhead per test run - ✅ Cleaner test output - No diagnostic logs from health checks - ⚠️ Trade-off - Fewer diagnostics if container fails to start (rare in practice)

How Testing Configuration Works:

┌─────────────────────────────────────────────┐
│ Test Execution Flow                         │
├─────────────────────────────────────────────┤
│ 1. Maven finds @ActiveProfiles("test")     │
│ 2. Loads application-test.yml              │
│ 3. Sees: spring.datasource.url = H2 mem:   │
│ 4. Creates H2 in-memory database           │
│ 5. Reads testcontainers.properties         │
│ 6. checks.enabled=false → Skip health verify│
│ 7. Starts test execution                   │
└─────────────────────────────────────────────┘

Key Point: testcontainers.properties is a supplement to application-test.yml, not a replacement. The actual database configuration (H2, Oracle mode, connectivity) comes from application-test.yml. This file only tunes TestContainers behavior.

When to Modify testcontainers.properties

Rarely needed, but if you encounter TestContainers startup issues:

# Enable debugging if containers fail to start
checks.enabled=true

# For Oracle TestContainers specifically
testcontainers.docker.client.strategy=org.testcontainers.dockerclient.UnixSocketClientProviderStrategy

Default Configuration Sufficient for: - ✅ Unit tests with H2 (no containers used) - ✅ Integration tests with mocked services - ✅ CI/CD pipelines with standard Docker setup

Test Fixtures & Data Builders

Test Helper Classes

Class Purpose Location
InventoryItemServiceImplTestHelper OAuth2 authentication setup, principal creation src/test/.../service/impl/
TestSecurityConfig Mock OAuth2 config for @WebMvcTest src/test/.../config/
TestApiStubController Probe endpoints for security testing src/test/.../security/
AdminStubController Admin-protected endpoints for RBAC tests src/test/.../security/

See: Test Fixtures & Data Builders for detailed documentation on: - OAuth2 authentication helper patterns - Test data builders and factories - Test isolation and cleanup strategies - Best practices for reusable test code

Quick Example

// Authenticate test with OAuth2 principal
@Test
void testAdminCanSave() {
    InventoryItemServiceImplTestHelper.authenticateAsOAuth2("admin@example.com", "ADMIN");
    
    InventoryItem item = InventoryItem.builder()
            .id("item-1")
            .name("Widget")
            .price(BigDecimal.TEN)
            .quantity(100)
            .build();
    
    InventoryItem saved = service.save(item);
    assertNotNull(saved.getId());
}

Quick Navigation

⬅️ Back to Architecture Index