| name | cs-offengine-testing |
| description | Write and run the mod's C# unit tests off-engine (net48 + xUnit). Use when writing or running C# tests, when a test hits an engine-bound type (Unity native call, Colossal.Logging.ILog, HttpQueries) or throws TypeLoadException off-engine, or when deciding where to put logic so it stays testable (plain Services/, not ECS Systems/). |
C# Off-Engine Testing
The mod's C# tests run off-engine: a plain net48 xUnit process, not a booted game. Everything
below follows from that one fact. Code that reaches the engine (Unity native calls, the game's
logging stack, a live ECS World) cannot run here, so the job is to test product logic in isolation
and keep engine-bound code behind a seam you can fake.
Tests live in the HallOfFame.Tests project.
Run
mise test:cs
This runs dotnet test with -p:SkipBuildUI=true -p:SkipModPostProcess=true, so the TypeScript UI
build and the mod post-processor are skipped (the tests need neither). Prefer it over a bare
dotnet test.
Where testable logic goes
- Put logic you want to test in plain
Services/ classes (e.g. StatsNotifier,
ScreenshotCarousel). These construct fine off-engine.
- ECS
Systems/ cannot be instantiated off-engine at all. When a system holds logic worth
testing, extract it into a plain Services/ class and have the system delegate to it.
- For UI behavior that can't be unit-tested, drive the live mod UI over Gameface CDP instead (see
the project's CDP live-UI memory). Off-engine xUnit and live CDP are complementary, not rivals.
What loads off-engine
A [ModuleInitializer] AssemblyResolve probe (GameAssemblyResolver) loads game DLLs on demand
from CSII_MANAGEDPATH (the game's Managed folder). Pure managed assemblies load fine this way:
Colossal.Core, Colossal.UI.Binding, and Game.dll. So domain records (Screenshot,
CreatorStats, ...) and pure managed structs like Game.UI.Localization.LocalizedString are
test-constructible (the test project has InternalsVisibleTo).
Caveat: engine enums in [InlineData] break discovery
An engine type loads in a test body (the probe is active for executing code) but not when
xUnit parses an attribute's argument blob. So a [Theory] whose [InlineData(...)] embeds an
engine-assembly enum value (e.g. GameMode.MainMenu from Game.dll) fails at discovery with
System.IO.FileNotFoundException: Could not load file or assembly 'Game': xUnit reads the blob via
CustomAttributeData reflection, a path GameAssemblyResolver does not cover. Use a single
[Fact] with the enum values inside the method body instead, e.g.
Assert.True(SlideshowConductor.ShouldRefreshOnReturnToMenu(GameMode.Game, GameMode.MainMenu)).
What fails off-engine, and the seam to use instead
The probe cannot save you from code that makes Unity native calls or loads engine-only types.
Never let a test touch these directly; depend on a mod-owned interface and inject a fake.
- HTTP /
HttpQueries. Its static constructor calls SystemInfo.deviceUniqueIdentifier
(native) and its methods take UnityWebRequest, so instantiating it off-engine fails. Depend on
IHallOfFameApi and inject FakeApi; never new HttpQueries. Constructing the nested
HttpQueries.JsonError is safe, because a nested type does not trigger the enclosing type's static
constructor.
- Logging /
Colossal.Logging.ILog. Do not depend on it. ILog uses C# default interface
methods that the net48 CLR cannot load (TypeLoadException the moment ILog is touched, e.g.
via LogManager.GetLogger), and LogManager is engine-bound regardless of runtime. Changing the
test TargetFramework does not help; the blocker is engine-boundness, not the CLR. Depend on
the mod-owned IModLog seam (HallOfFame/Logging/) and inject FakeModLog instead.
Fakes
Fakes are handwritten and kept to the smallest viable shape; no mocking library is used. The
convention (see HallOfFame.Tests/Http/FakeApi.cs and HallOfFame.Tests/Logging/FakeModLog.cs):
- One settable delegate per method the test actually wires up.
- Every method left unwired throws
NotImplementedException (or is a no-op for pure side effects
like logging), so an unexpected call fails loudly instead of passing silently.
The game's own test framework
Cities: Skylines II ships its own in-engine test framework, but none of it is reachable from this
off-engine project. If you are wondering whether to reuse it, read
game-test-framework.md.
