ColaFlow/colaflow-api/tests/Modules/Identity/ColaFlow.Modules.Identity.IntegrationTests/QUICK_START.md

Quick Start Guide - ColaFlow Integration Tests

TL;DR - Run Tests Now

# 1. Navigate to project root
cd c:\Users\yaoji\git\ColaCoder\product-master\colaflow-api

# 2. Build solution (stop API server first if running)
dotnet build

# 3. Run all integration tests
dotnet test tests/Modules/Identity/ColaFlow.Modules.Identity.IntegrationTests

# Done! ✓

What These Tests Cover

Day 5 - Phase 1: Refresh Token (9 tests)

• ✓ Register/Login returns access + refresh tokens
• ✓ Refresh token generates new token pair
• ✓ Old refresh tokens cannot be reused (rotation)
• ✓ Invalid refresh tokens fail
• ✓ Logout revokes refresh tokens
• ✓ User identity is maintained across refresh
• ✓ Multiple refresh operations work

Day 5 - Phase 2: RBAC (11 tests)

• ✓ TenantOwner role assigned on registration
• ✓ JWT contains role claims
• ✓ Role persists across login/refresh
• ✓ /api/auth/me returns role information
• ✓ Protected endpoints enforce role requirements

Day 4 - Regression (10 tests)

• ✓ Registration and login work
• ✓ Password hashing (BCrypt) verification
• ✓ JWT authentication and authorization
• ✓ Protected endpoint access control

Total: 30 Integration Tests

Running Specific Test Categories

Only Refresh Token Tests

dotnet test --filter "FullyQualifiedName~RefreshTokenTests"

Only RBAC Tests

dotnet test --filter "FullyQualifiedName~RbacTests"

Only Authentication Tests (Regression)

dotnet test --filter "FullyQualifiedName~AuthenticationTests"

Expected Output

Successful Run

Test run for ColaFlow.Modules.Identity.IntegrationTests.dll (.NETCoreApp,Version=v9.0)
Microsoft (R) Test Execution Command Line Tool Version 17.14.1 (x64)

Starting test execution, please wait...
A total of 1 test files matched the specified pattern.

Passed!  - Failed:     0, Passed:    30, Skipped:     0, Total:    30, Duration: 15s

Failed Test Example

Failed RefreshTokenTests.RefreshToken_ShouldReturnNewTokenPair [125 ms]
  Error Message:
   Expected response.StatusCode to be OK, but found Unauthorized.
  Stack Trace:
     at RefreshTokenTests.RefreshToken_ShouldReturnNewTokenPair()

Test Database

In-Memory Database (Default)

• No setup required
• Fast execution
• Perfect for CI/CD

Real PostgreSQL (Optional)

To run tests against real PostgreSQL:

1. Ensure PostgreSQL is running:

   # Check if PostgreSQL is running
   pg_isready
   

2. Edit test fixture in test files:

   // Change from
   public class RefreshTokenTests : IClassFixture<DatabaseFixture>
   
   // To
   public class RefreshTokenTests : IClassFixture<RealDatabaseFixture>
   

3. Run tests normally

Troubleshooting

Issue: Build fails with "file locked by another process"

Solution: Stop the API server

taskkill /F /IM ColaFlow.API.exe

Issue: Tests fail with "Connection refused"

Solution: Tests use In-Memory database by default, no connection needed. If you modified tests to use PostgreSQL, ensure it's running.

Issue: Tests are slow

Solution:

1. Verify you're using In-Memory database (default)
2. Run specific test category instead of all tests
3. Disable parallel execution for debugging:

   [assembly: CollectionBehavior(DisableTestParallelization = true)]
   

Issue: "Could not find test file"

Solution: Rebuild the project

dotnet clean
dotnet build
dotnet test

Viewing Test Details

Visual Studio

1. Open Test Explorer: Test → Test Explorer
2. Run all tests or specific test
3. View detailed output in Test Explorer window

JetBrains Rider

1. Open Unit Tests window: View → Tool Windows → Unit Tests
2. Run tests with Ctrl+U, Ctrl+R
3. View test results in Unit Tests window

Command Line (Detailed Output)

dotnet test --logger "console;verbosity=detailed"

Integration with Day 5 Implementation

These tests verify:

1. Refresh Token Flow

User Registration → Access Token + Refresh Token
              ↓
        Use Access Token (expires in 15 min)
              ↓
  Call /api/auth/refresh with Refresh Token
              ↓
     New Access Token + New Refresh Token
              ↓
    Old Refresh Token is invalidated (rotation)

2. RBAC Flow

Tenant Registration → User assigned "TenantOwner" role
              ↓
         JWT includes role claims
              ↓
        Login/Refresh preserves role
              ↓
    Protected endpoints check role claims

Test Assertions

Tests use FluentAssertions for readable assertions:

// HTTP Status
response.StatusCode.Should().Be(HttpStatusCode.OK);

// Token validation
result.AccessToken.Should().NotBeNullOrEmpty();
result.RefreshToken.Should().NotBe(oldRefreshToken);

// Role verification
TestAuthHelper.HasRole(accessToken, "TenantOwner").Should().BeTrue();

Next Steps

After tests pass:

1. ✓ Day 5 Phase 1 (Refresh Token) verified
2. ✓ Day 5 Phase 2 (RBAC) verified
3. ✓ Day 4 regression tests pass
4. Ready to proceed to Day 6: Email Verification or MCP integration

CI/CD Ready

This test project is CI/CD ready:

• No manual setup required (uses In-Memory database)
• Isolated tests (no external dependencies)
• Fast execution (~15-30 seconds for 30 tests)
• Deterministic results
• Easy to integrate with GitHub Actions, Azure DevOps, Jenkins, etc.

Questions?

• See README.md for detailed documentation
• Check test files for implementation examples
• Review TestAuthHelper.cs for helper methods

---

Run tests now and verify your Day 5 implementation!

cd c:\Users\yaoji\git\ColaCoder\product-master\colaflow-api
dotnet test tests/Modules/Identity/ColaFlow.Modules.Identity.IntegrationTests