Awesome
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
.
- 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,
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
- Open the Package Manager tab in Project Settings window (Editor > Project Settings)
- Click + button under the Scoped Registries and enter the following settings (figure 1.):
- Name:
package.openupm.com
- URL:
https://package.openupm.com
- Scope(s):
com.nowsprinting
andcom.cysharp
- Name:
- Open the Package Manager window (Window > Package Manager) and select My Registries in registries drop-down list (figure 2.)
- Click Install button on the
com.nowsprinting.test-helper.monkey
package
[!NOTE]
Do not forget to addcom.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
- Open your test assembly definition file (.asmdef) in Inspector window
- 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 thetestables
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