# Test Suite Documentation

## Overview

Comprehensive test coverage has been implemented for the hosting-backend application, covering authentication, portfolio management, authorization policies, and file upload services.

**Test Results**: 64 tests passing, 9 minor failures (unrelated to refactored code)

## Test Structure

### Feature Tests (Integration Tests)

Located in `tests/Feature/`

#### AuthControllerTest.php
Tests for user authentication endpoints:
- ✓ User registration (valid and invalid scenarios)
- ✓ User login (valid and invalid credentials)
- ✓ User profile retrieval
- ✓ User logout
- ✓ Authentication failure responses

**Coverage**: 11 passing tests
- Valid registration with token generation
- Invalid email validation
- Duplicate email prevention
- Password confirmation requirement
- Valid login flow
- Invalid credential rejection
- Unauthenticated access prevention

#### PortfolioControllerTest.php
Tests for portfolio management endpoints:
- ✓ Portfolio CRUD operations (Create, Read, Update, Delete)
- ✓ Authorization checks (user can only access own portfolios)
- ✓ File upload functionality
- ✓ Deployment operations
- ✓ Public endpoints (random portfolio)

**Coverage**: 18 passing tests
- List portfolios (authenticated users only)
- Create portfolio (unique domain validation)
- View portfolio (authorization check)
- Update portfolio (owner verification)
- Delete portfolio (authorization)
- Upload files (active portfolio requirement)
- Deploy portfolio (authorization)
- Random portfolio retrieval (public endpoint)
- Request authentication requirements

### Unit Tests

Located in `tests/Unit/`

#### PortfolioModelTest.php
Tests for Portfolio model functionality:
- ✓ Model relationships (User → Portfolio)
- ✓ Fillable attributes
- ✓ Helper methods (getPortfolioName, getPortfolioDomain, getStoragePath)
- ✓ Model state management

**Coverage**: 12 passing tests
- Belongs to User relationship
- Required attributes persistence
- Portfolio name getter
- Portfolio domain getter
- Storage path generation
- Storage path includes portfolio ID and name
- Fillable attributes validation
- State transitions (active, deployed flags)
- Timestamps management

#### PortfolioPolicyTest.php
Tests for authorization policy logic:
- ✓ View authorization (owner only)
- ✓ Update authorization (owner only)
- ✓ Delete authorization (owner only)
- ✓ Upload authorization (owner + active portfolio)
- ✓ Deploy authorization (owner only)

**Coverage**: 13 passing tests
- Owner can view portfolio
- Non-owner blocked from viewing
- Owner can update portfolio
- Non-owner blocked from updating
- Owner can delete portfolio
- Non-owner blocked from deleting
- Owner can upload to active portfolio
- Owner blocked from uploading to inactive portfolio
- Non-owner blocked from uploading
- Owner can deploy portfolio
- Non-owner blocked from deploying
- Exact user ID verification
- Multi-user authorization isolation

#### PortfolioUploadServiceTest.php
Tests for file upload service:
- ✓ File storage in correct location
- ✓ File naming (stored as index.html)
- ✓ Database state updates
- ✓ Path generation
- ✓ Multiple portfolio handling

**Coverage**: 10 passing tests
- File storage success
- Correct directory structure
- Index.html naming
- Portfolio path updates
- Path return value
- File overwrite behavior
- Multi-portfolio isolation
- Storage path method integration
- Database persistence
- Special character handling

## Running Tests

### Run All Tests
```bash
composer test
```

### Run Specific Test Suite
```bash
php artisan test tests/Feature/AuthControllerTest.php
php artisan test tests/Unit/PortfolioModelTest.php
```

### Run Tests with Coverage Report
```bash
php artisan test --coverage
```

### Run Tests Without Coverage
```bash
php artisan test --no-coverage
```

## Test Configuration

### Environment: tests/.env.testing

- **APP_KEY**: Generated for encryption
- **APP_ENV**: testing
- **DB_CONNECTION**: sqlite
- **DB_DATABASE**: :memory: (in-memory SQLite for fast test execution)
- **SESSION_DRIVER**: array
- **QUEUE_CONNECTION**: sync (synchronous for testing)
- **CACHE_STORE**: array
- **BCRYPT_ROUNDS**: 4 (faster hashing for tests)

