unit-testing

name	unit-testing
description	Write, fix, or review NeoServer unit tests using xUnit and FluentAssertions. Use this skill when the user wants to create new tests, fix failing tests, or review existing tests — even if they only say "add tests," "fix the test," or mention testing a domain entity (Player, Monster, Item, NPC, Tile), handler, game system, or server component. Covers test helpers, behavioral naming, xUnit traits, and the repository-only mocking policy.
compatibility	Requires .NET 10 SDK and dotnet CLI. Designed for NeoServer project conventions.

Quick Reference

Workflow

• 1. Identify behavior — one behavior per test
• 2. Write the test using AAA structure with the template below
• 3. Use existing helpers (PlayerTestDataBuilder, ItemTestDataBuilder, MapTestDataBuilder, etc.) instead of building from scratch
• 4. Tag with trait: [Trait("Category", "<value>")]
• 5. Run: dotnet test tests/<project>
• 6. Fix any failures and re-run until green

Test Template

[Fact]
[Trait("Category", "<HappyPath|Validation|EdgeCase|ErrorCondition|Integration>")]
public void {Actor}_does_{something}_when_{condition}()
{
    // Arrange
    var player = PlayerTestDataBuilder.Build();
    // ... use existing builders; mock only I*Repository

    // Act
    player.DoSomething();

    // Assert
    result.Should().Be(expected);
}

Project-Specific Conventions

Test Framework & Mocking

• xUnit with FluentAssertions (Should().BeTrue(), .BeEquivalentTo(), etc.)
• Do NOT mock domain entities, services, or commands — use real implementations
• Only mock infrastructure interfaces: I*Repository, IConnection, IEventAggregator
• Use Moq for mocks when needed

Naming

{Actor}_does_{something}_when_{condition}

Examples: Player_gets_disconnected_when_game_is_stopped, World_replaces_tile_when_new_tile_provided, Player_cannot_push_null_creature.

Test Isolation

Each [Fact] creates its own instances. Never share objects between tests — no static state, no class-level fixtures. Tests that need serialized execution use [ThreadBlocking].

Traits

Only [Trait("Category", "<value>")] is used. Valid values:

Value	When to Use
HappyPath	Core positive/expected behavior
Validation	Input validation, null checks, rejection
EdgeCase	Boundary conditions, corner cases
ErrorCondition	Error state handling (login fails, etc.)
Integration	Multi-component interaction (real objects, mock only repos)
PathFinding	Pathfinding algorithm tests
Proximity	Distance/proximity checks
Tile	Tile occupation/state tests

Custom Attributes

• [SkipOnGitHubActionsFact] — skips test in CI (for tests needing real DB)
• [ThreadBlocking] — serializes test execution via semaphore

Helper Methods — Reusable Builders

All helpers live in tests/NeoServer.Domain.Tests/Helpers/ and use optional parameters with sensible defaults:

Core Builders

Builder	Location	Key Method
PlayerTestDataBuilder	Helpers/Player/	Build(id, name, hp, mana, skills, inventoryMap, vocationType, ...)
ItemTestDataBuilder	Helpers/	CreateContainer(...), CreateCumulativeItem(...), CreateWeaponItem(...) (27 methods)
MonsterTestDataBuilder	Helpers/	Build(maxHealth, speed, isHostile, flags, ...)
MapTestDataBuilder	Helpers/Map/	Build(fromX, toX, fromY, toY, fromZ, toZ, ...) — rectangular grid
NpcTestDataBuilder	Helpers/	Build(name, npcType)
InventoryTestDataBuilder	Helpers/Player/	Build(player, inventoryMap, ...)
PartyTestDataBuilder	Helpers/	Build(partyInviteService, players)

Server Test Builders

Located in tests/NeoServer.Domain.Tests/Server/:

Builder	Purpose
GameServerTestBuilder	Creates IGameServer with map
ItemTypeStoreTestBuilder	Creates ItemTypeStore from items
ItemFactoryTestBuilder	Creates IItemFactory with type store
DecayableItemManagerTestBuilder	Creates DecayableItemManager
ScriptManagerTestBuilder	Creates IScriptManager
ServerTestHelper	Starts game server threads
TestSetup	Full DI container boot (in NeoServer.Server.Tests)

Event Helpers

Helper	Purpose
EventAggregatorTestHelper	SetupEventAggregator<TEvent>(handler) — wires handler to fire on publish
EventAssertHelper	Fluent extensions: WithArgs<T>(Expression)
EventSubscriptionCleanUp	CleanUp<T>(eventName) — tears down subscriptions between tests

Pattern

// Simple in-file helper
private static Location CreateLocation(ushort x = 100, ushort y = 100, byte z = 7)
    => new(x, y, z);

// Compose from existing builders
private static IPlayer CreatePlayerWithFullInventory()
{
    var player = PlayerTestDataBuilder.Build();
    var inventory = InventoryTestDataBuilder.Build(player);
    return player;
}

Gotchas

• Mock only infrastructure: Never mock domain entities (IPlayer, IMonster, IItem), services, or commands — use real implementations. Only mock I*Repository, IConnection, IEventAggregator.
• No shared state: Each [Fact] must create everything from scratch. Static or class-level state causes test pollution.
• One behavior per test: Multiple assertions for different behaviors belong in separate [Fact] methods.
• Always use FluentAssertions: result.Should().BeTrue(), not Assert.True(result).
• Handler null guards: Event handlers must guard with if (@event is null) return;.
• Builders are in Helpers/: Look in tests/NeoServer.Domain.Tests/Helpers/ for *TestDataBuilder classes before writing new setup code.
• Data-driven tests: Use [InlineData] for simple cases, [MemberData] for complex parameter sets, [ClassData] for reusable data classes.

Running Tests

# All tests
dotnet test tests/

# Specific project
dotnet test tests/NeoServer.Domain.Tests

# Specific category
dotnet test tests/ --filter "Category=HappyPath"

# Code coverage
dotnet test tests/ --collect:"XPlat Code Coverage" --results-directory testresults

# Build before test
dotnet build src/Standalone --configuration Release