effigenix/backend/TEST_FILES_INDEX.md

# Unit Test Files Index

## Complete List of Test Files Created

### Domain Layer Tests

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/domain/usermanagement/UserIdTest.java`
- **Class Under Test**: `UserId`
- **Type**: Value Object Test
- **Test Count**: 11 test cases
- **Key Tests**:
  - Valid ID creation
  - Null/empty/blank string rejection
  - Unique ID generation via `UserId.generate()`
  - Static factory method `UserId.of(String value)`
  - Record immutability
  - Equality and hash code consistency
  - Parameterized tests for invalid inputs

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/domain/usermanagement/RoleIdTest.java`
- **Class Under Test**: `RoleId`
- **Type**: Value Object Test
- **Test Count**: 11 test cases
- **Key Tests**:
  - Similar to UserIdTest but for Role identifiers
  - UUID generation uniqueness
  - Factory methods testing
  - Immutability verification

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/domain/usermanagement/PasswordHashTest.java`
- **Class Under Test**: `PasswordHash`
- **Type**: Value Object Test (Cryptographic)
- **Test Count**: 16 test cases
- **Key Tests**:
  - BCrypt hash creation acceptance ($2a$, $2b$, $2y$ versions)
  - 60-character length validation
  - Invalid format rejection (non-BCrypt, wrong length)
  - Static factory `PasswordHash.of(String bcryptHash)`
  - Immutability and equality
  - Comprehensive format validation with parameterized tests

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/domain/usermanagement/UserTest.java`
- **Class Under Test**: `User` (Entity)
- **Type**: Entity Business Logic Test
- **Test Count**: 35+ test cases
- **Key Tests**:
  - **Construction & Validation** (5+ tests)
    - Valid user creation
    - Null validation for UserId, username, email, passwordHash, status
    - Email format validation
    - Default createdAt timestamp
    - Factory method `User.create()`
  - **Status Management** (8+ tests)
    - `lock()` / `unlock()` state transitions
    - `activate()` / `deactivate()` state transitions
    - Status verification methods: `isActive()`, `isLocked()`
  - **Password Management** (3+ tests)
    - `changePassword()` with hash replacement
    - Null hash rejection
  - **Email & Branch Updates** (3+ tests)
    - `updateEmail()` with validation
    - `updateBranch()` assignment
  - **Role Management** (6+ tests)
    - `assignRole()` / `removeRole()`
    - Null role rejection
    - Unmodifiable role set
  - **Permission Logic** (4+ tests)
    - `getAllPermissions()` aggregates from all roles
    - `hasPermission()` checks existence
    - Empty set for users without roles
  - **Login Tracking** (1+ tests)
    - `updateLastLogin()` timestamp
  - **Equality & Immutability** (4+ tests)
    - ID-based equality
    - Unmodifiable collections

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/domain/usermanagement/RoleTest.java`
- **Class Under Test**: `Role` (Entity)
- **Type**: Entity Business Logic Test
- **Test Count**: 25+ test cases
- **Key Tests**:
  - **Construction & Validation** (4+ tests)
    - Valid role creation
    - Null RoleId/RoleName rejection
    - Null permissions defaulting to empty set
  - **Permission Management** (8+ tests)
    - `addPermission()` / `removePermission()`
    - Duplicate permission handling
    - Null permission rejection
    - Multiple permission operations
    - `hasPermission()` verification
  - **Description Management** (2+ tests)
    - `updateDescription()` updates
    - Null description handling
  - **Equality & Immutability** (4+ tests)
    - ID-based equality
    - Unmodifiable permission set
    - Hash code consistency
  - **Multi-Role Support** (3+ tests)
    - Different RoleNames support
    - Different permission sets
    - Large permission sets

---

### Application Layer Tests

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/application/usermanagement/CreateUserTest.java`
- **Use Case Under Test**: `CreateUser`
- **Type**: Application Layer / Use Case Test
- **Test Count**: 16 test cases
- **Mocked Dependencies**: UserRepository, RoleRepository, PasswordHasher, AuditLogger
- **Key Tests**:
  - **Success Path** (3+ tests)
    - Valid user creation with all checks
    - Password hashing via PasswordHasher
    - Role loading and assignment
    - UserDTO returned correctly
  - **Password Validation** (1+ tests)
    - Weak password rejection
  - **Uniqueness Checks** (2+ tests)
    - Duplicate username detection
    - Duplicate email detection
    - Validation ordering verification
  - **Role Loading** (2+ tests)
    - Multiple role loading
    - Role not found exception
  - **User Status** (1+ tests)
    - New users created as ACTIVE
  - **Persistence & Audit** (3+ tests)
    - Repository save verification
    - AuditEvent.USER_CREATED logging
    - Audit contains correct ActorId
  - **Error Handling** (3+ tests)
    - Result<Error, DTO> pattern verification
    - No persistence on failure
    - No audit on failure

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/application/usermanagement/AuthenticateUserTest.java`
- **Use Case Under Test**: `AuthenticateUser`
- **Type**: Application Layer / Use Case Test
- **Test Count**: 15 test cases
- **Mocked Dependencies**: UserRepository, PasswordHasher, SessionManager, AuditLogger
- **Key Tests**:
  - **Success Path** (2+ tests)
    - Credentials verified
    - SessionToken created
    - Last login updated
    - AuditEvent.LOGIN_SUCCESS logged
  - **Username Validation** (1+ tests)
    - User not found error
  - **Status Checks** (3+ tests)
    - LOCKED status blocks login
    - INACTIVE status blocks login
    - ACTIVE status allows login
  - **Password Verification** (2+ tests)
    - Incorrect password failure
    - Correct password success
  - **Session Management** (2+ tests)
    - SessionManager invoked
    - SessionToken returned
  - **Last Login Update** (1+ tests)
    - Timestamp set and persisted
  - **Audit Trail** (3+ tests)
    - Success and failure logging
    - Correct context and ActorId

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/application/usermanagement/ChangePasswordTest.java`
- **Use Case Under Test**: `ChangePassword`
- **Type**: Application Layer / Use Case Test
- **Test Count**: 14 test cases
- **Mocked Dependencies**: UserRepository, PasswordHasher, AuditLogger
- **Key Tests**:
  - **Success Path** (1+ tests)
    - Password changed successfully
  - **User Lookup** (1+ tests)
    - User not found error
  - **Current Password Verification** (2+ tests)
    - Incorrect current password rejection
    - Verification ordering
  - **New Password Validation** (2+ tests)
    - Weak password rejection
    - Validation ordering
  - **Password Hashing** (1+ tests)
    - New hash created and assigned
  - **Verification Ordering** (1+ tests)
    - Current password verified before new password validated
  - **Persistence** (1+ tests)
    - Updated user saved
  - **Audit Trail** (4+ tests)
    - Success logging
    - Failure logging with context

