n.nakhostin
7dc695752b
- Deleted the `github.com/google/uuid` dependency from `go.mod` to streamline the project and reduce unnecessary dependencies. - Updated `go.sum` to reflect the removal of the UUID package. - Enhanced the overall module management by ensuring only necessary dependencies are included.
350 lines
10 KiB
Markdown
350 lines
10 KiB
Markdown
# 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.* |