punkfuncgames/testing

Testing Reference

Location: Each package has its own Tests/ directory under Packages/com.punkfuncgames.<module>/Tests/. Template-level tests remain at Assets/Scripts/PunkFuncGames/GameTemplate/Tests/. Guide: Tests/TESTING_GUIDE.md Namespace: PunkFuncGames.<Module>.Tests.EditMode.* / PunkFuncGames.<Module>.Tests.PlayMode.*

TDD Mandate

100% test coverage goal. Every code change MUST include tests:

• New code: Write tests FIRST (Red-Green-Refactor)
• Modified code: Update existing tests + add new tests for changed behavior
• Bug fixes: Write a failing test that reproduces the bug, then fix

Test Integrity — No False Greens

A false green is a passing test that masks a real bug by working around it instead of fixing it. False greens are worse than failing tests because they create false confidence.

Root Cause Fixing (Mandatory)

When a test fails, the fix MUST target the root cause:

1. Trace the failure to its origin — step through the code path mentally or with a debugger
2. Fix the bug where it lives — if the bug is in a shared utility (e.g., BigDouble, SerializableBigDouble, helper class), fix it THERE
3. Write tests for the root fix — prove the underlying bug is fixed with dedicated tests
4. Then re-run the original failing test — it should now pass without any workaround

FORBIDDEN Workaround Patterns

These are signs of a false green — NEVER do these to make a test pass:

| Pattern | Why It's Wrong | |---------|---------------| | Adding guards in consumer code to avoid triggering a dependency bug | Masks the bug — other consumers still hit it | | Changing test expectations to match buggy behavior | Tests now validate the bug instead of the contract | | Adding try/catch around buggy code to swallow errors | Hides the failure, bug persists silently | | Mocking away the layer that contains the bug | Test passes but production code still broken | | Special-casing test data to avoid the failing code path | Reduces test coverage, bug still exists for other inputs |

Decision Flowchart

Test fails
  → Trace the root cause
    → Bug is in THIS class?
      → Fix it here, test passes ✓
    → Bug is in a DEPENDENCY (utility, shared lib, lower layer)?
      → Fix the dependency FIRST
      → Write tests for the dependency fix
      → Re-run original test — should pass now ✓
      → Optionally add defensive guard in consumer as SUPPLEMENTARY protection
    → Bug is in the TEST itself (wrong expectation, bad mock setup)?
      → Fix the test, verify it tests the right contract ✓

Defensive Guards Policy

Defensive guards in consumer code are ONLY acceptable when:

1. The root cause has ALREADY been fixed and tested
2. The guard adds semantic clarity (e.g., explicit infinity check before comparison)
3. The guard protects against potential future regressions

A defensive guard is NEVER a substitute for a root cause fix.

Real Example — BigDouble Infinity Bug

Wrong approach (false green):

// CurrencyContainer.SetCap — workaround added to avoid BigDouble operator bug
if (!BigDouble.IsPositiveInfinity(_cap.Value) && _amount.Value > _cap.Value)
// Test passes, but BigDouble.operator > is STILL broken for all other callers

Correct approach:

// 1. Fix BigDouble.operator > to handle infinity FIRST
public static bool operator >(BigDouble a, BigDouble b)
{
    if (IsNaN(a) || IsNaN(b)) return false;
    if (IsInfinity(a) || IsInfinity(b)) return a.Mantissa > b.Mantissa; // ROOT FIX
    // ... rest of operator
}

// 2. Write BigDoubleComparisonTests proving the fix
[Test]
public void GreaterThan_FiniteVsPositiveInfinity_ReturnsFalse()
{
    Assert.That(new BigDouble(500) > BigDouble.PositiveInfinity, Is.False);
}

// 3. THEN optionally keep the guard in CurrencyContainer as supplementary defense

Test Framework Stack