---

### Infrastructure Layer Tests

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/infrastructure/security/BCryptPasswordHasherTest.java`
- **Class Under Test**: `BCryptPasswordHasher`
- **Type**: Implementation / Cryptography Test
- **Test Count**: 26+ test cases
- **Key Tests**:
  - **Hashing** (6+ tests)
    - Valid password hashing
    - BCrypt format validation
    - Hash uniqueness (salt randomness)
    - Null/empty/blank rejection
    - Weak password rejection
  - **Verification** (5+ tests)
    - Correct password verification
    - Incorrect password failure
    - Null safety (returns false)
    - Malformed hash handling
  - **Password Validation** (10+ tests)
    - Minimum 8 characters
    - Uppercase letter requirement
    - Lowercase letter requirement
    - Digit requirement
    - Special character requirement
    - All requirements together
    - Long password acceptance
    - Null password handling
    - Similar password rejection
  - **Security Properties** (3+ tests)
    - Strength 12 format verification
    - Constant-time comparison (timing attack resistance)
    - Error graceful handling

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/infrastructure/persistence/usermanagement/mapper/UserMapperTest.java`
- **Class Under Test**: `UserMapper`
- **Type**: Hexagonal Port / Mapper Test
- **Test Count**: 16 test cases
- **Key Tests**:
  - **Domain → JPA Entity** (4+ tests)
    - All fields mapped correctly
    - Value object extraction
    - Timestamps preserved
    - Status preserved
  - **JPA Entity → Domain** (4+ tests)
    - All fields mapped correctly
    - Value object creation
    - Timestamps preserved
    - Status preserved
  - **Null Handling** (3+ tests)
    - Null user → null entity
    - Null entity → null domain
    - Null role set → empty set
  - **Bidirectional Mapping** (2+ tests)
    - User → Entity → User preservation
    - Field consistency round-trip
  - **Collection Independence** (2+ tests)
    - Set copied (not referenced)
    - Role set independence
  - **Status Mapping** (1+ tests)
    - All user statuses preserved

