Valheim.Testing.Game 0.1.0-preview.62

ValheimTesting

Reusable test inputs, fixtures and assertions for Valheim mods. Most tests run without Valheim, Unity, Steam or a dedicated server; native checks drive disposable game sessions through ValheimCLI on supported Windows, macOS and Linux hosts.

Unofficial community tooling; not affiliated with or endorsed by Iron Gate or Coffee Stain. Valheim is a trademark of Iron Gate AB.

First test in three steps

1. Install the .NET 10 SDK (Visual Studio 2026 brings it) on the PC where you build your mod.
2. Copy ModWithTests beside your mod: a test project that links your mod's real source files and references Valheim.Testing.Doubles from NuGet.org.
3. Run dotnet test MyMod.Tests/MyMod.Tests.csproj. No game, Steam or ValheimCLI is needed.

Then Bring your mod helps choose the layer for each behaviour, Get started has the package versions and IDE setup, and the examples go up to native checks with owned game processes. Supported hosts and limits are in platforms. New to BepInEx and Harmony? The community wiki's overview explains the concepts; check its older samples against 1.0 (wiki caveats). A plugin that will not load, or two mods that conflict: debugging guide.

To make the test workflow discoverable to your coding agent, copy the ValheimTesting skill into your mod repository.

For a disposable in-game load check, build your mod and run the tool from the directory containing its single .csproj:

dotnet build -c Release
valheim-test env preflight
valheim-test server-load

server-load selects the newest built [BepInPlugin] DLL, prints the choice, and records it in the run. start uses the same default for a client mod; server-load-ab requires explicit mod paths to keep both arms fixed. The tool refuses a missing, stale or ambiguous build instead of guessing. It writes run output under this machine's ValheimTesting data folder, outside your mod project. See the one-shot guide for setup and explicit options.

Packages

Each package's page is its reference: what it is for, the types a test calls, how it fails and its limits.

The dependency goes ValheimTesting → ValheimCLI, never the reverse: the game-side extension API stays in ValheimCLI, and a mod keeps its own adapter and scenarios. No test package belongs in a production mod or a player's plugin folder. Valheim.Testing.Cli is ValheimCLI's transport packaged by this repository from the fork commit cli-dependency.json pins, not an official ValheimCLI release. Preview APIs may change; the candidate API reference inventories them for the stable-contract review.

Test layers

1. Unit: real mod decisions against small declared inputs and the doubles. Broad and fast.
2. Integration: scenario drivers, adapters and fixtures against scripted replies and fake processes.
3. Bounded game checks: a few zones on a disposable server and client; save, restart and replication when those boundaries change.
4. Human judgement: a short look or walk when appearance or usability matters.

Synthetic inputs are not Valheim's generator, a replay of a capture is not independent evidence of the game, and an incomplete observation fails rather than reading as zero.

Contribute

Mod developers and coding agents are welcome. CONTRIBUTING.md has repository ownership, a worked fixture example, local checks (sh scripts/validate.sh on macOS/Linux; the bootstrap entrypoint then dotnet run scripts/validate.cs on Windows; no game) and PR expectations. Agents start with AGENTS.md and the agent workflow. Before a native run, read the runtime hygiene checklist.

License

MIT, copyright © 2026 Tys von Gaza. See LICENSE. Attribution for imported and adapted code is retained in THIRD-PARTY-NOTICES.md and PROVENANCE.md; both license files are included in the library packages.