tm_back/pkg/xmlparser/TEST_SUITE.md

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

# 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

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

Benchmark Tests

# 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

# 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

# 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

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.