openmu/docs/PacketStructureTests.md

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

// 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

// 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

// 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:

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.