# Unit Tests Documentation

This directory contains comprehensive unit tests for the high-priority internal packages of the AFASystems presence detection system.

## Test Coverage

The following files have been thoroughly tested:

1. **`distance_test.go`** - Tests for distance calculation utilities
   - `CalculateDistance()` - Distance calculation from RSSI and TX power
   - `twosComp()` - Two's complement hex conversion
   - `ValidateRSSI()` - RSSI value validation
   - `ValidateTXPower()` - TX power validation
   - Edge cases and real-world scenarios

2. **`beacons_test.go`** - Tests for beacon parsing utilities
   - `ParseADFast()` - Advertising Data structure parsing
   - `RemoveFlagBytes()` - Bluetooth flag bytes removal
   - `LoopADStructures()` - Beacon type detection and parsing
   - `isValidADStructure()` - AD structure validation
   - Beacon format support: Ingics, Eddystone TLM, Minew B7

3. **`typeMethods_test.go`** - Tests for model type methods
   - `Hash()` - Beacon event hash generation with battery rounding
   - `ToJSON()` - JSON marshaling for beacon events
   - `convertStructToMap()` - Generic struct-to-map conversion
   - `RedisHashable()` - Redis hash map conversion for HTTPLocation and BeaconEvent
   - JSON roundtrip integrity tests

4. **`mqtthandler_test.go`** - Tests for MQTT message processing
   - `MqttHandler()` - Main MQTT message processing with JSON/CSV input
   - `parseButtonState()` - Button counter parsing for different beacon formats
   - Kafka writer integration (with mock)
   - Hostname extraction from MQTT topics
   - Error handling and edge cases

## Running Tests

### Run All Tests
```bash
go test ./test/... -v
```

### Run Specific Test File
```bash
go test ./test/distance_test.go -v
go test ./test/beacons_test.go -v
go test ./test/typeMethods_test.go -v
go test ./test/mqtthandler_test.go -v
```

### Run Tests for Specific Function
```bash
go test ./test/distance_test.go -run TestCalculateDistance -v
go test ./test/beacons_test.go -run TestParseADFast -v
go test ./test/typeMethods_test.go -run TestHash -v
go test ./test/mqtthandler_test.go -run TestMqttHandlerJSONArrayInput -v
```

### Run Benchmarks
```bash
# Run all benchmarks
go test ./test/... -bench=.

# Run specific benchmarks
go test ./test/distance_test.go -bench=BenchmarkCalculateDistance -v
go test ./test/beacons_test.go -bench=BenchmarkParseADFast -v
go test ./test/typeMethods_test.go -bench=BenchmarkHash -v
go test ./test/mqtthandler_test.go -bench=BenchmarkMqttHandlerJSON -v
```

### Run Tests with Coverage Report
```bash
go test ./test/... -cover
go test ./test/... -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html
```

### Run Tests with Race Detection
```bash
go test ./test/... -race -v
```

## Test Organization

Each test file follows Go testing conventions with:
- **Function tests**: Individual function behavior testing
- **Edge case tests**: Boundary conditions and error scenarios
- **Integration tests**: Multi-function workflow testing
- **Benchmark tests**: Performance measurement
- **Table-driven tests**: Multiple test cases with expected results

## Mock Objects

The mqtthandler tests use a `MockKafkaWriter` to simulate Kafka operations without requiring a running Kafka instance. This allows for:

- Deterministic test results
- Failure scenario simulation
- Message content verification
- Performance benchmarking

## Known Limitations

- **CSV Processing**: The original CSV handler in `mqtthandler.go` contains `os.Exit(2)` calls which make it untestable. The test demonstrates the intended structure but cannot fully validate CSV processing due to this design choice.
- **External Dependencies**: Tests use mocks for external systems (Kafka) to ensure tests remain fast and reliable.

## Best Practices Demonstrated

These tests demonstrate several Go testing best practices:

1. **Table-driven tests** for multiple scenarios
2. **Subtests** for logical test grouping
3. **Benchmark tests** for performance measurement
4. **Mock objects** for dependency isolation
5. **Error case testing** for robustness validation
6. **Deterministic testing** with consistent setup and teardown

## Running Tests in CI/CD

For automated testing environments:

```bash
# Standard CI test run
go test ./test/... -race -cover -timeout=30s

# Performance regression testing
go test ./test/... -bench=. -benchmem
```

This comprehensive test suite ensures the reliability and correctness of the core business logic in the AFASystems presence detection system.