#### `/home/sebi/git/effigenix/src/test/java/com/effigenix/infrastructure/persistence/usermanagement/mapper/RoleMapperTest.java`
- **Class Under Test**: `RoleMapper`
- **Type**: Hexagonal Port / Mapper Test
- **Test Count**: 16 test cases
- **Key Tests**:
  - **Domain → JPA Entity** (4+ tests)
    - All fields mapped
    - Value object extraction
    - Description preserved
  - **JPA Entity → Domain** (4+ tests)
    - All fields mapped
    - Value object creation
    - Description preserved
  - **Null Handling** (3+ tests)
    - Null role → null entity
    - Null entity → null domain
    - Null permissions → empty set
  - **Bidirectional Mapping** (2+ tests)
    - Role → Entity → Role preservation
    - Full round-trip consistency
  - **Collection Independence** (2+ tests)
    - Permission set copied
    - No shared references
  - **Role Name Mapping** (1+ tests)
    - All RoleNames preserved

---

## Test Statistics by File

| File | Tests | LOC | Focus |
|------|-------|-----|-------|
| UserIdTest.java | 11 | 125 | Value object |
| RoleIdTest.java | 11 | 112 | Value object |
| PasswordHashTest.java | 16 | 232 | Cryptographic validation |
| UserTest.java | 35+ | 520 | Entity logic |
| RoleTest.java | 25+ | 420 | Entity logic |
| CreateUserTest.java | 16 | 285 | Use case flow |
| AuthenticateUserTest.java | 15 | 310 | Authentication |
| ChangePasswordTest.java | 14 | 280 | Password change |
| BCryptPasswordHasherTest.java | 26+ | 395 | Cryptography |
| UserMapperTest.java | 16 | 315 | Entity mapping |
| RoleMapperTest.java | 16 | 315 | Entity mapping |
| **TOTAL** | **170+** | **3,309** | **Full coverage** |

---

## How to Find Tests

### By Component
- **UserId**: `UserIdTest.java`
- **RoleId**: `RoleIdTest.java`
- **PasswordHash**: `PasswordHashTest.java`
- **User Entity**: `UserTest.java`
- **Role Entity**: `RoleTest.java`
- **CreateUser Use Case**: `CreateUserTest.java`
- **AuthenticateUser Use Case**: `AuthenticateUserTest.java`
- **ChangePassword Use Case**: `ChangePasswordTest.java`
- **BCryptPasswordHasher**: `BCryptPasswordHasherTest.java`
- **UserMapper**: `UserMapperTest.java`
- **RoleMapper**: `RoleMapperTest.java`

### By Layer
- **Domain Tests**: `/src/test/java/com/effigenix/domain/usermanagement/`
  - 5 test classes
  - 98 test cases
  - Value objects and entity logic

