test-writing-guide

Guide for writing test code for Unity projects.

Rules

• Before modifying any test file, check if the editor is in Play Mode. If it is, stop it using the unity_play_control tool first.
• Never create .meta files. Unity editor creates them automatically.
• When a test creates a GameObject or instantiates a prefab, add [CreateScene] to the test method (not required if [LoadScene] is already present).
• When adding a test seam to production code (e.g., an internal accessor or a virtual override point to support injection), always wrap it with #if UNITY_INCLUDE_TESTS … #endif so it is excluded from non-test builds:

  #if UNITY_INCLUDE_TESTS
  internal void SetStateForTest(State state) => _state = state;
  #endif
  

Categories

• When implementing tests designed as integration tests, add [Category("Integration")] to the test method.
• When implementing tests designed as visual verification tests, add [Category("VisualVerification")] to the test method.
• When implementing tests designed as acceptance tests (marked (acceptance test) in the test case design), add [Category("Acceptance")] to the test method.
• For test methods that test the internal visibility method, add [Category("Internal")].
• For test methods that depend on animation timing or other timing-sensitive conditions that may cause instability on slow CPUs, add [Category("IgnoreCI")].
• For test methods that specify the GameViewResolution attribute, add [Category("IgnoreCI")].

Multi-frame tests

When a game mechanic across frames (e.g., playing a card and waiting for its resolution), wait for the step to finish before asserting — not at a fixed frame count.

await DragCard(Cards[1], Enemies[0]);
while (battleDirector.IsPlaying) // wait until the played action fully resolves
    await Awaitable.NextFrameAsync();
Assert.That(battleState.Enemies[0].Hp, Is.LessThan(hpBefore));

• To confirm step completion, use a production-side state machine or a "busy" signal (IsPlaying, coroutine flag, etc.). Do not use a fixed number of frames or WaitForSeconds.
• When UniTask is available, UniTask.WaitUntil and UniTask.WaitUntilValueChanged are alternatives to the while loop:

  await UniTask.WaitUntil(() => isActive == false);
  await UniTask.WaitUntilValueChanged(this, x => x.isActive);
  

• When an operation triggers a deferred Destroy or UI rebuild, advance one extra await Awaitable.NextFrameAsync() before asserting on the new hierarchy.