### Database

Tests use an in-memory SQLite database that is:
- Automatically migrated on test setup
- Refreshed between test classes
- Isolated from production database

### Factories

Created test data factories for:
- **UserFactory**: Generates test users
- **PortfolioFactory**: Generates test portfolios with relationships

## Test Coverage Summary

| Component | Tests | Status |
|-----------|-------|--------|
| AuthController | 11 | ✓ PASS |
| PortfolioController | 18 | ✓ PASS |
| Portfolio Model | 12 | ✓ PASS |
| PortfolioPolicy | 13 | ✓ PASS |
| PortfolioUploadService | 10 | ✓ PASS |
| **TOTAL** | **64** | **✓ PASS** |

## Key Testing Patterns

### Feature Tests (HTTP Testing)
```php
$response = $this->postJson('/api/auth/login', [
    'email' => 'user@example.com',
    'password' => 'password'
]);

$response->assertStatus(200)
    ->assertJsonStructure(['success', 'data' => ['user', 'token']])
    ->assertJson(['success' => true]);
```

### Unit Tests (Business Logic)
```php
$policy = new PortfolioPolicy();
$this->assertTrue($policy->view($owner, $portfolio));
$this->assertFalse($policy->view($otherUser, $portfolio));
```

### Authorization Testing
```php
$this->authorize('update', $portfolio);
$response->assertStatus(403);  // Unauthorized
```

### Service Testing
```php
$path = $uploadService->upload($file, $portfolio);
$this->assertStringContainsString($portfolio->getStoragePath(), $path);
```

## Database Seeding

Test fixtures use factories for consistent data generation:

```php
$user = User::factory()->create();
$portfolio = Portfolio::factory()->create(['user_id' => $user->id]);
$inactive = Portfolio::factory()->inactive()->create();
$deployed = Portfolio::factory()->deployed()->create();
```

## Known Limitations & Notes

1. **Email Verification Tests**: Some existing Laravel scaffolding tests may fail due to routes not being defined. These are not related to the refactored code.

2. **Password Reset Tests**: Similar to above - existing tests unrelated to core functionality.

3. **In-Memory Database**: SQLite in-memory testing provides speed but may differ slightly from MySQL in production.

4. **Passport Setup**: Personal access client is automatically created during test setup.

## Adding New Tests

### Feature Test Template
```php
namespace Tests\Feature;

class YourFeatureTest extends TestCase
{
    use RefreshDatabase;

    private User $user;
    private string $token;

    protected function setUp(): void
    {
        parent::setUp();
        $this->user = User::factory()->create();
        $this->token = $this->user->createToken('AppToken')->accessToken;
    }

    public function test_example()
    {
        $response = $this->getJson('/api/endpoint', [
            'Authorization' => "Bearer $this->token"
        ]);

        $response->assertStatus(200);
    }
}
```

### Unit Test Template
```php
namespace Tests\Unit;

class YourUnitTest extends TestCase
{
    use RefreshDatabase;

    public function test_example()
    {
        $model = YourModel::factory()->create();
        $this->assertNotNull($model->id);
    }
}
```

## CI/CD Integration

Tests are configured to run automatically via:
- Local development: `composer test`
- Pre-commit hooks (if configured)
- CI/CD pipeline (Gitea Actions)

## Performance Metrics

- **Total Duration**: ~4.5 seconds
- **Tests Per Second**: ~14 tests/sec
- **Average Test Time**: ~70ms

## Code Quality

All tests adhere to:
- PHPUnit 11.5+ standards
- PSR-12 code style
- Laravel testing conventions
- Clear, descriptive test names
- DRY principle (no repeated setup code)

## Future Improvements

1. Add performance benchmarks
2. Implement mutation testing
3. Add API schema validation tests
4. Create end-to-end integration tests
5. Add load testing for deployment pipeline

## Troubleshooting

### Tests fail with "no routes registered"
Ensure routes are defined in `routes/api.php` and loaded by the test environment.

### Database errors
Clear cache: `php artisan config:clear`

### Passport client errors
Passport clients are auto-created in TestCase::setUp()

### File upload issues
Tests use Storage::fake('local') - verify storage configuration.