Valheim.Testing 0.3.0

ValheimTesting

Test what your Valheim mod does in the game. Start with a small action and an independent assertion, then reuse that scenario to protect a fix.

The marker example asks the mod to place a pole, then counts its saved objects. Selected action and assertion lines from Scenario.cs:

var reply = host.Execute("examplemod_mark " + At());
round.Step("exactly one marker stands there in the host's saved objects", () => RequireMarkers(host, x, z, ExpectedMarkers));

ExpectedMarkers is 1. A captured run records "first: exactly one marker stands there in the host's saved objects" with Passed: true. The unchanged assertion also catches a command that reports success without creating a pole.

Run your first gameplay assertion: the complete source, files to edit, tested command and failure result.

Choose your task

A load check proves that plugins start and enter a world. Gameplay checks need their own action and assertion.

First test in three steps

Follow Get started for the offline example and its copy map. You need no toolkit clone or bootstrap.

Native runs need a supported host: game clients on Windows and macOS, dedicated servers on Windows, macOS and Linux (platforms); the gameplay tutorial is written for Windows. New to BepInEx and Harmony? Read the community wiki's overview. A plugin that will not load, or two mods that conflict: the debugging guide.

Packages

Package versions lists every package, exact pin and reference link. Keep test packages in test projects, outside a player's plugin folder. The dependency goes ValheimTesting → ValheimCLI, never the reverse: a mod keeps its own adapter and scenarios. Preview APIs may change; see compatibility.

Test layers

Choose a test layer explains what unit tests, scripted integration, native checks and human review each prove. The example index shows the marker at those layers.

Contribute

Read CONTRIBUTING.md to change the toolkit; coding agents changing it start with AGENTS.md. To have your coding agent test your mod, give it the workflow.

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

Credits

ValheimTesting is built on ValheimCLI, created by Warpalicious (Thunderstore) and licensed MIT. Every native check talks to the game through ValheimCLI: its in-game plugin runs the commands, and its client transport, which ships as Valheim.Testing.Cli, sends them. This project uses a pinned fork, tvongaza/valheimCLI, which adds the commands and packs the toolkit needs. Thank you, Warpalicious, for building and sharing it.

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.