# XML Parser Test Suite

This document describes the comprehensive test suite for the `xmlparser` package and related TED XML models.

## 📁 Test Files Overview

### Core Package Tests (`pkg/xmlparser/`)

- **`interfaces_test.go`** - Tests for interfaces, types, and basic structures
- **`parser_test.go`** - Tests for XML parsing functionality and core parser logic
- **`utils_test.go`** - Tests for utility functions and error handling
- **`benchmark_test.go`** - Performance benchmarks and memory allocation tests

### TED Models Tests (`ted/`)

- **`ted_test.go`** - Tests for TED XML models and validation logic

### Test Infrastructure

- **`run_tests.sh`** - Comprehensive test runner script with coverage analysis
- **`TEST_SUITE.md`** - This documentation file

## 🧪 Test Categories

### 1. Interface and Type Tests (`interfaces_test.go`)

- **Default Parser Options**: Validates default configuration values
- **XML Metadata**: Tests metadata extraction and structure
- **Parse Results**: Validates result structure and error handling
- **Mock Implementation**: Tests the `MockParseable` test helper
- **Parser Interface**: Ensures interface compliance and method availability

**Key Test Functions:**
- `TestDefaultParserOptions()`
- `TestXMLMetadata()`
- `TestParseResult()`
- `TestMockParseable()`
- `TestParserInterface()`

### 2. Parser Functionality Tests (`parser_test.go`)

- **Parser Creation**: Tests parser instantiation with various options
- **XML Parsing**: Tests parsing from string, bytes, and readers
- **Validation**: Tests XML structure validation and depth limits
- **Size Constraints**: Tests parsing with size and depth limitations
- **Error Scenarios**: Tests handling of malformed XML and validation failures
- **Metadata Extraction**: Tests XML metadata extraction (version, encoding, namespace)
- **Concurrent Parsing**: Tests thread safety and concurrent access

**Key Test Functions:**
- `TestNewParser()`
- `TestParseString()` / `TestParseBytes()` / `TestParse()`
- `TestValidate()`
- `TestParseWithResult()`
- `TestConcurrentParsing()`

### 3. Utility Function Tests (`utils_test.go`)

- **Validation Errors**: Tests error structures and formatting
- **XML Sanitization**: Tests removal of invalid XML characters
- **XML Name Validation**: Tests XML element name validation rules
- **Namespace Validation**: Tests XML namespace URI validation
- **String Utilities**: Tests whitespace normalization and string truncation
- **Error Types**: Tests error interface implementations

**Key Test Functions:**
- `TestValidationError()` / `TestValidationErrors()`
- `TestXMLParseError()`
- `TestSanitizeXMLString()`
- `TestValidateXMLName()`
- `TestIsValidNamespace()`
- `TestNormalizeWhitespace()`
- `TestTruncateString()`

### 4. TED Model Tests (`ted/ted_test.go`)

- **Contract Notice Validation**: Tests validation rules and business logic
- **Getter Methods**: Tests all getter methods for extracting data from XML
- **Extension Handling**: Tests handling of UBL extensions and eForms data
- **Complex Scenarios**: Tests nested structures and edge cases
- **Date/Time Validation**: Tests various date format validations
- **Currency and Duration**: Tests validation of currency codes and duration units

**Key Test Functions:**
- `TestContractNoticeValidation()`
- `TestContractNoticeBasicGetters()`
- `TestContractNoticeExtensionGetters()`
- `TestContractNoticeProcurementDetails()`
- `TestValidDateFormats()`

### 5. Performance Benchmarks (`benchmark_test.go`)

- **Parsing Performance**: Benchmarks for different XML sizes (small, medium, large)
- **Memory Allocation**: Tests memory usage patterns during parsing
- **Utility Performance**: Benchmarks for utility functions
- **Concurrent Performance**: Tests performance under concurrent load
- **Validation Performance**: Benchmarks for different validation scenarios

**Key Benchmark Functions:**
- `BenchmarkParseString()` / `BenchmarkParseBytes()`
- `BenchmarkParseSmallXML()` / `BenchmarkParseMediumXML()` / `BenchmarkParseLargeXML()`
- `BenchmarkConcurrentParsing()`
- `BenchmarkMemoryAllocation()`

## 🚀 Running Tests

### Quick Test Run

```bash
# Run all tests
go test -v ./...

# Run tests with coverage
go test -v -cover ./...

# Run specific test category
go test -v -run=TestParser
go test -v -run=TestValidation
go test -v -run=TestUtils
```

### Comprehensive Test Suite

```bash
# Run the complete test suite with coverage and benchmarks
cd pkg/xmlparser
./run_tests.sh
```

### Benchmark Tests

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

# Run specific benchmarks
go test -bench=BenchmarkParse -benchmem
go test -bench=BenchmarkConcurrent -benchmem

# Run benchmarks with profiling
go test -bench=. -cpuprofile=cpu.prof -memprofile=mem.prof
```

### Coverage Analysis

```bash
# Generate coverage report
go test -coverprofile=coverage.out
go tool cover -html=coverage.out -o coverage.html

