Choose a test layer

When to use this

You have one behaviour to protect and have not decided how to test it. Start in your mod's repository with the cheapest layer that can observe the behaviour. Move down the table only when the cheaper layer cannot reach it. If the immediate problem is a mod that does not load, go to Debug a mod load or mod conflict first.

Pick a layer

Without the game

Your mod needs to test Use First example What still needs the game
A decision over heights, slopes or biomes Valheim.Testing with an ITerrain SharedWorld Real generator output, physics and save encoding
Production code that calls supported Unity or Valheim types Valheim.Testing.Doubles, source-linked ModWithTests: five runnable xUnit cases Unmodelled game methods, Harmony timing, actual replication
A pinned grid dump, reviewed as a picture TerrainRenderer with contours Test terrain decisions Native gameplay evidence; the picture is an interpolation
Retry, refusal, readiness or cleanup in a scenario driver Valheim.Testing.Game.Fakes Test fakes The real process and game lifecycle

The doubles model selected ZDO, RPC, console and ownership behaviour as well as terrain; read what they model before relying on a member. A field or stub is not an emulation of the game. Code that uses no Unity or Valheim type needs only Valheim.Testing and an ITerrain passed into the real method.

With the game

These rows use Valheim.Testing.Game with ValheimCLI in the game, or the valheim-test tool. Sessions and A/B runs add Valheim.Testing.GameSessions.

Your mod needs to test Use First example What still needs the game
Loaded height, collision or paint reaching a client ObserveCheck surface or paint surface, paint Appearance; a human judges it
Generator heights against loaded ground ObserveCheck ground ground Collider, paint or walking behaviour
A bounded grid sample recorded for exact replay ObserveCheck capture capture That the sampled value is independently correct
A named loaded-terrain site before, after or on failure Terrain site snapshots Terrain site snapshots Generator height, ZDO state or human usability
Saved objects, containers and structures near a site Area object snapshots Area object snapshots Terrain, paint or a mod-specific correctness verdict
Save, restart and rejoin under owned process control PinnedServerRun, ClientRounds, SessionControl FullLifecycle, ObserveCheck session A client when replication matters
Whether a mod loads, or which mod set conflicts valheim-test server-load, server-load-ab or start Debug a mod load or mod conflict The mod's gameplay behaviour; which mod owns a conflict
One mod before and after a change (A/B) in the real game TargetedRegression runner TargetedRegression: preflight without the game, then one run per arm Other mods, dedicated servers or restarts
Walking and appearance ObserveCheck walk plus a person walk Acceptance; the human verdict is recorded separately

Rules of thumb

  • Start in your mod repository. Shared fixtures go to this repository; game-side API goes to ValheimCLI.
  • Synthetic input is not Valheim's generator.
  • A replay of a capture is input, not independent evidence of the game.
  • An incomplete observation fails. It never reads as zero.
  • A person judges appearance and walkability. Record that verdict separately from the test result.

Problems

Problem Cause Fix
A game type conflicts or is missing The test project mixes source doubles with game assemblies Link source files only; see Test logic that uses game types
A package does not restore The pin names an unpublished version Pin an exact version from Packages
A native run hangs, or passes but proves nothing Runtime, load order, characters, timing or evidence rules Go through the runtime hygiene checklist
Edit this page