> For the complete documentation index, see [llms.txt](https://morningheartgames.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/tests-verification.md). # Tests and Verification > Online doc: The test suite is executable documentation for repository maintainers. It lives under `DevelopmentTests/GameplayAbilityToolkit/`, outside the copied `GameplayAbilityToolkit/` package, so runtime users do not see maintainer tests in normal imports. Test assemblies are still gated so development projects only compile them when explicitly enabled. ## What It Covers | Area | Test folders | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Core contracts | `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor`, `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/PlayMode`, `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Performance` | | Abilities | `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Abilities` | | Effects | `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Effects` | | Attributes | `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Attributes` | | Tags | `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Tags` | | Targeting | `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Targeting` | | Tasks | `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Tasks` | | Montage | `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Montage` | | Input buffering | `DevelopmentTests/GameplayAbilityToolkit/Core.Input.Buffering.Tests/Editor` | | Unity Input System | `DevelopmentTests/GameplayAbilityToolkit/InputSystem.Tests/Editor` | | Runtime UI | `DevelopmentTests/GameplayAbilityToolkit/UI.Tests/Editor` | | Game Creator | `DevelopmentTests/GameplayAbilityToolkit/GameCreator.Tests/Editor` | ## When To Use It Use tests when: * You are learning a subsystem and want concrete examples. * You added a custom ability/effect/task/filter/calculator. * You changed project content and need to confirm runtime contracts. * You are preparing an Asset Store update. * You need to explain expected behavior to another developer. ## Editor Setup 1. Open `Tools > Gameplay Ability Toolkit > Dashboard`. 2. Open **Dependencies**. 3. Click **Enable Tests**. Click **Enable Performance Tests** only when you need performance suites. 4. Open `Window > General > Test Runner`. 5. Select `EditMode` for editor tests. 6. Select the relevant assembly or folder. 7. Run focused tests first. 8. Run broader Core tests before committing. 9. Use `PlayMode` tests for lifecycle or scene/runtime behavior. Optional integrations require their dependencies. If Unity cannot compile an optional assembly because a dependency is missing, disable or remove that package-specific module for the project setup. ## Assembly Gates Test asmdefs must include: | Gate | Why it exists | | --------------------------------------------- | ---------------------------------------------------------------------- | | `optionalUnityReferences: ["TestAssemblies"]` | Marks the assembly as a Unity test assembly. | | `GAS_ENABLE_TESTS` | Keeps tests out of normal package imports. | | `GAS_HAS_UNITY_TEST_FRAMEWORK` | Requires Unity Test Framework before compiling test code. | | `GAS_ENABLE_PERFORMANCE_TESTS` | Enables performance tests only when requested. | | `GAS_HAS_PERFORMANCE_TESTING` | Requires Unity Performance Testing before compiling performance tests. | Optional integration tests keep their integration gate as well, such as `GAS_ENABLE_GAMECREATOR` or `GAS_ENABLE_INPUT_SYSTEM`. ## Test Reading Strategy | Need | Where to look | | ------------------------------------ | ------------------------------------------------------------------------ | | How ability activation should behave | `AbilityLifecycleContractTests.cs`, `AbilityGrantActivationDeepTests.cs` | | How effect lifecycle/stacking works | `EffectLifecycleContractTests.cs`, `EffectStackingRemovalDeepTests.cs` | | How attribute clamps and hooks work | `AttributeClampContractTests.cs`, `AttributeChangeHookTests.cs` | | How tags and tag queries work | `GameplayTagQueryContractTests.cs`, `RuntimeTagsTests.cs` | | How input queues work | `InputQueueContractTests.cs` | | How targeting collectors work | `GeneralTargetCollectorTests.cs`, `MultiTargetCollectorTests.cs` | | How task cleanup works | `AbilityTaskContractTests.cs` | | How cue/montage/logging interact | `TargetingCueMontageLoggingDeepContractTests.cs` | ## Acceptance Checklist For Project Content * A new attribute set has a focused test or manual verification scene. * A new damage effect is tested against missing target attributes and normal targets. * A new duration effect is tested for application, stacking, expiration, and removal. * A new ability is tested for grant, activation failure, success, cancellation, cost, and cooldown. * A new target collector is tested for no target, one target, multiple targets, self filtering, and layer/tag filtering. * A new UI panel is tested with missing ASC and live ASC. ## Debugging With Tests 1. Reproduce the issue in a small test before debugging a full scene. 2. Create test assets in memory where possible. 3. Use stable tags and attribute definitions. 4. Assert both state and emitted events. 5. Add regression tests for every bug fixed in custom project code. ## Common Mistakes | Mistake | Result | Fix | | -------------------------------------- | --------------------------- | ---------------------------------------- | | Only testing happy paths | Failures surprise designers | Add failure reason checks. | | Testing full scenes for every contract | Slow and brittle tests | Use focused EditMode tests. | | Ignoring optional dependency failures | CI noise | Separate optional integration test runs. | | Reading tests as internal-only | Missed examples | Treat tests as behavior reference. | ## Related Pages * [AbilitySystemComponent](/docs/gameplay-ability-toolkit/subsystems/ability-system-component.md) * [Abilities](/docs/gameplay-ability-toolkit/subsystems/abilities.md) * [Effects](/docs/gameplay-ability-toolkit/subsystems/effects.md) * [Targeting](/docs/gameplay-ability-toolkit/subsystems/targeting.md) * [Unity Input System](/docs/gameplay-ability-toolkit/integrations/unity-input-system.md) * [Game Creator](/docs/gameplay-ability-toolkit/integrations/game-creator.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/tests-verification.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.