Monkey Test Helper

Reference implementation that performs object-based Unity UI (uGUI) monkey tests and API for custom implementation.

This library can use in runtime code because it does not depend on the Unity Test Framework.

Required Unity 2019 LTS or later.

Features

Monkey test reference implementation

Run a monkey test for uGUI (2D, 3D, and UI) elements. Monkey.Run method operates on randomly selected objects. It does not use screen points.

Usage:

using System;
using System.Threading.Tasks;
using NUnit.Framework;
using TestHelper.Monkey;

[TestFixture]
public class MyIntegrationTest
{
    [Test]
    public async Task MonkeyTesting()
    {
        var config = new MonkeyConfig
        {
            Lifetime = TimeSpan.FromMinutes(2),
            DelayMillis = 200,
            SecondsToErrorForNoInteractiveComponent = 5,
        };

        await Monkey.Run(config);
    }
}

Configurations in MonkeyConfig:

• Lifetime: Running time
• DelayMillis: Delay time between operations
• SecondsToErrorForNoInteractiveComponent: Seconds to determine that an error has occurred when an object that can be interacted with does not exist
• Random: Random generator
• Logger: Logger
• Verbose: Output verbose log if true
• Gizmos: Show Gizmos on GameView during running monkey test if true
• Screenshots: Take screenshots during running the monkey test if set a ScreenshotOptions instance.
  • Directory: Directory to save screenshots. If omitted, the directory specified by command line argument "-testHelperScreenshotDirectory" is used. If the command line argument is also omitted, Application.persistentDataPath + "/TestHelper/Screenshots/" is used.
  • FilenameStrategy: Strategy for file paths of screenshot images. Default is test case name and four digit sequential number.
  • SuperSize: The factor to increase resolution with. Default is 1.
  • StereoCaptureMode: The eye texture to capture when stereo rendering is enabled. Default is LeftEye.

More customize for your project:

• IsReachable: Function returns the GameObject is reachable from user or not. Default implementation is using Raycaster and includes ScreenPointStrategy (GetScreenPoint function).
• IsInteractable: Function returns the Component is interactable or not. The default implementation is support for standard Unity UI (uGUI) components.
• Operators: Operators that the monkey invokes. Default is ClickOperator, ClickAndHoldOperator, and TextInputOperator. There is support for standard Unity UI (uGUI) components.

Annotations for Monkey's behavior

You can control the Monkey's behavior by attaching the annotation components to the GameObject. Use the TestHelper.Monkey.Annotations assembly by adding it to the Assembly Definition References. Please note that this will be included in the release build due to the way it works.

Note

Even if the annotations assembly is removed from the release build, the link to the annotation component will remain Scenes and Prefabs in the asset bundle built. Therefore, a warning log will be output during instantiate. To avoid this, annotations assembly are included in release builds.

IgnoreAnnotation

Monkey will not operate objects with IgnoreAnnotation attached.

InputFieldAnnotation

Specify the character kind and length input into InputField with InputFieldAnnotation.

ScreenOffsetAnnotation

Specify the screen position offset on the screen space where Monkey operates.

ScreenPositionAnnotation

Specify the screen position where Monkey operates.

WorldOffsetAnnotation

Specify the screen position offset on world space where Monkey operates.

WorldPositionAnnotation

Specify the world position where Monkey operates.

Find and operate interactable uGUI components

GameObjectFinder.FindByNameAsync

Find GameObject by name (wait until they appear).

Arguments:

• name: Find GameObject name
• reachable: Find only reachable object
• interactable: Find only interactable object

Usage:

using NUnit.Framework;
using TestHelper.Monkey;

[TestFixture]
public class MyIntegrationTest
{
    [Test]
    public void MyTestMethod()
    {
        var finder = new GameObjectFinder(5d); // 5 seconds timeout
        var dialog = await finder.FindByNameAsync("ConfirmDialog", reachable: true, interactable: false);
    }
}

GameObjectFinder.FindByPathAsync

Find GameObject by path (wait until they appear).

Arguments:

• path: Find GameObject hierarchy path separated by /. Can specify glob pattern
• reachable: Find only reachable object
• interactable: Find only interactable object

Usage:

using NUnit.Framework;
using TestHelper.Monkey;

[TestFixture]
public class MyIntegrationTest
{
    [Test]
    public void MyTestMethod()
    {
        var finder = new GameObjectFinder();
        var button = await finder.FindByPathAsync("/**/Confirm/**/Cancel", reachable: true, interactable: true);
    }
}

