Valheim.Testing.Game 0.1.0-preview.41

ValheimTesting

Reusable test inputs, fixtures and assertions for Valheim mods. Most tests run without Valheim, Unity, Steam or a dedicated server. Optional system tests use the real game through ValheimCLI.

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

Bringing your own mod? Start with the adoption guide and a complete first mod test. Use package setup and the example index for the next layer. To investigate a load failure or mod conflict, use the debugging guide. Existing mod tests stay in their own repository; shared helpers and lifecycle code are adopted gradually. Before a native run, read the runtime hygiene and evidence checklist.

Browse the candidate API reference on GitHub Pages. It is generated from main and remains an inventory for the stable-contract review, not yet a 1.0 API promise.

New to Valheim plugins? The community wiki's BepInEx and Harmony overview explains the modding concepts used by these examples. Its older code samples are background, not a substitute for this toolkit's pinned game-version checks; see wiki version caveats.

Contribute

Mod developers and coding agents are welcome to help extend the synthetic world, capture/replay, observations and lifecycle tools. Read CONTRIBUTING.md for repository ownership, a worked fixture example, local checks and PR expectations. Useful local contributions can be reviewed before native testing; mark that evidence as not run.

AI agent entry point

Start with AGENTS.md and the agent workflow. A CLAUDE.md pointer keeps Claude-based assistants on the same instructions. The guide covers tool discovery, strict pins, one-shot mutations, result interpretation, test-layer limits and restoration/handoff.

Packages and ownership

The dependency goes ValheimTesting → ValheimCLI, never the reverse. Game-side extension API and observers stay in ValheimCLI. Roads and MWL own their optional adapters and scenarios. No test package belongs in an ordinary player's plugin folder.

Until upstream merges the required transport/API changes, cli-dependency.json pins our ValheimCLI fork by full commit and exact package version. The packages, including the native-smoke tool, are published on NuGet.org as releases become available. ValheimTesting publishes the transport as Valheim.Testing.Cli so it is clearly this toolkit's packaging, not an official ValheimCLI release; upstream's own project is Valheim.Cli.Testing. Bootstrap builds it from tracked source at the pinned commit into an ignored local feed; it does not compile or launch the game plugin.

Validate or develop the framework (no game)

Consumers of published packages can restore directly from NuGet.org; see the adoption guide. The commands below validate this entire repository.

Requires only the .NET 10 SDK and Git; the bootstrap and validation scripts are .NET file-based C# programs. The pure library targets netstandard2.0; the game library and examples target net10.0 and allow a newer runtime. The ValheimCLI transport package is built for net10.0 from the pinned ValheimCLI source, so .NET 10 is the only modern runtime needed.

dotnet run scripts/bootstrap-cli.cs
# Or use a local CLI clone; the script exports only the pinned commit:
# dotnet run scripts/bootstrap-cli.cs -- --source /path/to/valheimCLI
dotnet run scripts/validate.cs
dotnet run --project examples/SharedWorld -c Release

validate.cs runs the local library tests, builds all external examples and packs the libraries to .packages. It never starts Valheim. The ValheimCLI transport and its tests remain upstream-owned, not copied here. Choose the packages in getting started: its exact versions are the newest releases, recorded once in toolkit-versions.json. Pin the versions your mod tests actually use; a newly published package does not silently change a passing test. Use the local feed only to try a build that is not yet published.

The same commands work in any shell on Windows, macOS and Linux; there is no per-shell launcher. A sandbox that blocks the NuGet caches or the SDK's file-based app directory needs the sandbox recipe in AGENTS.md.

Platforms

The toolkit needs only the .NET 10 SDK on every host, and CI runs bootstrap and validation on all three. ClientLaunch builds a BepInEx game-client launch (Doorstop loader checks and variables, -console, SteamAppId) from a client install on its own OS, and ServerLaunch does the same for a dedicated server; each refuses the other's install and names the right one. ClientLaunch only builds the launch: a client needs an interactive desktop session with a display and a running Steam client, so InteractiveClient starts it inside a Windows or Linux host's existing desktop session (see the toolkit notes). On a Mac, an owned game client runs under Rosetta by default or natively on Apple Silicon when its plan asks for arm64 (native client), and the native macOS dedicated server can run locally with the BepInEx setup in getting started; ServerLaunch still refuses a Valheim.app client passed as a server runtime and a Windows or Linux server on macOS. Remote macOS server hosts are not supported yet.

Linux and containers