| Library | Role | |---------|------| | NUnit | [TestFixture], [Test], [SetUp], [TearDown] | | NSubstitute | Substitute.For<T>(), Arg.Any<T>(), .Received() | | UniTask | async Task return with UniTask APIs in body (NUnit doesn't support async UniTask) | | R3 | ReactiveProperty<T> testing, .Subscribe() | | MessagePipe | IPublisher<T> / ISubscriber<T> mock verification | | VContainer | ContainerBuilder for integration tests |

FORBIDDEN in Tests

• IEnumerator / [UnityTest] with IEnumerator return / yield return / coroutines
• async UniTask as test method return type (NUnit doesn't support it — use async Task instead)
• Task.Delay / Thread.Sleep (use UniTask.Delay)
• ValueTask in production code
• Assert.AreEqual — use Assert.That constraint syntax
• Debug.Log — use assertions
• Static state between tests

Code Style in Tests

All rules from the code-style skill apply to test code. Key reminders:

• No var — use explicit types: string name = "test"; not var name = "test";
• One attribute per line: [Test] on one line, [Category("X")] on the next
• Unity object null checks: if (obj) / if (!obj) not obj != null

EditMode vs PlayMode

EditMode (default): Pure C# services, models, calculations, reactive properties, commands, events PlayMode (only when needed): MonoBehaviour lifecycle, GameObjects, VContainer scene resolution, Views, Time.timeScale, Physics

Test File Template — EditMode

using System;
using MessagePipe;
using NSubstitute;
using NUnit.Framework;

namespace PunkFuncGames.GameTemplate.Tests.EditMode.<Module>
{
    [TestFixture]
    public sealed class MyServiceTests
    {
        private IDependency _mockDep;
        private IPublisher<MyEvent> _mockPublisher;
        private MyService _service;

        [SetUp]
        public void SetUp()
        {
            _mockDep = Substitute.For<IDependency>();
            _mockPublisher = Substitute.For<IPublisher<MyEvent>>();
            _service = new MyService(_mockDep, _mockPublisher);
        }

        [TearDown]
        public void TearDown()
        {
            _service?.Dispose();
        }
    }
}

Test File Template — PlayMode (UniTask)

using System.Threading;
using Cysharp.Threading.Tasks;
using NUnit.Framework;

namespace PunkFuncGames.GameTemplate.Tests.PlayMode.<Module>
{
    [TestFixture]
    public sealed class MyIntegrationTests
    {
        private CancellationTokenSource _cts;

        [SetUp]
        public void SetUp()
        {
            _cts = new CancellationTokenSource();
        }

        [TearDown]
        public void TearDown()
        {
            _cts?.Cancel();
            _cts?.Dispose();
        }

        [Test]
        public async Task Method_Condition_Expected()
        {
            await UniTask.NextFrame(_cts.Token);
            Assert.That(result, Is.EqualTo(expected));
        }
    }
}

Async in EditMode (Synchronous Mocks)

When mocks return UniTask.CompletedTask, async completes synchronously:

_mockDep.DoAsync(Arg.Any<CancellationToken>()).Returns(UniTask.CompletedTask);
_service.ProcessAsync(CancellationToken.None).Forget();
_mockDep.Received(1).DoAsync(Arg.Any<CancellationToken>());

UniTask Wait Patterns (PlayMode)

await UniTask.NextFrame(_cts.Token);                    // Next frame
await UniTask.DelayFrame(10, cancellationToken: ct);    // N frames
await UniTask.Delay(TimeSpan.FromSeconds(1), DelayType.Realtime, cancellationToken: ct);
await UniTask.WaitUntil(() => ready, cancellationToken: ct).Timeout(TimeSpan.FromSeconds(5));
await prop.Where(v => v == target).FirstAsync(ct);      // Reactive wait

MockFactory (EditMode/Helpers/MockFactory.cs)

| Method | Returns | Key Parameters | |--------|---------|----------------| | CreateSteamService() | ISteamService | initialized, connected, loggedIn, steamId, personaName | | CreateSteamCloudService() | ISteamCloudService | cloudEnabled, quotaTotal, quotaAvailable | | CreateSteamAchievementService() | ISteamAchievementService | Defaults: all async → success | | CreateSerializer() | ISaveSerializer | JSON-backed for testing | | CreateEncryption() | ISaveEncryption | enabled (XOR when true, passthrough when false) | | CreateLocalizationService() | ILocalizationService | currentLanguage, strings dict | | CreatePublisher<T>() | IPublisher<T> | Generic | | CreateSubscriber<T>() | ISubscriber<T> | Generic | | CreateTriggeredSubscriber<T>() | (ISubscriber<T>, Action<T>) | Subscriber + manual trigger | | CreateGameStateService() | IGameStateService | initialState (reactive, auto-updates) | | CreateAnalyticsService() | IAnalyticsService | enabled, hasConsent |

TestFixtures (EditMode/Helpers/TestFixtures.cs)

| Method | Returns | |--------|---------| | CreateGameSettings() | GameSettings (ScriptableObject) | | CreateSteamSettings() | SteamSettings (ScriptableObject) | | CreateLocalizationSettings() | LocalizationSettings (ScriptableObject) | | CreateSaveData() | SaveData | | CreateSaveMetadata() | SaveMetadata | | CreateTestBytes() | byte[] | | CreateTestSerializableObject() | TestSerializableObject |

Config + Data Testing Pattern

All ScriptableObject configs follow the Config + Data pattern in tests:

1. Create the ScriptableObject instance:

FloatingTextConfig config = ScriptableObject.CreateInstance<FloatingTextConfig>();

2. Initialize the data struct directly:

config.data = new FloatingTextConfigData
{
    duration = 1f,
    moveDistance = 2f,
    defaultColor = Color.white,
    prewarmCount = 5,
    maxPoolSize = 20
};

3. Access fields via .data.fieldName:

Assert.That(config.data.duration, Is.EqualTo(1f));

Key rules:

• Config SOs are thin wrappers with public SomeData data;
• Data structs are [Serializable] public struct with public camelCase fields, no methods
• Logic lives in extension methods on the Data struct
• No CreateRuntime() factories — use ScriptableObject.CreateInstance<T>() + struct initializer
• TestFixtures methods return SOs with data struct pre-initialized

Examples across modules:

// LogSettings
LogSettings logSettings = ScriptableObject.CreateInstance<LogSettings>();
logSettings.data = new LogSettingsData { minimumLevel = LogLevel.Debug, historyCapacity = 256 };

// PoolConfig
PoolConfig poolConfig = ScriptableObject.CreateInstance<PoolConfig>();
poolConfig.data = new PoolConfigData { pools = new List<PoolEntryData> { new PoolEntryData { poolId = "Bullet", initialSize = 10 } } };

// CurrencyDefinition
CurrencyDefinition def = ScriptableObject.CreateInstance<CurrencyDefinition>();
def.data = new CurrencyDefinitionData { displayNameKey = "Gold", hasCap = false, showInUI = true };

// AudioSettings
AudioSettings audioSettings = ScriptableObject.CreateInstance<AudioSettings>();
audioSettings.data = new AudioSettingsData { sfxPoolSize = 16, defaultMasterVolume = 1f };

PlayModeTestHelpers (PlayMode/Helpers/PlayModeTestHelpers.cs)

await PlayModeTestHelpers.WaitForConditionAsync(() => ready, timeout: 5f, ct);
await PlayModeTestHelpers.WaitFramesAsync(10, ct);
await PlayModeTestHelpers.WaitForRealSecondsAsync(1f, ct);
GameObject go = PlayModeTestHelpers.CreateTestObject("Name");
PlayModeTestHelpers.DestroyTestObject(go);

Naming Convention

Class: {ClassUnderTest}Tests Method: {MethodOrProperty}_{Condition}_{ExpectedResult}

Examples:

• GetProductionRate_NoProducers_ReturnsZero
• Constructor_NullWalletService_ThrowsArgumentNullException
• Count_InitialState_ReturnsZero
• AsyncMethod_Cancelled_ThrowsOperationCanceledException

Coverage Checklist (Per Public Class)

Services:

• Constructor null guards (one per parameter)
• Initial state of all public/reactive properties
• Every public method: happy path + error/edge cases + boundary values
• Every branch in conditional logic
• Event publishing: correct type/data, NOT published on failure
• Reactive property emissions on state changes
• Observable exposure (not null)
• Dispose behavior + double-dispose safety
• Mock interaction verification

Models: Default values, property setters, serialization round-trip, equality Events: Factory methods, field population Commands: ExecuteAsync, UndoAsync, Name, TryMerge Views (PlayMode): Init, ShowAsync/HideAsync, model binding, cleanup Configs: Default values, validation, data struct initialization (no runtime factories — use ScriptableObject.CreateInstance<T>() + struct init)

NSubstitute Quick Reference

Substitute.For<IService>()                              // Create mock
mock.Method().Returns(value)                            // Return value
mock.AsyncMethod(ct).Returns(UniTask.CompletedTask)     // Async return
mock.AsyncMethod(ct).Returns(UniTask.FromResult(val))   // Async with result
Arg.Any<T>()                                            // Match any
Arg.Is<T>(v => v > 0)                                   // Match predicate
mock.Received(1).Method()                               // Verify called once
mock.DidNotReceive().Method()                           // Verify not called
mock.ClearReceivedCalls()                               // Reset call tracking
mock.When(x => x.Method()).Do(ci => ...)                // Capture/callback

Assert Quick Reference

Assert.That(actual, Is.EqualTo(expected))               // Equality
Assert.That(condition, Is.True / Is.False)              // Boolean
Assert.That(obj, Is.Null / Is.Not.Null)                 // Null check
Assert.That(value, Is.GreaterThan(n))                   // Comparison
Assert.That(list, Contains.Item(item))                  // Contains
Assert.That(list, Has.Count.EqualTo(n))                 // Count
Assert.That(obj, Is.InstanceOf<T>())                    // Type check
Assert.Throws<T>(() => code())                          // Sync throws
Assert.ThrowsAsync<T>(async () => await code())         // Async throws
Assert.DoesNotThrow(() => code())                       // No throw
Assert.That(val, Is.EqualTo(exp).Within(0.001f))        // Tolerance

Assembly Definitions

EditMode (Tests.EditMode.asmdef): Editor-only, NUnit + NSubstitute + Newtonsoft.Json + R3 + DOTween PlayMode (Tests.PlayMode.asmdef): All platforms, adds MessagePipe.VContainer + ObservableCollections + VContainer

Existing Test Coverage (43 test files)

EditMode (33 files): Idle (9), Services (9), UnlockCondition (4), Serialization (3), FloatingText (2), Math (1), Pool (2), Helpers (2) PlayMode (10 files): FloatingText (3), Integration (3), Services (3), Helpers (1)