Get Started
To run the first test for your Unity app you need to:
Note
If you don’t have access to source code of the app you need to ask a person with access to give you an instrumented version of the app.
Import AltTester® package in Unity Editor
To instrument your Unity application with AltTester® Unity SDK you first need to import the AltTester® package into Unity. This can be done either by downloading from the AltTester® website, or by following the steps from the OpenUPM website.
Download from AltTester®.
Import it by drag and drop inside your Unity project.
Go to OpenUPM.
Follow the instructions from the Install via Package Manager section on the right to install via Unity’s Package Manager or via Command-Line Interface.
Resolve dependencies
Newtonsoft.Json
In order for AltTester® Unity SDK to work you need dependency for Newtonsoft.Json. Add "com.unity.nuget.newtonsoft-json": "3.1.0"
to your project manifest.json
, inside dependencies
.
{
"dependencies": {
"com.unity.nuget.newtonsoft-json": "3.1.0"
}
}
Input System
AltTester® Unity SDK has support for Input System starting with version 1.7.1. To enable Input System in AltTester® Unity SDK you need to add "com.unity.inputsystem"
to your manifest.json
, inside testables.
{
"testables": ["com.unity.inputsystem"]
}
Editor Coroutines
In order for AltTester® Unity SDK to work with your project you need the dependency for Editor Coroutines. Add "com.unity.editorcoroutines": "1.0.0
to your project manifest.json
, inside dependencies
.
{
"dependencies": {
"com.unity.editorcoroutines": "1.0.0"
}
}
Important
To make sure the import was correct, check if you can open the AltTester® Editor window from Unity Editor -> AltTester® -> AltTester® Editor.
Instrument your app with AltTester® Unity SDK
Steps:
Open the AltTester® Editor window from Unity Editor -> AltTester® -> AltTester® Editor
In the Build Settings section set AltTester® Port to 13000
In the Scene Manager section select the scenes you want to include in your build
In the Platform section select desired platform and set the path to where you want to save the build
Press “Build Only” to instrument the app or “Build & Run” to start your instrumented app after the build succeeded
Check the console to see if the build was successful.
Important
AltTester® Unity SDK is intended to be used only in debug builds, and it will not work in release mode out of the box. You need to make sure you don’t release a production build instrumented with AltTester® Unity SDK.
Note
If you want to build your intrumented app from outside the AltTester® Editor window you will have to make sure to uncheck the Development Build setting from the Build Settings menu in Unity (go to File -> Build Settings) after selecting your Scenes, as seen bellow.
Note
Your build files are available in the configured Output path. By default, the Output path is a folder with the same name as your game.
Note
If you have a custom build, check how you can build from the command line using the instructions in the Advanced Usage section.
Note
If changes are made inside a test, rebuilding the application is not necessary. A rebuild is needed only if changes are made inside the Unity project.
Note
To be able to run your instrumented app in the background, go to File -> Build Settings -> Player Settings -> Project Settings -> Player -> Resolution and presentation and check the box next to Run in background.
Note
To make sure you can catch possible exceptions thrown from your tests, you’ll have to go to Edit -> Project Settings -> Player -> Publishing Settings and set Enable Exceptions to Full With Stacktrace.
Note
When running the WebGL build of your app in browser, even with the Run in background setting enabled, you still might experience slow performance if the tab with your content is not on focus. Make sure that the tab with your app is visible, otherwise your content will only update once per second in most browsers.
Note
If you are building your instrumented app using the IL2CPP Scripting Backend configuration, you may also want to set the Managed Stripping Level to Minimal from Player Settings -> Other Settings -> Optimization. Otherwise, AltTester® Desktop will throw an exception and will not be able to connect to the game.
Start the AltTester® Server Module
The AltTester® Server Module is incorporated in AltTester® Desktop. In order to start it, all you have to do is to open AltTester® Desktop.
Run your app in Unity or on desired platform
Before running your tests you need to start the instrumented Unity application. Upon startup, your instrumented Unity app should display a popup with the message: “Waiting for connections on port: {Port}”. The popup disappears when your app has successfully connected to the tests.
Open AltTester® Editor
In platform section select Editor
Click Play in Editor
Open AltTester® Editor
In platform section select Standalone
Choose your build target
Click Build & Run
Important
Make sure to set the “Api Compatibility Level” to “.NET 4.x” in Unity versions lower than 2021 when building using the Standalone option.
This setting can be found under Edit menu -> Project Settings -> Player -> Other Settings -> Configuration.
Prerequisites:
Use the Unity Hub to install Android Build Support and the required dependencies: Android SDK & NDK tools, and OpenJDK
Steps:
Open AltTester® Editor
In platform section select Android
Click Build & Run
Prerequisites:
Have IProxy installed:
brew install libimobiledevice
Steps:
Open AltTester® Editor
In platform section select iOS
Click Build & Run
Note
Check the following link to see how to build and run your app for iOS (.ipa file) – link
Note
You can switch between the regular and the AltTester® input by toggling the box with the AltTester® Input label. Take into consideration that if you are using the New Input System, then after activating the AltTester® input, you will only be able to interact with the instrumented build via your automated tests or the AltTester® Desktop.
Write and execute first test for your app
To write tests with AltTester® Unity SDK you need to import the AltDriver in your tests project.
AltTester® package contains AltDriver class used to connect to the instrumented app. In the setup method create an instance of the driver and in the tear-down method invoke the stop method of the driver. With the instance of the driver you can query the Unity objects and interact with the app.
AltTester-Driver for C# is already included in AltTester® package. If you are writing tests in C# then you can create your tests directly from Unity.
Create a folder named Editor in your Unity Project.
Right-click on Editor folder and select Create -> AltTest. This will create a template file in which you could start to write your test.
Name the file MyFirstTest.
Open AltTester® Editor.
Make sure that the AltTester® Desktop app is running (Starting with version
2.0.0
, AltTester® Desktop must be running on your PC while the tests are running).In the Run Tests section press “Run All Tests” button. You should see the output of the tests in Unity Editor Console
Example test file:
using NUnit.Framework;
using AltTester.AltTesterUnitySDK.Driver;
public class MyFirstTest
{
private AltDriver altDriver;
[OneTimeSetUp]
public void SetUp()
{
altDriver = new AltDriver();
}
[OneTimeTearDown]
public void TearDown()
{
altDriver.Stop();
}
[Test]
public void TestStartGame()
{
altDriver.LoadScene("Scene 2 Draggable Panel");
altDriver.FindObject(By.NAME, "Close Button").Tap();
altDriver.FindObject(By.NAME, "Button").Tap();
var panelElement = altDriver.WaitForObject(By.NAME, "Panel");
Assert.IsTrue(panelElement.enabled);
}
}
using AltTester.AltTesterUnitySDK.Driver;
using AltTester.AltTesterUnitySDK.Driver.AltReversePortForwarding;
using NUnit.Framework;
public class MyFirstTest
{
private AltDriver altDriver;
[OneTimeSetUp]
public void SetUp()
{
AltReversePortForwarding.ReversePortForwardingAndroid();
altDriver = new AltDriver();
}
[OneTimeTearDown]
public void TearDown()
{
altDriver.Stop();
AltReversePortForwarding.RemoveReversePortForwardingAndroid();
}
[Test]
public void TestStartGame()
{
altDriver.LoadScene("Scene 2 Draggable Panel");
altDriver.FindObject(By.NAME, "Close Button").Tap();
altDriver.FindObject(By.NAME, "Button").Tap();
var panelElement = altDriver.WaitForObject(By.NAME, "Panel");
Assert.IsTrue(panelElement.enabled);
}
}
Run your test file from the command line by using the following command:
<UnityPath>/Unity -projectPath $PROJECT_DIR -executeMethod AltTestRunner.RunTestFromCommandLine -tests MyFirstTest.TestStartGame -logFile logFile.log -batchmode -quit
- Prerequisite:
.NET installed.
Instrumented build.
The AltTester® Desktop installed on your PC.
- Connection:
Starting with version
2.0.0
, the AltTester® Desktop must be running on your PC while the tests are running.The AltTester® Desktop app is running.
The instrumented build is running.
Configure the IP of the build in order to match the IP of the machine (PC) the Desktop app is running on.
Then press the restart button in the AltTester® dialog and wait until the Connected to AltTester® Server… message is displayed in the dialog.
- Test Setup:
You can use any IDE you want. As a suggestion, we prefer Visual Studio Code.
To be able to run our test scripts, we should use a testing framework. For this tutorial, we will use the NUnit testing framework.
In order to use
NUnit
, you should start by creating an NUnit project. To do this, you need to create an empty folder (this will be the project folder) and open it in Visual Studio Code. Open a terminal (we preferred git bash) and run the command below. This command will create a basic NUnit project for you:
dotnet new nunit
To be able to interact with the game through your tests, you need AltDriver. To add the AltDriver to your testing project, all you need to do is to use the following command in your terminal:
dotnet add package AltTester-Driver --version x.y.z
Note that the
x.y.z
is the version of AltDriver you want to install.- Writing tests:
There are many ways in which the project can be organized. We suggest using the Page Object Model design pattern to organize your project into pages folders and tests folders.
To initialize the AltDriver in your project, you should import it. You can do it by using the following syntax:
using AltTester.AltTesterUnitySDK.Driver;
.After that you can initialize the AltDriver:
altDriver = new AltDriver();
.
- Running the tests:
To run your test, open a terminal window in the project folder and paste the following command:
dotnet test
Example test file:
using NUnit.Framework;
using AltTester.AltTesterUnitySDK.Driver;
public class MyFirstTest
{
private AltDriver altDriver;
[OneTimeSetUp]
public void SetUp()
{
altDriver = new AltDriver();
}
[OneTimeTearDown]
public void TearDown()
{
altDriver.Stop();
}
[Test]
public void TestStartGame()
{
altDriver.LoadScene("Scene 2 Draggable Panel");
altDriver.FindObject(By.NAME, "Close Button").Tap();
altDriver.FindObject(By.NAME, "Button").Tap();
var panelElement = altDriver.WaitForObject(By.NAME, "Panel");
Assert.IsTrue(panelElement.enabled);
}
}
using AltTester.AltTesterUnitySDK.Driver;
using AltTester.AltTesterUnitySDK.Driver.AltReversePortForwarding;
using NUnit.Framework;
public class MyFirstTest
{
private AltDriver altDriver;
[OneTimeSetUp]
public void SetUp()
{
AltReversePortForwarding.ReversePortForwardingAndroid();
altDriver = new AltDriver();
}
[OneTimeTearDown]
public void TearDown()
{
altDriver.Stop();
AltReversePortForwarding.RemoveReversePortForwardingAndroid();
}
[Test]
public void TestStartGame()
{
altDriver.LoadScene("Scene 2 Draggable Panel");
altDriver.FindObject(By.NAME, "Close Button").Tap();
altDriver.FindObject(By.NAME, "Button").Tap();
var panelElement = altDriver.WaitForObject(By.NAME, "Panel");
Assert.IsTrue(panelElement.enabled);
}
}
- Prerequisite:
Java installed.
Instrumented build.
The AltTester® Desktop installed on your PC.
- Connection:
Starting with version
2.0.0
, the AltTester® Desktop must be running on your PC while the tests are running.The AltTester® Desktop app is running.
The instrumented build is running.
Configure the IP of the build in order to match the IP of the machine (PC) the Desktop app is running on.
Then press the restart button in the AltTester® dialog and wait until the Connected to AltTester® Server… message is displayed in the dialog.
- Test Setup:
You can use any IDE that works with Java, but for this setup tutorial, we will use IntelliJ.
In order to have the structure already created for us and the possibility to install/update dependencies in an easy way, we can choose to create a MAVEN project.
In the new
pom.xml
generated, you should add thealttester
andjunit
dependencies (and make sure to use the latest AltTester® driver version):
<dependency> <groupId>com.alttester</groupId> <artifactId>alttester</artifactId> <version>2.1.2</version> </dependency>
<dependency> <groupId>org.junit.jupiter</groupId> <artifactId>junit-jupiter-engine</artifactId> <version>5.11.0-M1</version> </dependency>
When you have these steps completed and you don’t have any errors, you are able to jump into the next section.
- Writing tests:
There are many ways in which the project can be organized. We suggest using the Page Object Model design pattern to organize your project into pages folders and tests folders.
To initialize the AltDriver in your project, you should import it. You can do it by using the following syntax:
import com.alttester.AltDriver;
.After that you can initialize the AltDriver:
driver = new AltDriver();
.Considering that we’re using JUnit as a testing framework, you can find more information about JUnit in its official documentation.
- Running the tests:
Considering that we are using IntelliJ, the tests can be run using the runner that is inside of it. More information about this can be found in the official documentation of IntelliJ.
Example test file:
import org.junit.AfterClass;
import org.junit.Assert;
import org.junit.BeforeClass;
import org.junit.Test;
import com.alttester.AltDriver;
import com.alttester.AltObject;
import com.alttester.Commands.FindObject.AltFindObjectsParameters;
import com.alttester.Commands.FindObject.AltWaitForObjectsParameters;
import java.io.IOException;
public class myFirstTest {
private static AltDriver altDriver;
@BeforeClass
public static void setUp() throws IOException {
altDriver = new AltDriver();
}
@AfterClass
public static void tearDown() throws Exception {
altDriver.stop();
}
@Test
public void openClosePanelTest() {
altDriver.loadScene("Scene 2 Draggable Panel");
AltFindObjectsParameters altFindObjectsParametersCamera = new AltFindObjectsParameters.Builder(
AltDriver.By.PATH, "//Main Camera")
.build();
AltObject camera = altDriver.findObject(altFindObjectsParametersCamera);
AltFindObjectsParameters closeButtonObjectsParameters = new AltFindObjectsParameters.Builder(
AltDriver.By.NAME, "Close Button")
.withCamera(AltDriver.By.ID, String.valueOf(camera.id))
.build();
altDriver.findObject(closeButtonObjectsParameters).tap();
AltFindObjectsParameters buttonObjectsParameters = new AltFindObjectsParameters.Builder(
AltDriver.By.NAME, "Button")
.withCamera(AltDriver.By.ID, String.valueOf(camera.id))
.build();
altDriver.findObject(buttonObjectsParameters).tap();
AltFindObjectsParameters panelObjectsParameters = new AltFindObjectsParameters.Builder(
AltDriver.By.NAME, "Panel")
.withCamera(AltDriver.By.ID, String.valueOf(camera.id))
.build();
AltWaitForObjectsParameters panelWaitForObjectsParameters = new AltWaitForObjectsParameters.Builder(
panelObjectsParameters).build();
AltObject panelElement = altDriver.waitForObject(panelWaitForObjectsParameters);
Assert.assertTrue(panelElement.isEnabled());
}
}
import org.junit.AfterClass;
import org.junit.Assert;
import org.junit.BeforeClass;
import org.junit.Test;
import com.alttester.AltReversePortForwarding;
import com.alttester.AltDriver;
import com.alttester.AltObject;
import com.alttester.Commands.FindObject.AltFindObjectsParameters;
import com.alttester.Commands.FindObject.AltWaitForObjectsParameters;
import java.io.IOException;
public class MyFirstTest {
private static AltDriver altDriver;
@BeforeAll
public static void setUp() throws IOException {
AltReversePortForwarding.reversePortForwardingAndroid();
altDriver = new AltDriver();
}
@AfterAll
public static void tearDown() throws Exception {
altDriver.stop();
AltReversePortForwarding.removeReversePortForwardingAndroid();
}
@Test
public void openClosePanelTest() {
altDriver.loadScene(new AltLoadSceneParams.Builder("Scene 2 Draggable Panel").build());
AltFindObjectsParams altFindObjectsParametersCamera = new AltFindObjectsParams.Builder(
AltDriver.By.PATH, "//Main Camera")
.build();
AltObject camera = altDriver.findObject(altFindObjectsParametersCamera);
AltFindObjectsParams closeButtonObjectsParameters = new AltFindObjectsParams.Builder(
AltDriver.By.NAME, "Close Button")
.withCamera(AltDriver.By.ID, String.valueOf(camera.id))
.build();
altDriver.findObject(closeButtonObjectsParameters).tap();
AltFindObjectsParams buttonObjectsParameters = new AltFindObjectsParams.Builder(
AltDriver.By.NAME, "Button")
.withCamera(AltDriver.By.ID, String.valueOf(camera.id))
.build();
altDriver.findObject(buttonObjectsParameters).tap();
AltFindObjectsParams panelObjectsParameters = new AltFindObjectsParams.Builder(
AltDriver.By.NAME, "Panel")
.withCamera(AltDriver.By.ID, String.valueOf(camera.id))
.build();
AltWaitForObjectsParams panelWaitForObjectsParameters = new AltWaitForObjectsParams.Builder(
panelObjectsParameters).build();
AltObject panelElement = altDriver.waitForObject(panelWaitForObjectsParameters);
Assertions.assertTrue(panelElement.isEnabled());
}
}
- Prerequisite:
Python installed.
Instrumented build.
The AltTester® Desktop installed on your PC.
- Connection:
Starting with version
2.0.0
, the AltTester® Desktop must be running on your PC while the tests are running.The AltTester® Desktop app is running.
The instrumented build is running.
Configure the IP of the build in order to match the IP of the machine (PC) the Desktop app is running on.
Then press the restart button in the AltTester® dialog and wait until the Connected to AltTester® Server… message is displayed in the dialog.
- Test Setup:
We suggest using the
git bash
terminal type for all the commands below.You can use any IDE you want. As a suggestion, we prefer Visual Studio Code and PyCharm.
To actually run the tests we need a test framework. One of the most popular python testing frameworks is pytest which is easy to download because you just need to use the following command in your terminal:
pip install pytest
To be able to interact with the game through your tests, you need AltDriver. It contains all the methods you need such as
tap()
,wait_for_object()
,find_object()
and so on. To add the AltDriver to your testing project, all you need to do is to use the following command in your terminal:
pip install AltTester-Driver
The following setup steps are not mandatory, but if you choose to use them, you will act like a pro.
Install assertpy - for easy and nice assertions.
Most of the time on a project, you will have to provide some reports with the results of your tests. In order to provide them, you can use
pytest-html-reporter
which generates nice and detailed reports with the results of your tests. To installpytest-html-reporter
use the following command:
pip install pytest-html-reporter
- Writing tests:
There are many ways in which the project can be organized. We suggest using the Page Object Model design pattern to organize your project into pages folders and tests folders.
The AltDriver can be used in your code after you import it. Here is the import syntax:
from alttester import AltDriver
, then you can instantiate an object of AltDriver type:alt_driver = AltDriver()
. By doing this, you are able to use all the methods that come from AltDriver().Considering that we are using
pytest
, the names of the tests should start withtest
.
- Running the tests:
Running tests using pytest can be easily done using the commands for cmd.
Run all the tests: navigate through the cmd in the folder that contains the tests folder and use the following command:
pytest tests/
Run a specific test file: navigate into the tests folder and use the following command:
pytest test_name.py
Run a specific test method from a file: navigate into the tests folder and use the following command:
pytest test_name.py -k name_of_test_you_wanna_run
For running tests with the HTML reporter, all you have to do is to add this extra argument to your running command:
--html-report=./report/report.html.
This will generate a report under the report folder.
Example test file:
import unittest
from alttester import *
class MyFirstTest(unittest.TestCase):
alt_driver = None
@classmethod
def setUpClass(cls):
cls.alt_driver = AltDriver()
@classmethod
def tearDownClass(cls):
cls.alt_driver.stop()
def test_open_close_panel(self):
self.alt_driver.load_scene('Scene 2 Draggable Panel')
self.alt_driver.find_object(By.NAME, "Close Button").tap()
self.alt_driver.find_object(By.NAME, "Button").tap()
panel_element = self.alt_driver.wait_for_object(By.NAME, "Panel")
self.assertTrue(panel_element.enabled)
import unittest
from alttester import *
class MyFirstTest(unittest.TestCase):
alt_driver = None
@classmethod
def setUpClass(cls):
AltReversePortForwarding.reverse_port_forwarding_android()
cls.alt_driver = AltDriver()
@classmethod
def tearDownClass(cls):
cls.alt_driver.stop()
AltReversePortForwarding.remove_reverse_port_forwarding_android()
def test_open_close_panel(self):
self.alt_driver.load_scene("Scene 2 Draggable Panel")
self.alt_driver.find_object(By.NAME, "Close Button").tap()
self.alt_driver.find_object(By.NAME, "Button").tap()
panel_element = self.alt_driver.wait_for_object(By.NAME, "Panel")
self.assertTrue(panel_element.enabled)
- Prerequisite:
Robot Framework installed.
Instrumented build.
The AltTester® Desktop installed on your PC.
- Connection:
Starting with version
2.0.0
, the AltTester® Desktop must be running on your PC while the tests are running.The AltTester® Desktop app is running.
The instrumented build is running.
Configure the IP of the build in order to match the IP of the machine (PC) the Desktop app is running on.
Then press the restart button in the AltTester® dialog and wait until the Connected to AltTester® Server… message is displayed in the dialog.
- Test Setup:
You can use any IDE you want. As a suggestion, we prefer Visual Studio Code and PyCharm.
- Writing tests:
First you need to create a new project with a Robot class under it, which can store your tests
- In the
Settings
section: Import the
AltTesterLibrary
- Next create the
Setup
andTeardown
suites for your tests In the
Setup
suite you need to include the initialization of the AltDriver - make sure to also add the ip, host and app name as parameters if the connection data for the connected instrumented app is not the default oneIn the
Teardown
suite the AltDriver needs to be stopped
- Next create the
- In the
*** Settings*** Library AltTesterLibrary Suite Setup Initialize Altdriver Suite Teardown Stop Altdriver
The
Test Cases
section stores all your tests which should have a specific and relevant name
*** Test Cases *** Test My First Test
Running the tests:
To run your test use the
robot
commmandRobot Framework test cases are created in files and directories, and they are executed by giving the path to the file or directory in question to the selected runner script
Examples:
robot my_first_test.robot
robot path/to/my_tests/
After running the test the Robot will generate 3 files:
report.html
,log.html
andoutput.xml
- the html files can be opened in the browser and for every test inlog.html
there will be a status highlight, the keywords used, as well as a potential error that might have occured during the test
Example test file:
*** Settings***
Library AltTesterLibrary
Suite Setup Initialize Altdriver
Suite Teardown Stop Altdriver
*** Test Cases ***
Test Resize Panel
Load Scene Scene 2 Draggable Panel
${alt_object}= Find Object NAME Resize Zone
${alt_object_x}= Get Object X ${alt_object}
${alt_object_y}= Get Object Y ${alt_object}
${position_init}= Create List ${alt_object_x} ${alt_object_y}
${screen_position}= Get Screen Position ${alt_object}
${new_x}= Evaluate ${alt_object_x}-200
${new_y}= Evaluate ${alt_object_y}-200
${new_screen_position}= Create List ${new_x} ${new_y}
Swipe ${screen_position} ${new_screen_position} duration=2
${alt_object}= Find Object NAME Resize Zone
${alt_object_x}= Get Object X ${alt_object}
${alt_object_y}= Get Object Y ${alt_object}
${position_final}= Create List ${alt_object_x} ${alt_object_y}
Should Not Be Equal ${position_init} ${position_final}
*** Settings***
Library AltTesterLibrary
Suite Setup SetUp Tests
Suite Teardown Teardown Tests
*** Test Cases ***
Test Resize Panel
Load Scene Scene 2 Draggable Panel
${alt_object}= Find Object NAME Resize Zone
${alt_object_x}= Get Object X ${alt_object}
${alt_object_y}= Get Object Y ${alt_object}
${position_init}= Create List ${alt_object_x} ${alt_object_y}
${screen_position}= Get Screen Position ${alt_object}
${new_x}= Evaluate ${alt_object_x}-200
${new_y}= Evaluate ${alt_object_y}-200
${new_screen_position}= Create List ${new_x} ${new_y}
Swipe ${screen_position} ${new_screen_position} duration=2
${alt_object}= Find Object NAME Resize Zone
${alt_object_x}= Get Object X ${alt_object}
${alt_object_y}= Get Object Y ${alt_object}
${position_final}= Create List ${alt_object_x} ${alt_object_y}
Should Not Be Equal ${position_init} ${position_final}
*** Keywords ***
SetUp Tests
Reverse Port Forwarding Android
Initialize Altdriver
Teardown Tests
Stop Altdriver
Remove Reverse Port Forwarding Android
Now your project can use all the AltDriver Commands.
Note
Before the connection step, start the instrumented app and wait for the green popup with the message: Waiting to connect to AltTester® Server on IP:port with app name: ‘your app name’.