- **Application Tests**: `/src/test/java/com/effigenix/application/usermanagement/`
  - 3 test classes
  - 45 test cases
  - Use cases with mocked dependencies

- **Infrastructure Tests**: `/src/test/java/com/effigenix/infrastructure/`
  - 3 test classes (security, mappers)
  - 58+ test cases
  - Implementations and adapters

### By Topic
- **Value Objects**: UserIdTest, RoleIdTest, PasswordHashTest
- **Entity Logic**: UserTest, RoleTest
- **Use Cases**: CreateUserTest, AuthenticateUserTest, ChangePasswordTest
- **Cryptography**: BCryptPasswordHasherTest
- **Mapping**: UserMapperTest, RoleMapperTest

---

## Running Specific Tests

### Run a single test class:
```bash
mvn test -Dtest=UserIdTest
mvn test -Dtest=UserTest
mvn test -Dtest=CreateUserTest
mvn test -Dtest=BCryptPasswordHasherTest
mvn test -Dtest=UserMapperTest
```

### Run all tests in a package:
```bash
mvn test -Dtest=com.effigenix.domain.usermanagement.*
mvn test -Dtest=com.effigenix.application.usermanagement.*
mvn test -Dtest=com.effigenix.infrastructure.security.*
mvn test -Dtest=com.effigenix.infrastructure.persistence.usermanagement.mapper.*
```

### Run a single test method:
```bash
mvn test -Dtest=UserTest#should_CreateUser_When_ValidDataProvided
mvn test -Dtest=BCryptPasswordHasherTest#should_HashPassword_When_ValidPasswordProvided
```

---

## Test Dependencies

### JUnit 5 Annotations Used
- `@Test` - Marks a test method
- `@DisplayName("description")` - Human-readable test name
- `@BeforeEach` - Setup before each test
- `@ParameterizedTest` - Parameterized tests
- `@ValueSource` - Parameter source for parameterized tests
- `@ExtendWith(MockitoExtension.class)` - Mockito support

### Mockito Annotations Used
- `@Mock` - Creates a mock object
- `@InjectMocks` - Injects mocks into system under test
- `when(...).thenReturn(...)` - Stubbing
- `when(...).thenAnswer(...)` - Complex stubbing
- `verify(...)` - Verification of method calls
- `ArgumentMatchers` - Flexible matching

### AssertJ Methods Used
- `assertThat(value).isEqualTo(expected)`
- `assertThat(value).isNotNull()`
- `assertThat(value).isInstanceOf(Type.class)`
- `assertThat(set).contains(item)`
- `assertThat(value).matches(regex)`
- `assertThatThrownBy(() -> code()).isInstanceOf(Exception.class)`
- `assertThat(list).hasSize(n)`

---

## Test Maintenance

### Adding new tests to existing class:
1. Follow existing test naming pattern: `should_X_When_Y()`
2. Add `@Test` and `@DisplayName("description")`
3. Use Arrange-Act-Assert pattern
4. Group related tests together
5. Update this index if adding new test class

### Updating tests after code changes:
1. Run affected test class: `mvn test -Dtest=ClassName`
2. Fix assertion expectations if behavior changed
3. Add new test case if new behavior added
4. Verify coverage still meets 80% target

---

## Coverage Report

Generate coverage report:
```bash
mvn clean test jacoco:report
# Report at: target/site/jacoco/index.html
```

View in browser:
```bash
open target/site/jacoco/index.html
```

Expected coverage:
- Domain Layer: 90-95%
- Application Layer: 85-90%
- Infrastructure Layer: 88-95%
- Overall: 80%+

---

## Notes

All test files are located in `/home/sebi/git/effigenix/src/test/java/` directory structure mirroring the main source code at `/home/sebi/git/effigenix/src/main/java/`.

Test files follow the naming convention: `{ClassName}Test.java`

Each test class is independent and can run in any order.