From d60a46c21793856abf592ce1342264570a1c920a Mon Sep 17 00:00:00 2001 From: SlamBamActionman <83650252+SlamBamActionman@users.noreply.github.com> Date: Wed, 13 May 2026 16:16:15 +0200 Subject: [PATCH 1/5] Create your-first-integration-test.md --- .../your-first-integration-test.md | 155 ++++++++++++++++++ 1 file changed, 155 insertions(+) create mode 100644 src/en/ss14-by-example/your-first-integration-test.md diff --git a/src/en/ss14-by-example/your-first-integration-test.md b/src/en/ss14-by-example/your-first-integration-test.md new file mode 100644 index 0000000000..e5e21d0cb1 --- /dev/null +++ b/src/en/ss14-by-example/your-first-integration-test.md @@ -0,0 +1,155 @@ +# Your First Integration Test + +In this guide you will learn about integration testing and how to create an integration test. + +### What is integration testing? + +**Integration testing** is a useful tool to ensure that changes to one part of the game doesn't unexpectedly cause another part of the game to change too. +It can catch unintended behavior, bugs and even rare game-crashing errors when used properly! +This is achieved through **integration tests**, which basically run short simulations of the game and makes sure ingame values match what the test expects. + +An example would be changing a Cargo order to cost less. +If you have an integration test that compares order costs to sell values, you'll be able to automatically catch if this change would result in an infinite money loop! + +Integration tests are ran on all pull requests submitted to the SS14 repository and all tests must pass for a PR to be mergeable. +You can also run tests locally in your IDE (useful if you fail a specific test when submitting a PR). + +### The structure of a test + +Tests generally follow this flow: + +- Select which base test class the test should use. +- Define test-specific prototypes & settings. +- Spawn entities and retrieve components/systems to test. +- Assert default values (i.e. "are the starting values what I expect?"). +- Do the test scenario. +- Assert that values have changed (i.e. "did the test result in what I expected?"). + +We will go through this flow in the tutorial below: + +## Making your first test + +In this tutorial we are going to make a test to check that hugging works. +Hugging is done via `InteractionPopupSystem` and `InteractionPopupComponent`, and when a hug is performed `InteractionPopupComponent.LastInteractTime` should get updated to a new value. + +We decide our test will try to simulate a hug and then verify that it happened by checking if `LastInteractTime` updated. + +### Setup + +Integration tests are created in a relevant area folder in `Content.IntegrationTests/Tests`, so we create a new folder `InteractionPopup` and a new C# script `InteractionPopupTest`. + +Our first decision will be to choose which base test class to use. +These are used to handle boilerplate (e.g. setting up and disposing of finished tests) and enable specific functionalities (such as spawning a default player mob or a walkable grid). +Some choices include `GameTest`, `InteractionTest` and `MovementTest`. + +For our test, we will use `InteractionTest` as our base class. +It spawns a simple player mob with a single hand and has a lot of helper functions related to interactions that we can make use of later: +``` +using Content.IntegrationTests.Tests.Interaction; + +namespace Content.IntegrationTests.Tests.InteractionPopup; + +public sealed class InteractionPopupTest : InteractionTest +{ + +} +``` +We will also create the method inside of which our test is run, `HugTest()`. The method requires two properties: +- A `[Test]` attribute, to mark the method as a test. +- The `async` keyword, since the test simulation will run alongside other tests, and some behaviors (such as spawning) will take time to run. +``` +using Content.IntegrationTests.Tests.Interaction; + +namespace Content.IntegrationTests.Tests.InteractionPopup; + +public sealed class InteractionPopupTest : InteractionTest +{ + + [Test] + public async Task HugTest() + { + + } +} +``` +With this, the test should now be visible in the Tests tab of your IDE! +Exactly where the Tests tab is located depends on the IDE you use, but if once found you should be able to see `InteractionPopupTest` among the other test folders. +You can even run the test if you want, though since the test is empty it will just return a Success. + +### Spawning an entity +Since `InteractionTest` handles spawning the player mob automatically, our first actual step in creating the test will be to spawn in the mob we will hug. We have two options here: + +- Rely on an existing mob prototype with `InteractionPopupComponent`. +- Create a dummy prototype inside the test class to only use for this test. + +We will choose the first one since the `MobHuman` prototype is a base mob that we expect will always be huggable, and using it additionally makes the test keep an eye on if that prototype ever accidentally gets changed. + +`InteractionTest` has a built-in spawning method `SpawnTarget`, which spawns an entity one tile next to the player entity and sets it as the target for any future interactions of the player entity. + +``` +[Test] +public async Task HugTest() +{ + var urist = await SpawnTarget("MobHuman"); +} +``` + +### Checking for components + +`InteractionTest` has a shorthand to get the server componet in the method `Comp(NetEntity? target)`. There is similarly a shorthand for the `NetEntity`, `FromServer(EntityUid suid)`, resulting in: + +``` +[Test] +public async Task HugTest() +{ + var urist = await SpawnTarget("MobHuman"); + var interactionPopupComp = Comp(urist); +} +``` + +### Asserts + +What we want to do is *assert* that the property has the value we expect it to have, and if it doesn't the test should fail. +The `Assert` class has several methods for this, but the most common is `Assert.That` which allows comparing values of properties. + +`InteractionPopupComponent` has the property `LastInteractTime`, and while we can *assume* that it will always start at the default value, core to testing is never assuming if you can test it. We can check this with `Is.Default`. + +``` +[Test] +public async Task HugTest() +{ + var urist = await SpawnTarget("MobHuman"); + var interactionPopupComp = Comp(urist); + + Assert.That(interactionPopupComp.LastInteractTime, Is.Default); +} +``` + +### Simulation & Checking + +`InteractionTest` has many helper methods used for simulating interactions. +With our testcase being simply clicking on the huggable entity, we can use of the basic `await Interact();` method to simulate hugging. +Since the player entity spawns with one free hand, we should expect a basic interaction to result in the `InteractionPopupSystem.InteractHandEvent` event subscription triggering, and therefore `LastInteractTime` should be updated to the current time: + +``` +[Test] +public async Task HugTest() +{ + var urist = await SpawnTarget("MobHuman"); + var interactionPopupComp = Comp(urist); + + Assert.That(interactionPopupComp.LastInteractTime, Is.Default); + + var previousInteractTime = interactionPopupComp.LastInteractTime; + + await Interact(); // Perform the hug! + + Assert.That(interactionPopupComp.LastInteractTime, !Is.EqualTo(previousInteractTime)); +} +``` + +If you run `HugTest()` test now, it should pass! +If any future changes accidentally makes another empty-handed action override hugging, this test will now be able to catch that. You made your first test! + +This tutorial only brushes the surface of how tests can be made. +The test can expand to cover trying to hug with an item in the player's hand, hugging all different player species, checking that hugs don't come out faster than the cooldown and much more. From 4d5d39e7c64631e1e584e8615bc0d4ce99254bf2 Mon Sep 17 00:00:00 2001 From: SlamBamActionman <83650252+SlamBamActionman@users.noreply.github.com> Date: Wed, 13 May 2026 16:17:20 +0200 Subject: [PATCH 2/5] Update SUMMARY.md --- src/SUMMARY.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 70ce6f0fc7..da434ccd58 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -59,6 +59,7 @@ SS14 By Example - [UI and You](en/ss14-by-example/ui-and-you.md) - [UI Cookbook](en/ss14-by-example/ui-and-you/ui-cookbook.md) - [UI Survival Guide](en/ss14-by-example/ui-survival-guide.md) +- [Your First Integration Test](en/ss14-by-example/your-first-integration-test.md) - [Converting Oldbody to Nubody](en/ss14-by-example/converting-oldbody-to-nubody.md) Robust Toolbox From fe0e9b56139fb3f53484dc71d1071d8b52c9791c Mon Sep 17 00:00:00 2001 From: SlamBamActionman <83650252+SlamBamActionman@users.noreply.github.com> Date: Wed, 13 May 2026 16:23:02 +0200 Subject: [PATCH 3/5] Update your-first-integration-test.md --- src/en/ss14-by-example/your-first-integration-test.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/en/ss14-by-example/your-first-integration-test.md b/src/en/ss14-by-example/your-first-integration-test.md index e5e21d0cb1..4578090b25 100644 --- a/src/en/ss14-by-example/your-first-integration-test.md +++ b/src/en/ss14-by-example/your-first-integration-test.md @@ -96,7 +96,7 @@ public async Task HugTest() ### Checking for components -`InteractionTest` has a shorthand to get the server componet in the method `Comp(NetEntity? target)`. There is similarly a shorthand for the `NetEntity`, `FromServer(EntityUid suid)`, resulting in: +`InteractionTest` has a helper method to get the server component: `Comp(NetEntity? target)`. This also checks that the component exists on the entity, and fails the test if it doesn't. ``` [Test] @@ -128,8 +128,9 @@ public async Task HugTest() ### Simulation & Checking `InteractionTest` has many helper methods used for simulating interactions. -With our testcase being simply clicking on the huggable entity, we can use of the basic `await Interact();` method to simulate hugging. -Since the player entity spawns with one free hand, we should expect a basic interaction to result in the `InteractionPopupSystem.InteractHandEvent` event subscription triggering, and therefore `LastInteractTime` should be updated to the current time: +With our testcase being simply clicking on the huggable entity, we can use of the basic `await Interact();` method to simulate hugging. Since we spawned the `MobHuman` with `SpawnTarget` earlier, all we have to do is run the method! + +Since the player entity spawns with one free hand, we should expect a basic interaction to result in the `InteractionPopupSystem.InteractHandEvent` event subscription triggering, and therefore `LastInteractTime` should be updated to the current time. We assert that the previous `LastInteractTime` should not be equal to the new `LastInteractTime`. ``` [Test] From b44edf5f550decf4c6abb0ab71e38f9c74d6021d Mon Sep 17 00:00:00 2001 From: SlamBamActionman <83650252+SlamBamActionman@users.noreply.github.com> Date: Wed, 13 May 2026 16:23:26 +0200 Subject: [PATCH 4/5] the --- src/en/ss14-by-example/your-first-integration-test.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/en/ss14-by-example/your-first-integration-test.md b/src/en/ss14-by-example/your-first-integration-test.md index 4578090b25..35369298d4 100644 --- a/src/en/ss14-by-example/your-first-integration-test.md +++ b/src/en/ss14-by-example/your-first-integration-test.md @@ -149,7 +149,7 @@ public async Task HugTest() } ``` -If you run `HugTest()` test now, it should pass! +If you run the `HugTest()` test now, it should pass! If any future changes accidentally makes another empty-handed action override hugging, this test will now be able to catch that. You made your first test! This tutorial only brushes the surface of how tests can be made. From 7ef32b0ef27cf74de6c25060cc5dd967bee9660e Mon Sep 17 00:00:00 2001 From: SlamBamActionman <83650252+SlamBamActionman@users.noreply.github.com> Date: Thu, 14 May 2026 12:52:31 +0200 Subject: [PATCH 5/5] Update your-first-integration-test.md --- .../your-first-integration-test.md | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/src/en/ss14-by-example/your-first-integration-test.md b/src/en/ss14-by-example/your-first-integration-test.md index 35369298d4..6882414977 100644 --- a/src/en/ss14-by-example/your-first-integration-test.md +++ b/src/en/ss14-by-example/your-first-integration-test.md @@ -110,7 +110,7 @@ public async Task HugTest() ### Asserts What we want to do is *assert* that the property has the value we expect it to have, and if it doesn't the test should fail. -The `Assert` class has several methods for this, but the most common is `Assert.That` which allows comparing values of properties. +The `Assert` class enables this, with the method [`Assert.That`](https://docs.nunit.org/articles/nunit/writing-tests/assertions/assertion-models/constraint.html) being the preferred method of evaluating property values. `InteractionPopupComponent` has the property `LastInteractTime`, and while we can *assume* that it will always start at the default value, core to testing is never assuming if you can test it. We can check this with `Is.Default`. @@ -154,3 +154,17 @@ If any future changes accidentally makes another empty-handed action override hu This tutorial only brushes the surface of how tests can be made. The test can expand to cover trying to hug with an item in the player's hand, hugging all different player species, checking that hugs don't come out faster than the cooldown and much more. + +## Extra Credit: How Do Tests Work Under The Hood? + +There is a lot going into the setup of integration testing that the test base classes do automatically when initialized. +It can be good to understand this process since a lot can be modified and extended, and there are several helper methods that can save time and make your tests much better. + +`PoolManager` is a static core class that manages server-client simulation relationships, and is used for tests, benchmarks and map rendering. +For tests specifically it allows for client-servers to be reused for multiple tests and for tests to be run in parallel, instead of constantly starting and shutting down such systems. + +It's unlikely you will access `PoolManager` yourself, but a key property that all integration tests make use of is the `TestPair` class. +`TestPair` gives access to the Client and Server instances and therefore the ability to set CVars, resolve manager/system dependencies and map management. +The test base classes all make use of this to create helper methods and properties. + +It is strongly recommended you check out `GameTest.Entities.cs`, `GameTest.Pair.cs` `InteractionTest.Helpers.cs`, `Pair/TestPair.Helpers.cs` and `Pool/TestPair.Helpers.cs` to see what helper methods are available!