Get interactable components and operators

GetInteractableComponents are extensions of GameObject that return interactable components.

SelectOperators and SelectOperators<T> are extensions of Component that return available operators. Operators implements IOperator interface. It has OperateAsync method that operates on the component.

Usage:

using NUnit.Framework;
using TestHelper.Monkey;

[TestFixture]
public class MyIntegrationTest
{
    [Test]
    public void ClickStartButton()
    {
        var finder = new GameObjectFinder();
        var button = await finder.FindByNameAsync("StartButton", interactable: true);

        var buttonComponent = button.GetInteractableComponents().First();
        var clickOperator = buttonComponent.SelectOperators<IClickOperator>(_operators).First();
        clickOperator.OperateAsync(buttonComponent);
    }
}

InteractiveComponentCollector.FindInteractableComponents

Returns interactable uGUI components.

Usage:

using System.Linq;
using NUnit.Framework;
using TestHelper.Monkey;
using TestHelper.Monkey.Operators;

[TestFixture]
public class MyIntegrationTest
{
    [Test]
    public void MyTestMethod()
    {
        var components = InteractiveComponentCollector.FindInteractableComponents();

        var firstComponent = components.First();
        var clickAndHoldOperator = firstComponent.SelectOperators<IClickAndHoldOperator>(_operators).First();
        await clickAndHoldOperator.OperateAsync(firstComponent);
    }
}

InteractiveComponentCollector.FindReachableInteractableComponents

Returns interactable uGUI components. Return only user-really reachable components (using the IsReachable method).

Usage:

using System.Linq;
using NUnit.Framework;
using TestHelper.Monkey;
using TestHelper.Monkey.Operators;

[TestFixture]
public class MyIntegrationTest
{
    [Test]
    public void MyTestMethod()
    {
        var components = InteractiveComponentCollector.FindReachableInteractableComponents();

        var firstComponent = components.First();
        var textInputOperator = firstComponent.SelectOperators<ITextInputOperator>(_operators).First();
        textInputOperator.OperateAsync(firstComponent);   // input random text
    }
}

Use in runtime code

The "Define Constraints" is set to UNITY_INCLUDE_TESTS || COM_NOWSPRINTING_TEST_HELPER_ENABLE in this package's assembly definition files, so it is generally excluded from release builds.

To use the feature in release builds, add COM_NOWSPRINTING_TEST_HELPER_ENABLE to the "Define Symbols" at build time.

Installation

You can choose from two typical installation methods.

Install via Package Manager window

1. Open the Package Manager tab in Project Settings window (Editor > Project Settings)
2. Click + button under the Scoped Registries and enter the following settings (figure 1.):
   1. Name: package.openupm.com
   2. URL: https://package.openupm.com
   3. Scope(s): com.nowsprinting and com.cysharp
3. Open the Package Manager window (Window > Package Manager) and select My Registries in registries drop-down list (figure 2.)
4. Click Install button on the com.nowsprinting.test-helper.monkey package

Note

Do not forget to add com.cysharp into scopes. These are used within this package.

Figure 1. Package Manager tab in Project Settings window.

Figure 2. Select registries drop-down list in Package Manager window.

Install via OpenUPM-CLI

If you installed openupm-cli, run the command below:

openupm add com.nowsprinting.test-helper.monkey

Add assembly reference

1. Open your test assembly definition file (.asmdef) in Inspector window
2. Add TestHelper.Monkey into Assembly Definition References

License

MIT License

How to contribute

Open an issue or create a pull request.

Be grateful if you could label the PR as enhancement, bug, chore, and documentation. See PR Labeler settings for automatically labeling from the branch name.

How to development

Add this repository as a submodule to the Packages/ directory in your project.

git submodule add https://github.com/nowsprinting/test-helper.monkey.git Packages/com.nowsprinting.test-helper.monkey

Warning

Required install packages for running tests (when adding to the testables in package.json), as follows:

• Unity Test Framework package v1.3.4 or later

Generate a temporary project and run tests on each Unity version from the command line.

make create_project
UNITY_VERSION=2019.4.40f1 make -k test

Release workflow

Run Actions > Create release pull request > Run workflow and merge created pull request. (Or bump version in package.json on default branch)

Then, Will do the release process automatically by Release workflow. And after tagging, OpenUPM retrieves the tag and updates it.

Do NOT manually operation the following operations:

• Create a release tag
• Publish draft releases