87 lines
3.3 KiB
Markdown
87 lines
3.3 KiB
Markdown
# Packet Structure Tests Implementation
|
|
|
|
## Overview
|
|
|
|
This implementation provides automatically generated tests for packet structures defined in XML files. The tests validate that packet definitions are correct and would catch issues like incorrect packet lengths (as mentioned in PR #622).
|
|
|
|
## Files Created
|
|
|
|
### 1. `src/Network/Packets/GenerateTests.xslt`
|
|
XSLT transformation that generates C# test code from XML packet definitions. Features:
|
|
- Validates fixed-length packets/structures against their declared lengths
|
|
- Tests variable-length packets' GetRequiredSize methods
|
|
- Validates field boundaries to prevent buffer overruns
|
|
- Generates syntactically correct C# test code with proper naming
|
|
|
|
### 2. `tests/MUnique.OpenMU.Network.Packets.Tests/`
|
|
New test project that:
|
|
- Automatically generates test files during build (when `ci` is not set)
|
|
- Integrates with existing test infrastructure (NUnit, StyleCop, etc.)
|
|
- Added to main solution file for CI/CD integration
|
|
|
|
### 3. Test Files Generated
|
|
- `ClientToServerPacketTests.cs` - Tests for client-to-server packets
|
|
- `ServerToClientPacketTests.cs` - Tests for server-to-client packets
|
|
- `ChatServerPacketTests.cs` - Tests for chat server packets
|
|
- `ConnectServerPacketTests.cs` - Tests for connect server packets
|
|
|
|
## Types of Validation
|
|
|
|
### Fixed-Length Validation
|
|
```csharp
|
|
// Validates declared length matches calculated size
|
|
const int expectedLength = 20; // From XML
|
|
const int actualLength = PlayerShopItem.Length; // From generated struct
|
|
Assert.That(actualLength, Is.EqualTo(expectedLength));
|
|
|
|
// Validates field boundaries
|
|
Assert.That(fieldIndex + fieldSize, Is.LessThanOrEqualTo(expectedLength));
|
|
```
|
|
|
|
### Variable-Length Validation
|
|
```csharp
|
|
// Tests GetRequiredSize method accuracy
|
|
const string testString = "TestData";
|
|
var calculatedSize = StoredItem.GetRequiredSize(testString);
|
|
var expectedSize = Encoding.UTF8.GetByteCount(testString) + 1 + baseOffset;
|
|
Assert.That(calculatedSize, Is.EqualTo(expectedSize));
|
|
```
|
|
|
|
### Field Boundary Validation
|
|
```csharp
|
|
// Ensures fields don't exceed packet boundaries
|
|
Assert.That(fieldIndex + fieldSize, Is.LessThanOrEqualTo(packetLength));
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **Build Process**: During build, XSLT transformations read XML packet definitions
|
|
2. **Code Generation**: Generates comprehensive test methods for each packet/structure
|
|
3. **Validation**: Tests run during normal test execution, catching definition errors
|
|
4. **Integration**: Fully integrated with existing CI/CD pipeline
|
|
|
|
## Benefits
|
|
|
|
- **Automatic Detection**: Catches packet definition errors at build time
|
|
- **Comprehensive Coverage**: Tests all packet types and structures
|
|
- **Zero Maintenance**: Tests are automatically updated when XML definitions change
|
|
- **Early Error Detection**: Prevents runtime issues from malformed packets
|
|
|
|
## Usage
|
|
|
|
The tests run automatically as part of the normal build and test process. No manual intervention required.
|
|
|
|
To run tests manually:
|
|
```bash
|
|
dotnet test tests/MUnique.OpenMU.Network.Packets.Tests/
|
|
```
|
|
|
|
## Example Issues Caught
|
|
|
|
The generated tests would catch issues like:
|
|
- Packet length declared as 10 but fields require 12 bytes
|
|
- Field starting at index 8 with size 4 in a 10-byte packet
|
|
- Incorrect GetRequiredSize calculations
|
|
- Overlapping field definitions
|
|
|
|
This addresses the core issue mentioned in PR #622 where packet structures were defined incorrectly. |