xamxam/app/tests/README.md

# XAMXAM Test Suite

Centralized test suite for the XAMXAM thesis management system.

## 📁 Structure

```
tests/
├── run-tests.php           # Test runner (runs all tests)
├── Unit/                   # Unit tests
│   ├── DatabaseTest.php    # Database connection & queries
│   └── RateLimitTest.php   # Rate limiting functionality
├── Integration/            # Integration tests
│   └── SearchTest.php      # Search functionality
├── Security/               # Security tests
│   └── SecurityTest.php    # SQL injection & XSS protection
└── README.md              # This file
```

## 🚀 Running Tests

### Run All Tests

```bash
# Using justfile (recommended)
just test

# Or directly
php tests/run-tests.php
```

### Run Individual Tests

```bash
# Database test
php tests/Unit/DatabaseTest.php

# Search test
php tests/Integration/SearchTest.php

# Security test
php tests/Security/SecurityTest.php

# Rate limit test
php tests/Unit/RateLimitTest.php
```

## ✅ Test Coverage

### Unit Tests

**DatabaseTest.php** - Tests basic database operations:
- ✅ Database connection
- ✅ Count published theses
- ✅ Get published theses
- ✅ Get single thesis by ID

**RateLimitTest.php** - Tests rate limiting:
- ✅ RateLimit initialization
- ✅ check() method
- ✅ sendHeaders() method
- ✅ getResetTime() method
- ✅ cleanup() method

### Integration Tests

**SearchTest.php** - Tests search functionality:
- ✅ Empty search query handling
- ✅ Search for specific terms
- ✅ Special characters in search

### Security Tests

**SecurityTest.php** - Tests security measures:
- ✅ SQL injection protection
- ✅ Invalid ID rejection
- ✅ XSS protection (output escaping)

## 📝 Writing New Tests

### Test File Template

```php
<?php
/**
 * Test Name
 * Description of what this tests
 */

require_once __DIR__ . '/../../lib/YourClass.php';

echo "Test Name\n";
echo "=========\n\n";

try {
    // Test 1
    echo "Test 1: Description\n";
    // ... test code ...
    echo "✓ PASS: Test passed\n\n";

    // Test 2
    echo "Test 2: Description\n";
    // ... test code ...
    echo "✓ PASS: Test passed\n\n";

    echo "✅ All tests passed!\n";
    return true;

} catch (Exception $e) {
    echo "❌ FAIL: " . $e->getMessage() . "\n";
    return false;
}
```

### Guidelines

1. **Return Value**: Return `true` for pass, `false` for fail
2. **Output Format**: Use `✓ PASS:` for successes, `❌ FAIL:` for failures
3. **Exceptions**: Catch and report exceptions clearly
4. **Dependencies**: Require only what's needed via relative paths
5. **Location**: 
   - `Unit/` - Tests for individual classes/functions
   - `Integration/` - Tests for feature workflows
   - `Security/` - Tests for security vulnerabilities

## 🔧 Test Database

Tests use the main database at `storage/xamxam.db`.

### Setup Test Database

```bash
# Create from schema
just init-db
```

### Reset Test Database

```bash
just reset-db
```

## 📊 Expected Output

Successful test run:
```
╔════════════════════════════════════════════╗
║         XAMXAM Test Suite                ║
╚════════════════════════════════════════════╝

┌─────────────────────────────────────────┐
│ Database (Unit)                         │
└─────────────────────────────────────────┘

✓ PASS: Database connection successful
✓ PASS: Found 16 published theses
...
✅ TEST PASSED

...

╔════════════════════════════════════════════╗
║              Test Summary                  ║
╠════════════════════════════════════════════╣
║ Total:   4                                 ║
║ Passed:  4 ✅                              ║
║ Failed:  0                                 ║
╚════════════════════════════════════════════╝

✅ All tests passed!
```

## 🐛 Debugging Failed Tests

### Check Logs

```bash
# Application errors
tail -f error.log

# Test output
php tests/run-tests.php > test-output.txt 2>&1
```

### Run Tests Individually

When a test fails, run it directly to see full output:

```bash
php tests/Unit/DatabaseTest.php
```

### Check Database

```bash
# Open database
just query

# Check stats
just stats
```

## 🔄 Continuous Testing

### Watch Mode (Future)

Could add file watching for auto-run:

```bash
# Future: auto-run tests on file change
just watch-tests
```

### Pre-commit Hook (Future)

Add to `.git/hooks/pre-commit`:

```bash
#!/bin/bash
php tests/run-tests.php
```

## 📚 Related Documentation

- [Database Specification](../storage/DATABASE_SPECIFICATION.md)
- [Security Documentation](../docs/SECURITY.md)
- [Development Guide](../MIGRATION_GUIDE.md)

---

**To run tests:** `just test`