Writing Tests¶

This guide covers the VinTest test authoring API in depth.

For a quick introduction, see Getting Started.

Test suites and test cases¶

Tests are organized into suites — plain C# classes marked with [GameTestSuite]. Each suite contains one or more test cases — public methods marked with [GameTest], returning IEnumerable<TestStep>.

[GameTestSuite]
public class PetTests
{
    [GameTest]
    public IEnumerable<TestStep> WolvesAreTameable() =>
        new TestChain()
            .Assert("wolf entity has tameable behavior", () => /* verify */);

    [GameTest]
    public IEnumerable<TestStep> WolvesEatMeat() =>
        new TestChain()
            .Do(() => /* feed meat to wolf */)
            .Wait(/* give it time to process */)
            .Assert("wolf got tamed status", () => /* verify */);
}

Naming convention¶

Each test case is identified by SuiteName.CaseName: the suite class name followed by the test method name.

PetTests.WolvesAreTameable
PetTests.WolvesEatMeat

This identifier is used in log output and in filtering.

The TestChain API¶

TestChain is a builder class that describes what a test does, step by step. You chain calls to it and return the result from your test method.

Steps are not executed immediately when the method is called — they are collected and then executed one by one by the runner on subsequent game loop ticks. This allows the runner to interleave them with the game loop (e.g. wait for an entity to spawn before asserting something about it).

As a rule of thumb: if a callback throws, or an .Assert() condition returns false, the test case stops at that step and is marked as failed.

.Assert()¶

TestChain.Assert — the core step. Evaluates a bool-returning callback and records the result. If the condition returns false the test case is marked as failed and stops.

new TestChain()
    .Assert("player is alive", () => player.Entity.Alive)
    .Assert("health is above 50", () => player.Entity.WatchedAttributes
        .GetTreeAttribute("health").GetFloat("currenthealth") > 50f)

The source file and line number parameters are populated automatically by the compiler via the reflection magicks of CallerFilePath / CallerLineNumber attributes — do not pass them manually. They record the assertion's source location, which VinTest.Cake and the VS Code extension surface as a clickable link when a test fails.

.Do()¶

TestChain.Do — simply executes a callback.

Entity? wolf = null;
new TestChain()
    .Do(() => wolf = SpawnWolf(sapi))
    .Assert("wolf is in the world", () => wolf.Alive)

Keep your .Assert()s shorter by putting the execution code in .Do()s.

// EITHER:
.Assert("", () => wolf!.Alive)
// OR:
Entity wolf = null!;

.Wait()¶

TestChain.Wait — pause. Once the chain execution reaches this step, it unconditionally waits for the given number of milliseconds before proceeding to the next step. Use this to give the game time to process events before asserting.

new TestChain()
    .Do(() => ScheduleExplosion(pos, 100))
    .Wait(1000)
    .Assert("block was destroyed", () => /* verify */)

// give OnTick() enough time to trigger
int waitInterval = system.updateInterval * 3
...
.Wait(waitInterval)

.WaitIf()¶

TestChain.WaitIf — same as .Wait(), but only waits if the condition is true at the moment the step runs. Otherwise the wait is skipped and execution continues immediately.

bool needChunksToLoad = false;
new TestChain()
    .Do(() => needChunksToLoad = TeleportIfFarAway())
    .WaitIf(chunkLoadMs, () => needChunksToLoad)
    .Assert("entity is loaded", () => /* verify */)

.AssertEventually()¶

Polls a condition repeatedly until it returns true or the timeout is reached. If the timeout is reached without the condition becoming true, the test case fails. Useful for asserting on things that take a while.

new TestChain()
    .Do(() => SpawnDrifterNearby())
    .AssertEventually(
        "drifter found the player",
        maxMs: 5000,
        breakWhen: () => PlayerWasAttacked(),
        // pollIntervalMs: 500  // optional
    )
    .Assert("player took damage", () => PlayerHealthDecreased())

Notes¶

// WRONG: the exception fires when the runner collects steps, not when it runs them
[GameTest]
public IEnumerable<TestStep> BadTest()
{
    var entity = FindEntity(); // throws if not found yet
    return new TestChain().Assert("entity exists", () => entity != null);
}

// CORRECT: put any code that might fail inside a callback
[GameTest]
public IEnumerable<TestStep> GoodTest()
{
    Entity? entity = null;
    return new TestChain()
        .Do(() => entity = FindEntity())
        .Assert("entity exists", () => entity != null);
}

Injecting dependencies into suites¶

Suites are instantiated in CreateSuites(), which is called after the player has spawned. Pass API instances, players and other useful dependencies into your suite constructors there:

public class EconomyTests
{
    private readonly ICoreServerAPI sapi;
    private readonly EconomySystem economy;
    private readonly IServerPlayer player;

    public EconomyTests(ICoreServerAPI s, EconomySystem e, IServerPlayer p)
    {
        sapi = s;
        economy = e;
        player = p;
    }

    // ...
}

public class YourTestModSystem : GametestModsystemBase
{
    protected override object[] CreateSuites(IServerPlayer player) =>
    [
        new EconomyTests(SApi, SApi.ModLoader.GetModSystem<EconomySystem>(), player),
    ];
}

public class EconomyTests(ICoreServerAPI sapi, EconomySystem economy, IServerPlayer player)
{
    // sapi, economy, player are available throughout the class body
}

Startup delay¶

By default, VinTest waits 2000 ms after the player joins before running the first test. This gives the world time to finish loading before tests begin.

If your test world takes longer to settle (or you need less), override StartupDelayMs:

public class YourTestModSystem : GametestModsystemBase
{
    protected override int StartupDelayMs => 5000;

    protected override object[] CreateSuites(IServerPlayer player) => [/* ... */];
}

Interaction with VinTest.Cake¶

These things are much easier to do if you use the cake task to drive your tests — but in the end it boils down to Cake writing parameters into ModConfig/vintestconfig.json, and the framework internals reacting to set parameters.

Filtering tests¶

Instead of running every test on every launch, you can run a subset by filtering.

The filter is a comma-separated list of case-insensitive substrings. A test case is run only if its SuiteName.CaseName contains at least one of the substrings.

{
    "TestCaseFilter": "Economy,Crafting"
}

This runs only test cases whose full name contains "economy" or "crafting".

Manual mode¶

When ManualMode is enabled, VinTest loads normally but does not run tests automatically. Use this to launch VS in a known state for manual debugging the tests, or initializing the world.

Enable it in vintestconfig.json:

{
    "ManualMode": true
}

You can hook into this in your ModSystem to register debug commands or do custom setup:

public class YourTestModSystem : GametestModsystemBase
{
    protected override object[] CreateSuites(IServerPlayer player) => [/* ... */];

    protected override void OnManualModeReady(IServerPlayer player)
    {
        SApi.RegisterCommand("debugthing", "...", "", (p, g, a) => DebugThing());
        CreateEntitiesInWorld();
    }
}