Owned dedicated-server checks can run on Linux as well as Windows. ServerLaunch detects a copied server runtime's platform from its executable (valheim_server.exe or valheim_server.x86_64) and builds the direct launch that DirectServerProcess and OwnedServerSession own, including BepInEx's Doorstop variables on Linux. It is new in Game preview.11. docker/linux-server builds a local x86-64 image with the server, BepInEx and .NET 10, and the manual Linux workflow boots it once with LinuxServerSmoke. The scheduled server checks run that smoke and the FullLifecycle example's server half every night and after each new public server build, and keep one tracking issue open while they fail. The image and smoke were verified on a Linux x86-64 Docker host on 28 September 2026 (server build 25527701); on Apple Silicon the image runs only under emulation and remains experimental.

Linux game clients can run on a remote NVIDIA GPU host using the client container, which supplies a display and Steam setup but no game files. An environment inventory and game hosts (local, SSH, container) run scripts, take a host lock, ship a revision, follow a log, fetch evidence and reach a loopback-only ValheimCLI through an SSH tunnel. PinnedServerRun --inventory runs a plan's dedicated server on an inventory host (Linux over SSH or in a container, or Windows), from any OS (a server-only plan on a remote host); a campaign (PinnedServerRun.RunCampaignAsync) places remote clients too, each started in its host's desktop session (InteractiveClient) on the Steam identity signed in there, leased so no two runs use it at once. A server-only run from macOS over SSH to a Linux VM has passed natively, and a Windows client was started in its desktop session over SSH during a crossplay run; provisioning the host and signing in its Steam client stays with the operator.

Server images contain Valheim's game files. Build them locally or in the CI job that uses them; never push, upload or publish an image, layer or server directory.

Test pyramid

1. Unit/synthetic: real mod decisions against small explicit inputs. Broad and fast.
2. Integration: transport, adapters, fixture handling and orchestration with controlled doubles.
3. Bounded game checks: a few zones on a disposable server and ValheimCLI-only client; save/restart and replication when those boundaries change.
4. Human judgement: short visual/walking checks when usability matters.

Synthetic inputs are not Valheim's generator. Replaying captured inputs is not independent proof of the game's physics. Incomplete observations fail explicitly. Session ownership does not own Steam accounts, machine reservations or another operator's running game.

Evidence and limits

Local validation covers synthetic inputs, observation contracts and lifecycle failure handling. Roads supplies the first native scenarios: a 100-sample declared terrain/collider calibration, followed by a persistent two-zone native fixture. On Valheim 1.0.16, a ValheimCLI-only client matched 15 height/collider samples and three stationary grounded observations before and after confirmed server save/restart/rejoin. The later paint arm matched all 16 paved-core/verge RGBA samples across the same lifecycle. An unchanged-paint negative expectation failed exactly the eight painted samples and passed the untouched eight.

The paint fixture starts from explicit saved RGBA, preserves alpha and samples both sides of a zone seam. The follow-up campaign adds bounded dirt/fading-edge coverage. These fixtures do not establish arbitrary terrain, rendered appearance or human walking usability. Mod-specific acceptance status belongs in the mod's scenario report. See the detailed guide, source provenance, and examples.

Preview APIs may change. No release or upstream merge is implied by this repository.

Developer-loop scripts

tools/dev-loop holds dev-loop.cs, one .NET file-based script for a mod's edit-build-test loop (build, install into a game copy you own, launch, run a strict plan, summarise the log), and a strict smoke plan to start from. It drives a valheim-cli executable taken from a ValheimCLI release or build; see Developer loop.

Two more tools are for a mod's build: tools/test-runners (one MSBuild targets file) runs a test project on net10.0 and on net48 (Mono on macOS and Linux, .NET Framework on Windows) and fails if either fails, and tools/game-references gives the mod's game-side projects their Valheim, Unity and BepInEx references from one ValheimPath, with an error naming whatever is missing.

ObserveCheck attaches to a prepared game and runs one probe: declared heights, a client's ground and collider, loaded raw paint, a terrain capture for replay, a human-driven walk without moving the character, or session state and save. The bounded paved paint/reload check passed; human walking acceptance remains pending.

License

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

Shared-world fixtures: guide and mod consumers, runnable example. Zone state is the terrain doubles' TerrainComp arrays; snapshots are in-memory test state, not native saves.

The 27 September native follow-up covers strict reloads, terrain capture/replay, session controls, controlled mutation draining and dirt/fade paint persistence. It records the remaining limits explicitly.