WotR.Testing.Offline 0.1.0-preview.1

WotR.Testing.Offline

Runs a Pathfinder: Wrath of the Righteous mod against the real game assemblies, vanilla blueprint pack and settings on the game's own Unity Mono runtime (or .NET Framework), without starting Wrath.exe or the Unity player. The mod is loaded through the entry method in its Info.json, and its blueprints are created by its own patches on the game's BlueprintsCache.Init.

Status: preview; the API may change. Verified with WotR 2.7.0, AttributeFeats (BlueprintCore) and TabletopTweaks-Base with TabletopTweaks-Core as a dependency mod. See docs/offline.md for how it works, every environment adaptation and the known limits.

The library and its NuGet package contain no game files. Game assemblies are referenced at compile time from your own installation and copied and rewritten on the test machine. License: AGPL-3.0 with an additional permission for use together with the game and Unity assemblies.

Use it in a mod's test project

Requirements: Windows, the .NET SDK, PowerShell 7, a UnityModManager mod with Info.json in its build output, and the game installed (or a snapshot from New-WotrSnapshot.ps1).

From NuGet

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <PlatformTarget>x64</PlatformTarget>
    <WotrModAssembly>../MyMod/bin/Debug/MyMod.dll</WotrModAssembly>
    <WrathInstallDir>C:/Games/Pathfinder Second Adventure</WrathInstallDir>
  </PropertyGroup>
  <ItemGroup>
    
    <WotrDependencyMod Include="../deps/TabletopTweaks-Core/TabletopTweaks-Core.dll" />
    <PackageReference Include="WotR.Testing" Version="0.1.0-preview.1" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
    <PackageReference Include="xunit" Version="2.9.2" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
  </ItemGroup>
</Project>

WotR.Testing is the meta-package for all WotR.Testing components; referencing WotR.Testing.Offline directly works the same. The build targets are imported automatically. Its runner and snapshot scripts are in the package's tools/ folder, which the project reports as WotrToolsDirectory:

$tools = dotnet msbuild tests/MyMod.Tests/MyMod.Tests.csproj -getProperty:WotrToolsDirectory
pwsh -NoProfile -File "$($tools.Trim())Invoke-WotrOfflineTests.ps1" -Project tests/MyMod.Tests/MyMod.Tests.csproj

From a Git submodule

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net48</TargetFramework>
    <PlatformTarget>x64</PlatformTarget>
    <WotrModAssembly>../MyMod/bin/Debug/MyMod.dll</WotrModAssembly>
    <WrathInstallDir>C:/Games/Pathfinder Second Adventure</WrathInstallDir>
  </PropertyGroup>
  <Import Project="../../external/wotr-testing/src/WotR.Testing.Offline/build/WotR.Testing.Offline.targets" />
  <ItemGroup>
    
    <WotrDependencyMod Include="../deps/TabletopTweaks-Core/TabletopTweaks-Core.dll" />
    <ProjectReference Include="../../external/wotr-testing/src/WotR.Testing.Offline/WotR.Testing.Offline.csproj" AdditionalProperties="WotrInputRoot=$(WotrInputRoot)" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.11.1" />
    <PackageReference Include="xunit" Version="2.9.2" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.8.2" />
  </ItemGroup>
</Project>

The default -Runtime mono of Invoke-WotrOfflineTests.ps1 runs xUnit v2 test projects on the game's own Mono runtime; other test frameworks can use -Runtime netfx. Add xunit.runner.json with "appDomain": "denied" and "shadowCopy": false, copied to the output. Build the mod without deploying it to the game.

public sealed class MyModGame : WotrGameFixture
{
    // Optional: fail initialization unless the mod reports success.
    protected override void VerifyModInitialized(GameSession session) { }
}

[CollectionDefinition("game")]
public sealed class GameCollection : ICollectionFixture<MyModGame> { }

[Collection("game")]
public sealed class MyFeatTests
{
    private readonly MyModGame game;
    public MyFeatTests(MyModGame game) => this.game = game;

    [Fact]
    public void FeatAddsBonus()
    {
        game.RequireGame();
        var unit = OfflineGame.CreateUnit("<vanilla unit blueprint guid>");
        var before = OfflineGame.StatSnapshot(unit);
        unit.Progression.Features.AddFeature(OfflineGame.Blueprint<BlueprintFeature>("<feat guid>"));
        // assert on unit.Stats, then remove the fact and compare with before
    }
}

Game types can be used anywhere in test classes. The targets generate a module initializer into the test assembly that installs the game assembly resolver; the first request for a game assembly, even while the test framework discovers tests, prepares the runtime folder. If your project already defines System.Runtime.CompilerServices.ModuleInitializerAttribute, set WotrGenerateModuleInitializer=false and call OfflineRuntime.InstallResolver() from your own module initializer.

Catch UnityNative.IsUnavailable(error) and skip with UnityNative.SkipReason(...) when a path reaches Unity engine code; such results are reported as unity-runtime-required, never as passed.

Build properties and variables

API