# View coverage in terminal
go tool cover -func=coverage.out
```

## 📊 Test Statistics

### Coverage Targets

- **Overall Coverage**: ≥ 80%
- **Critical Paths**: ≥ 95%
- **Error Scenarios**: ≥ 90%
- **Utility Functions**: ≥ 95%

### Test Counts (Approximate)

- **Unit Tests**: 50+ test functions
- **Benchmarks**: 20+ benchmark functions
- **Test Cases**: 200+ individual test scenarios
- **Mock Objects**: Full `MockParseable` implementation

## 🔧 Test Infrastructure

### Mock Objects

**`MockParseable`**: Test implementation of the `Parseable` interface
- Supports both valid and invalid states for testing validation
- Includes all required XML structure elements
- Implements proper validation logic for testing error scenarios

### Test Utilities

- **Error Readers**: For testing I/O error scenarios
- **XML Test Data**: Various XML samples for different test cases
- **Concurrent Test Helpers**: For testing thread safety

### Test Configuration

- **Parallel Execution**: Concurrent tests are properly isolated
- **Race Detection**: All tests pass with `-race` flag
- **Memory Testing**: Benchmarks include memory allocation tracking
- **Timeout Handling**: Long-running tests have appropriate timeouts

## 🚨 Common Test Scenarios

### Success Cases

- Valid XML parsing with all data types
- Proper validation of business rules
- Correct metadata extraction
- Successful error handling and recovery

### Error Cases

- Malformed XML structure
- Invalid business data (missing required fields)
- Size and depth limit violations
- I/O errors during reading
- Validation failures

### Edge Cases

- Empty XML documents
- Very large XML documents
- Deeply nested structures
- Unicode and special characters
- Concurrent access patterns

## 📈 Performance Expectations

### Parsing Performance

- **Small XML** (< 1KB): < 10μs per operation
- **Medium XML** (1-10KB): < 100μs per operation
- **Large XML** (10-100KB): < 1ms per operation

### Memory Usage

- **Parsing Overhead**: < 3KB per operation
- **Memory Allocations**: < 100 allocations per parse
- **No Memory Leaks**: All tests pass memory leak detection

### Concurrent Performance

- **Thread Safety**: All operations are thread-safe
- **Scalability**: Performance scales linearly with CPU cores
- **Resource Sharing**: Parsers can be safely shared between goroutines

## 🔍 Debugging Tests

### Running Individual Tests

```bash
# Run specific test with verbose output
go test -v -run=TestSpecificFunction

# Run test with race detection
go test -race -run=TestConcurrent

# Run test with memory profiling
go test -run=TestMemory -memprofile=mem.prof
```

### Test Debugging Tips

1. **Use `-v` flag** for verbose output to see individual test progress
2. **Use `-race` flag** to detect race conditions in concurrent tests
3. **Use `-count=1`** to disable test caching for consistent results
4. **Use `-timeout`** to prevent hanging tests in CI environments
5. **Check coverage reports** to identify untested code paths

## 📝 Adding New Tests

### Guidelines for New Tests

1. **Follow naming conventions**: `TestFunctionName` for unit tests, `BenchmarkFunctionName` for benchmarks
2. **Use table-driven tests** for multiple test cases
3. **Include both success and failure scenarios**
4. **Add appropriate benchmarks** for performance-critical code
5. **Update this documentation** when adding new test categories

### Test Structure Template

```go
func TestNewFeature(t *testing.T) {
    tests := []struct {
        name        string
        input       InputType
        expected    ExpectedType
        expectError bool
    }{
        {
            name:        "Valid case",
            input:       validInput,
            expected:    expectedOutput,
            expectError: false,
        },
        {
            name:        "Error case",
            input:       invalidInput,
            expected:    nil,
            expectError: true,
        },
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            result, err := FunctionUnderTest(tt.input)
            
            if tt.expectError {
                if err == nil {
                    t.Errorf("Expected error but got none")
                }
                return
            }
            
            if err != nil {
                t.Errorf("Unexpected error: %v", err)
                return
            }
            
            if !reflect.DeepEqual(result, tt.expected) {
                t.Errorf("Expected %v, got %v", tt.expected, result)
            }
        })
    }
}
```

## 🎯 Continuous Integration

### CI Pipeline Tests

1. **Unit Tests**: All unit tests must pass
2. **Race Detection**: Tests must pass with `-race` flag
3. **Coverage Check**: Coverage must meet minimum thresholds
4. **Benchmark Regression**: Performance must not regress significantly
5. **Lint Checks**: Code must pass all linting rules

### Quality Gates

- ✅ All tests pass
- ✅ Coverage ≥ 80%
- ✅ No race conditions detected
- ✅ Benchmarks within acceptable range
- ✅ No critical linting errors

---

## 📞 Support

For questions about the test suite or adding new tests, please refer to:

1. **Code Comments**: Inline documentation in test files
2. **README.md**: Main package documentation
3. **Architecture Documentation**: Project-wide coding standards
4. **Team Knowledge Base**: Internal development guidelines

---

*This test suite ensures the reliability, performance, and maintainability of the XML parser package and related TED models.*