Valheim.Testing.GameSessions
Reference source:
f6459d0c772b. For the installed package version, use the published package table.
API reference. This page is the package's README; each type's members are in the reference.
Valheim.Testing.GameSessions runs game sessions for mod tests: a dedicated server with its clients, a client hosting a world with its peers, or a server on another machine, prepared, started, joined and torn down as one run. It is built on Valheim.Testing.Game, which drives one game process. Unofficial community tooling; not affiliated with or endorsed by Iron Gate or Coffee Stain. Valheim is a trademark of Iron Gate AB.
| You want | Use |
|---|---|
| Observe or drive one game, or a joining client's rounds | Valheim.Testing.Game alone |
| A dedicated server and a client, with a save and restart | This package: PinnedServerRun |
| A hosting client's rounds, driven by your code | This package: HostedClientRounds.Run (game sessions) |
| Two builds of your mod in one scenario | This package: TargetedRegression |
| A server on another machine, or several clients | This package: an inventory file and a campaign |
Install
Add both packages to a separate system-test project, never to the mod. It targets net10.0.
<PackageReference Include="Valheim.Testing.Game" Version="[0.1.0]" />
<PackageReference Include="Valheim.Testing.GameSessions" Version="[0.1.0]" />
Brackets pin an exact version; the released versions are in the package table. This package depends on exactly the Valheim.Testing.Game version it was built with, so the two always restore as the pair that was tested together.
using Valheim.Testing.Game;
using Valheim.Testing.GameSessions;
A first session
Copy the FullLifecycle example: one dedicated server and one client on this machine, with a save, a restart and a rejoin. Test that a change survives a save, restart and rejoin walks through it. Your scenario receives the started session:
public static void Run(GameSession session, MarkerPlan plan) =>
Run(plan, session.Server!.Game, session.Server!, () => session.OpenClient(plan.Client!), session.Report, session.Output, session.Cancellation);
For xUnit, copy GameSessionFixture.cs and the skip pattern in ExampleSession.cs. Without its private session files, the native test is skipped with the reason, so dotnet test stays offline.
What every run does
| Behaviour | Rule |
|---|---|
| Profiles | Each owned process runs from a disposable loader profile; the install is only read and never copied (profiles) |
| Hosts | Each machine is a host with one shell; Linux hosts run the dedicated server only (game hosts) |
| Claims | A run takes each host's lock and leases each client's Steam account (locks and leases) |
| Journal | Every profile, copy, character and process is journalled before it is made, for valheim-test env status and env recover |
| User files | A client's recent-servers list is moved aside before launch and restored after (the user's files) |
| Report | result.json and junit.xml, with every step's phase and four states (phases and states) |
Reference pages
| Types | Page |
|---|---|
GameSession, ServerActor, ClientActor, HostingClientActor, HostedClientRounds |
Game sessions |
PinnedServerRun, PinnedServerRunOptions<TPlan>, ModDeclaration |
Pinned server runner |
IGameHost, HostServer, InteractiveClient |
Game hosts |
EnvironmentInventory with a file |
Inventory file |
The profile contract, --in-place |
Disposable profiles |
SteamAccountHold, EnvironmentRuns, OwnedCopies, RunCancellation |
Locks, leases and recovery |
HostedCampaignManifest, HostedCampaignPreparation |
Campaigns |
TargetedRegression, StagedArm |
Targeted regression |
WorldDump |
Pinned world dumps |
ReviewCapture, ReviewClip |
Evidence |
Profiles and hosts explains the ideas behind these pages.
Test fakes
FakeGameSession.Create and FakeGameSession.Hosted, in Valheim.Testing.GameSessions.Fakes, build a session over scripted clients, with no game. The Valheim.Testing.Game fakes work with them.
Limits
- A pass with fakes is an orchestration test, not an in-game pass.
- A client runs only in a signed-in desktop session with Steam; the toolkit never signs in to Steam.
- The output holds local paths, account identifiers and a copy of the user's recent-servers list. Keep it private.