
## What is unit testing + why should I do it?

The best way of thinking about unit tests is that they should be designed to test small pieces of your systems in isolation. In Unity, this might be a single script or a helper function.

Unit tests tend to be faster to write since you're focused on one specific piece rather than how individual pieces fit together.

While there's always a time and place for larger end-to-end tests, typically when building a game you'll want to prioritise creating quick tests for complicated logic - most of the time just to sanity-check it.

## What is the Unity Test Framework?

The Unity Test Framework is a convenient test runner built into Unity and based off the popular [NUnit framework](https://nunit.org). Unity Test Framework abstracts away the complicated logic required to build and load your game before tests, allowing you to create Play-mode tests and Edit-mode tests. In this post we'll be focusing on Play-mode tests.

It is available [as a package](https://docs.unity3d.com/Packages/com.unity.test-framework@1.3/manual/index.html) that you can install through the Unity Package Manager.

In this post we'll go over how to use the Unity Test Framework to write good tests. You'll need to set up the test runner and assemblies as [described in the Unity docs](https://docs.unity3d.com/Packages/com.unity.test-framework@1.3/manual/getting-started.html) to get started.

## Your first test

For this post, we'll be looking at [real-world tests](https://github.com/TaloDev/unity/tree/develop/Packages/com.trytalo.talo/Tests/Runtime) we created for Talo to illustrate some of these examples. When you create your first test, you'll have a simple script that looks like this:

```csharp
public class MyFirstTest
{
    // A UnityTest behaves like a coroutine in Play Mode. In Edit Mode you can use
    // `yield return null;` to skip a frame.
    [UnityTest]
    public IEnumerator MyFirstTestWithEnumeratorPasses()
    {
        // Use the Assert class to test conditions.
        // Use yield to skip a frame.
        yield return null;
    }
}
```

As you can see, Unity uses [Coroutines](https://docs.unity3d.com/ScriptReference/Coroutine.html) to run tests. Coroutines are great because they allow you to pause execution and wait for actions to happen before resuming.

The `[UnityTest]` attribute decorates the function to allow us to use these coroutines to skip frames or enter Play-mode.

Lets create a test for the `GetProp` function from the following script:

```csharp
public class LiveConfig
{
    private Prop[] props;

    public LiveConfig(Prop[] props)
    {
        this.props = props;
    }

    public T GetProp<T>(string key, T fallback = default(T))
    {
        try
        {
            Prop prop = props.First((prop) => prop.key == key);
            return ((T)Convert.ChangeType(prop.value, typeof(T)));
        }
        catch (Exception)
        {
            return fallback;
        }
    }
}
```

This function simply uses LINQ to search an array of key/value pairs (`Props`) and find the first one with a matching key. It then converts the value of that `Prop` to match the generic type. If we don't find a `Prop` with that key, we should return the fallback instead.

### Testing the GetProp function

Appropriately, our first test should make sure that the function returns the expected result. Here's what that test would look like:

```csharp
[UnityTest]
public IEnumerator GetProp_WithALiveConfigThatHasValues_ReturnsCorrectValue()
{
    var config = new LiveConfig(new[] { new Prop(("gameName", "Crawle")), new Prop(("halloweenEventEnabled", "True")) });

    Assert.AreEqual("Crawle", config.GetProp("gameName", "No name"));

    yield return null;
}
```

The first thing to note is the structure of the function name. NUnit tests typically have a standardised name made of up of 1) the name of the function you're testing, 2) the condition you're testing and 3) the expected outcome.

We're testing that when the `GetProp` function correctly finds the `Prop` with the key we're searching for when the `LiveConfig` has an array of `Props`. We're doing this because the LINQ `First` function throws when searching an empty array.

By using the `Assert` class, we can compare any number of different outcomes. In this case we're doing a simple equality check. Always remember to `yield return null` at the end of your test, to mark the coroutine as complete.

Luckily for us this function is really small and therefore easy to test. We wrote a few more tests to handle the cases for empty arrays, missing keys, etc. You can find all of those in our [GitHub repo](https://github.com/TaloDev/unity/blob/develop/Packages/com.trytalo.talo/Tests/Runtime/LiveConfig/GetPropTest.cs).

## Handling pre-test setup

In the complicated world of game development it's pretty difficult to write totally isolated code. You'll usually have a number of dependencies that need to be in place before you can properly test what you need to test.

NUnit solves this problem by introducing the `[OneTimeSetUp]` attribute that runs the method it decorates before your tests.

The code below highlights a common scenario where you need some sort of "Manager script" to be ready before executing in the scripts that it manages:

```csharp
public class UpdateSaveTest
{
    private TaloManager tm;

    [OneTimeSetUp]
    public void SetUp()
    {
        tm = new GameObject().AddComponent<TaloManager>();
        tm.settings = ScriptableObject.CreateInstance<TaloSettings>();
    }

    [UnityTest]
    public IEnumerator UpdateSave_InOfflineMode_UpdatesTheSaveName()
    {
        var api = new SavesAPI(tm);
        Talo._saves = api;

        api._allSaves.Add(new GameSave() { id = -1, name = "Offline Save" });
        api.WriteOfflineSavesContent(new OfflineSavesContent(api._allSaves.ToArray()));

        _ = api.UpdateSave(-1, "New Name");

        Assert.AreEqual(1, api.GetOfflineSavesContent().saves.Length);
        Assert.AreEqual("New Name", api.GetOfflineSavesContent().saves[0].name);

        yield return null;
    }
}
```

If you've used Talo (and if you haven't - [you should definitely check it out](https://trytalo.com)), you know that it requires a settings asset. This asset is passed to the `TaloManager` which passes these settings down to individual APIs.

Here, we're testing the `SavesAPI`. We need the `SavesAPI` to have a manager and that's what we're setting up in the `SetUp` function before our test runs.

NUnit has a number of [other convenient attributes](https://docs.nunit.org/articles/nunit/writing-tests/setup-teardown/index.html) like `[SetUp]` that runs before _each_ test and `[TearDown]` that runs after _each_ test to keep your test environment clean and avoid flaky tests.

## Quick tips for writing unit tests

Different people have different thoughts on what makes a good unit test. Sometimes testing feels like uncharted territory in the world of game development, but here are some thoughts about how to go about it:

1. Pick your battles. Some things _just work_ so trying to test everything will inevitably just slow you down. For example, test a weird interaction between two items over a basic 2D movement script.
2. Keep your tests small. In Unity, that usually means testing functions within scripts but maybe not the entire script.
3. Mock as much as possible. Don't re-write code you've already written just for a test, try and find clever workarounds to prevent writing duplicate code.

## Closing thoughts

Unit tests bring a level of confidence you otherwise wouldn't have in a piece of code, however they take time to create and need to be maintained going forward.

This post only scratches the surface on helpful attributes and assertions provided by NUnit and the Unity Test Framework. You can test specific platforms, move from Edit-mode to Play-more and more. Check out the [Unity Test Framework docs](https://docs.unity3d.com/Packages/com.unity.test-framework@1.3/manual/index.html) for additional use-cases.

Testing has sometimes felt a bit abstract in game development and we've only just started the process of adding tests to the [Talo Unity SDK](https://github.com/TaloDev/unity) which you can see in our repo.


Unit tests are a quick and easy way of building confidence in any complicated systems you implement into your game.

Testing your game code with the Unity Test Framework


## What is stat tracking?

Stat tracking involves taking a handful of key metrics in your game and updating them in response to player actions. Stat tracking can be really useful for understanding your players or even for [showing-off recap information](https://i.redd.it/hcnnor7alss61.jpg) in blog posts.

After we've finished doing a game jam, we like to do a wrap-up post focusing on some of the stats from our game. During our most recent jam, we worked on a dystopian farming game where you drive around a modded combine harvester. Your combine harvester can take damage from any angle apart from the left flank, where it has a shield that blocks all damage.

To understand how well players understood the mechanic, we tracked the amount of damage blocked as well as the amount of damage taken. In this post, we'll go over how to do that.

![A combine harvester that can block incoming damage from its left side](/blog/stat-tracking-unity/game.png)

## Stat tracking through Talo

Talo provides an easy way to create stats and view them directly in the dashboard. The stat system provides a number of useful constraints to make sure players aren't attempting to cheat and your code is working as expected.

You can use Talo in any modern Unity game by simply importing the SDK through the Unity package manager.

## Set up

Once you've loaded or created a project, go to the package manager (by navigating to `Window > Package Manager`). Click the plus symbol and select "Add package from git url". When prompted, enter the url: `https://github.com/TaloDev/unity-package.git`.

![Choose the add package from git url option in the Package Manager](/blog/stat-tracking-unity/package-manager.png)

We've now added the Talo package to our Unity project. Doing this through git allows you to keep Talo up to date without needing to redownload the zip file and importing it.

Next, if you don't already have a `Resources` folder, create one inside the `Assets` folder. This folder allows you to load assets at run-time through code. Inside this folder, right-click and select `Create > Talo > Settings Asset`.

![Create a settings asset inside the Resources folder](/blog/stat-tracking-unity/settings-asset.png)

If you click into this Asset, you'll find a number of configuration options. The two important ones are `API url` (which you can change if you're choosing to self-host Talo) and `Access key` which identifies your game. You'll need to create an access key through the Talo dashboard.

### Generating an access key

Visit the [Talo dashboard](https://dashboard.trytalo.com), login or create an account (and confirm your email address). Once logged in, create a new game (if you need to) and visit the Access Keys page.

Choose the scopes available to your access key (you'll need the `read:players`, `write:players`, `read:gameStats` and `write:gameStats` scopes) and create your access key. Copy your newly-generated access key into the `Access key` field on the Settings Asset.

### Creating a stat

To create your new stat visit the [Stats page](https://dashboard.trytalo.com/stats) in the dashboard. You can also access it from the `Services` dropdown. Configure your stat however you like but keep note of your chosen `Internal name` since you'll need this to track your stat.

## Identifying the player

We need to know which player to associate with which stat change. Let's create a script to do that automatically for us. Start off by creating a new GameObject in your scene and call it something like `Identity Controller`.

Attach a script to the new GameObject, again I'm calling mine `IdentityController`:

```csharp
using UnityEngine;
using TaloGameServices;
using System;

public class IdentityController : MonoBehaviour
{
    private async void Awake()
    {
        var id = PlayerPrefs.GetString("talo-id", Guid.NewGuid().ToString());
        await Talo.Players.Identify("custom", id);
        PlayerPrefs.SetString("talo-id", id);
    }
}
```

We're using Unity's [PlayerPrefs](https://docs.unity3d.com/ScriptReference/PlayerPrefs.html) to load and save a random ID and associate it with that player. PlayerPrefs provides a fallback option in case there's no matching key (`talo-id` in this example). This will happen the first time the player loads the game but going forward we'll use their assigned ID.

To identify a player we need to provide an identity service (this can be Steam, Epic, etc) - in this case we're using `custom` to simply denote the randomised ID.

## Incrementing stat(s)

Earlier I mentioned I wanted to track two things:

1. Damage blocked by players (with an `Internal name` of `damage-blocked`)
2. Damage taken by players (with an `Internal name` of `damage-taken`)

Currently, I've got a bullet script that handles collision events through the `OnTriggerEnter2D` callback:

```csharp
private void OnTriggerEnter2D(Collider2D collision)
{
    if (collision.CompareTag("Cockpit"))
    {
        collision.gameObject.GetComponent<Cockpit>().OnHit();
        Remove();
    else if (collision.CompareTag("Shield"))
    {
        Remove();
    }
}
```

The player in my game is made up of two `BoxColliders`. One is the `Shield` where the player can't take damage and the other is the `Cockpit` where the player can take damage.

Adding stat tracking to this script is really simple and can be done in just 2 lines of code:

```csharp
using TaloGameServices;

private async void OnTriggerEnter2D(Collider2D collision)
{
    if (collision.CompareTag("Cockpit"))
    {
        collision.gameObject.GetComponent<Cockpit>().OnHit();
        Remove();
        await Talo.Stats.Track("damage-taken");
    else if (collision.CompareTag("Shield"))
    {
        Remove();
        await Talo.Stats.Track("damage-blocked");
    }
}
```

Note: we've had to mark this function as `async` since we need to `await` the tracking.

The `Track()` function requires one parameter which is the `Internal name` of your stat. You can optionally provide a second parameter which is the amount to increase/decrease the stat by.

## Conclusion

If you've ever wondered about how many players are performing specific actions, you can use Talo to easily track these actions. With just 1 line of code, we can track any stat and keep it constrainted within the limits you created it with.

Best of all, these stats are easily visible in the dashboard - you can see global stats or inspect players' individual stats too.


Find out how to track stats like the number of levels players have completed on an individual basis or total across your game.

How to start tracking global and player stats in your Unity game


## The current state of updates

These days there's plenty of ways to update your game, from using SteamPipe to update your game on Steam or Butler to update your game on itch.io.

These tools provide great automation but depend on these updates being delivered to players at the right time or the player needing to download and install the update before progressing.

Plenty of problems come up with these approaches, like needing to check if a player is on the latest version, and if not, providing some UI that prompts them to go and download (or find) the latest version.

On mobile app stores sometimes you need to wait for a review for minor wording changes or to enable a seasonal event. These reviews can take days to finally be completed.

## Live config

Using [live config](/live-config) you can update your game directly from the web. When players open your game, they'll always receive the latest config. You can even keep your config in sync by checking it before players do specific actions.

In this tutorial you'll integrate live config into your Unity game in a few simple steps.

## Set up

You can enable live config in any modern Unity game. For this demo, I've created a project using the Core 2D template - but you can use any template you like.

Once you've loaded your project, go to the package manager (by navigating to `Window > Package Manager`). Click the plus symbol and select "Add package from git url". When prompted, enter the url: `https://github.com/TaloDev/unity-package.git`.

![Choose the add package from git url option in the Package Manager](/blog/live-config-unity/package-manager.png)

We've now added the Talo package to our Unity project. Doing this through git allows you to keep Talo up to date without needing to redownload the zip file and importing it.

Next, if you don't already have a `Resources` folder, create one inside the `Assets` folder. This folder allows you to load assets at run-time through code. Inside this folder, right-click and select `Create > Talo > Settings Asset`.

![Create a settings asset inside the Resources folder](/blog/live-config-unity/settings-asset.png)

If you click into this Asset, you'll find a number of configuration options. The two important ones are `API url` (which you can change if you're choosing to self-host Talo) and `Access key` which identifies your game. You'll need to create an access key through the Talo dashboard.

### Generating an access key

Visit the [Talo dashboard](https://dashboard.trytalo.com), login or create an account (and confirm your email address). Once logged in, create a new game (if you need to) and visit the Access Keys page.

Choose the scopes available to your access key (you'll need the `read:players`, `write:players` and `read:gameConfig` scopes) and create your access key. Copy your newly-generated access key into the `Access key` field on the Settings Asset.

## Setting up the scene

As part of this tutorial we'll be creating a piece of text and using live config to get the latest version of the string. You can apply this pattern to any concept in your game - like checking the max level a player can reach or if a seasonal event is currently enabled.

To start off, right-click your scene hierarchy and select `Create > UI > Text - TextMeshPro`. You will need to import the TextMeshPro assets if you haven't already.

![Create a text game object in the scene](/blog/live-config-unity/create-text.png)

I've centred the text and [moved it to the middle of the screen](/blog/live-config-unity/align-text.gif) to make it easier to see by holding `Shift` to set the pivot and `Alt` (or `Option` on MacOS) to set the position.

Next, add a new script to your Text object - I've named mine `TextLoader`. Open up your new script.

## Querying the live config

The first thing we need to do in our script is import the namespaces we'll be using. Add the following namespaces:

```csharp
using TMPro;
using TaloGameServices;
```

Now we can use functions from the TextMeshPro and Talo namespaces. Here's what we want the script to do:

1. Fetch down the live config for our game
2. Get the value of the string
3. Update the UI to reflect the live config value of our string

Doing this is really easy - all you need to do is update the `Start()` method of the script:

```csharp
async void Start()
{
    var textUI = GetComponent<TextMeshProUGUI>();

    Talo.GameConfig.OnLiveConfigLoaded += (liveConfig) =>
    {
        textUI.text = liveConfig.GetProp("liveString", "Not set!");
    };

    await Talo.GameConfig.Get();
}
```

Live config works on an event-based system - we're subscribing to the `OnLiveConfigLoaded` event to instantly update our game once the config has been fetched. We're then inspecting the config we receive and updating the UI with the string we're looking for (or a fallback - if it isn't set).

Once we've subscribed to the event, we fetch the game config. You'll notice that if you run your game, the UI will say "Not set!" because we haven't created the config property in the Talo dashboard.

## Creating the live config property

To update your config, visit the [Live Config page](https://dashboard.trytalo.com/game-config) in the dashboard. You can also access it from the `Services` dropdown.

Add a new property, name it `liveString` (the same as we've named it in the script), choose what you want your string to be and finally click `Save`.

![Create your property in the dashboard, give it the same name as the key in the script](/blog/live-config-unity/live-config-dashboard.png)

Now when you run your game, you'll see your string directly in your UI. You can update it again in the dashboard and once again your game will always pull in the latest version of the config.

## Polling the live config

The `GameConfig.Get()` method always pulls in the latest version of your config. That means you can check the latest config before a player takes an action or continue to poll for the latest changes:

```csharp
using UnityEngine;
using TaloGameServices;
using TMPro;

public class TextLoader : MonoBehaviour
{
    void Start()
    {
        var textUI = GetComponent<TextMeshProUGUI>();

        Talo.GameConfig.OnLiveConfigLoaded += (liveConfig) =>
        {
            textUI.text = liveConfig.GetProp("liveString", "Not set!");
        };

        InvokeRepeating("GetConfig", 0f, 2f);
    }

    async void GetConfig()
    {
        await Talo.GameConfig.Get();
    }
}
```

Unity's `InvokeRepeating()` calls a method with a delay (that we've set to 0 seconds so it runs instantly) and then every interval after that (which we've set to every 2 seconds). 

## Conclusion

While even the smallest updates have traditionally required new releases, Talo's live config lets your game be reactive to the latest changes without releasing a new update or waiting for that update to be approved by an app store.

With only a few lines of code, you can pull in your game config. You can update that config whenever you need to from the Talo dashboard. [Check out the docs](https://docs.trytalo.com/docs/unity/live-config) to learn more about how live config works.


Learn how to easily update your game without depending on players downloading a new update or app store reviews.

Sign up

Talo Blog

Testing your game code with the Unity Test Framework

How to start tracking global and player stats in your Unity game

How to update your Unity game without releasing a new update