sam-api/tests/README.md

# Parametric BOM System Test Suite

This directory contains comprehensive test files for the parametric BOM system, including unit tests, integration tests, performance tests, and API validation.

## Test Structure

### PHPUnit Tests (`tests/Feature/Design/`)

Comprehensive PHPUnit feature tests for all Design domain components:

- **ModelParameterTest.php** - Tests parameter CRUD operations, validation, and type casting
- **ModelFormulaTest.php** - Tests formula creation, calculation, and dependency resolution
- **BomConditionRuleTest.php** - Tests condition rule evaluation and BOM manipulation
- **BomResolverTest.php** - Tests complete BOM resolution workflows
- **ProductFromModelTest.php** - Tests product creation from parametric models

### Database Seeders (`database/seeders/`)

Test data seeders for comprehensive testing:

- **ParametricBomSeeder.php** - Creates comprehensive test data with multiple models
- **KSS01ModelSeeder.php** - Creates specific KSS01 model with realistic parameters

### Validation Scripts (`scripts/validation/`)

Standalone validation scripts for system testing:

- **validate_bom_system.php** - Complete system validation
- **test_kss01_scenarios.php** - KSS01-specific business scenario testing
- **performance_test.php** - Performance and scalability testing

### API Testing (`tests/postman/`)

Postman collection for API testing:

- **parametric_bom.postman_collection.json** - Complete API test collection
- **parametric_bom.postman_environment.json** - Environment variables

## Running Tests

### Prerequisites

1. **Seed Test Data**
   ```bash
   php artisan db:seed --class=KSS01ModelSeeder
   # or for comprehensive test data:
   php artisan db:seed --class=ParametricBomSeeder
   ```

2. **Ensure API Key Configuration**
   - Set up valid API keys in your environment
   - Configure test tenant and user credentials

### PHPUnit Tests

Run individual test suites:

```bash
# All Design domain tests
php artisan test tests/Feature/Design/

# Specific test classes
php artisan test tests/Feature/Design/ModelParameterTest.php
php artisan test tests/Feature/Design/BomResolverTest.php

# Run with coverage
php artisan test --coverage-html coverage-report/
```

### Validation Scripts

Run system validation scripts:

```bash
# Complete system validation
php scripts/validation/validate_bom_system.php

# KSS01 business scenarios
php scripts/validation/test_kss01_scenarios.php

# Performance testing
php scripts/validation/performance_test.php
```

### Postman API Tests

1. Import the collection: `tests/postman/parametric_bom.postman_collection.json`
2. Import the environment: `tests/postman/parametric_bom.postman_environment.json`
3. Update environment variables:
   - `api_key` - Your API key
   - `user_email` - Test user email (default: demo@kss01.com)
   - `user_password` - Test user password (default: kss01demo)
4. Run the collection

## Test Coverage

### Core Functionality

- ✅ Parameter validation and type checking
- ✅ Formula calculation and dependency resolution
- ✅ Condition rule evaluation and BOM manipulation
- ✅ Complete BOM resolution workflows
- ✅ Product creation from parametric models
- ✅ Tenant isolation and security
- ✅ Error handling and edge cases

### Business Scenarios

- ✅ Residential applications (small windows, patio doors)
- ✅ Commercial applications (storefronts, office buildings)
- ✅ Edge cases (minimum/maximum sizes, unusual dimensions)
- ✅ Material type variations (fabric vs steel)
- ✅ Installation type variations (wall/ceiling/recessed)

### Performance Testing

- ✅ Single BOM resolution performance
- ✅ Batch resolution performance
- ✅ Memory usage analysis
- ✅ Database query efficiency
- ✅ Concurrent operation simulation
- ✅ Large dataset throughput

### API Validation

- ✅ Authentication and authorization
- ✅ CRUD operations for all entities
- ✅ BOM resolution workflows
- ✅ Error handling and validation
- ✅ Performance benchmarks

## Performance Targets

| Metric | Target | Test Location |
|--------|--------|---------------|
| Single BOM Resolution | < 200ms | performance_test.php |
| Batch 10 Resolutions | < 1.5s | performance_test.php |
| Batch 100 Resolutions | < 12s | performance_test.php |
| Memory Usage | < 50MB | performance_test.php |
| DB Queries per Resolution | < 20 | performance_test.php |
| Throughput | ≥ 10/sec | performance_test.php |

## Quality Gates

### System Validation Success Criteria

- ✅ ≥90% test pass rate = Production Ready
- ⚠️ 75-89% test pass rate = Review Required
- ❌ <75% test pass rate = Not Ready

### Business Scenario Success Criteria

- ✅ ≥95% scenario pass rate = Business Logic Validated
- ⚠️ 85-94% scenario pass rate = Edge Cases Need Review
- ❌ <85% scenario pass rate = Critical Issues

### Performance Success Criteria

- ✅ ≥90% performance tests pass = Performance Requirements Met
- ⚠️ 70-89% performance tests pass = Performance Issues Detected
- ❌ <70% performance tests pass = Critical Performance Issues

## Troubleshooting

### Common Issues

1. **"KSS_DEMO tenant not found"**
   - Run KSS01ModelSeeder: `php artisan db:seed --class=KSS01ModelSeeder`

2. **API key authentication failures**
   - Verify API key is correctly set in environment
   - Check API key middleware configuration

3. **Test database issues**
   - Ensure test database is properly configured
   - Run migrations: `php artisan migrate --env=testing`

4. **Performance test failures**
   - Check database indexes are created
   - Verify system resources (CPU, memory)
   - Review query optimization

### Debugging Tips

1. **Enable Query Logging**
   ```php
   DB::enableQueryLog();
   // Run operations
   $queries = DB::getQueryLog();
   ```

2. **Check Memory Usage**
   ```php
   echo memory_get_usage(true) / 1024 / 1024 . " MB\n";
   echo memory_get_peak_usage(true) / 1024 / 1024 . " MB peak\n";
   ```

3. **Profile Performance**
   ```bash
   php -d xdebug.profiler_enable=1 scripts/validation/performance_test.php
   ```

## Continuous Integration

### GitHub Actions / CI Pipeline

```yaml
# Example CI configuration
- name: Run PHPUnit Tests
  run: php artisan test --coverage-clover coverage.xml

- name: Run System Validation
  run: php scripts/validation/validate_bom_system.php

- name: Run Performance Tests
  run: php scripts/validation/performance_test.php

- name: Check Coverage
  run: |
    if [ $(php -r "echo coverage_percentage();") -lt 80 ]; then
      echo "Coverage below 80%"
      exit 1
    fi
```

### Quality Metrics

- **Code Coverage**: Minimum 80% line coverage
- **Test Pass Rate**: Minimum 95% pass rate
- **Performance**: All performance targets met
- **Security**: No security vulnerabilities in tests

## Contributing

When adding new tests:

1. Follow existing naming conventions
2. Include both positive and negative test cases
3. Add performance considerations for new features
4. Update this README with new test documentation
5. Ensure tenant isolation in all tests
6. Include edge case testing

## Support

For test-related issues:

1. Check logs in `storage/logs/laravel.log`
2. Review test output for specific failure details
3. Verify test data seeding completed successfully
4. Check database connection and permissions