Get Started

To run the first test for your Unity app you need to:

Import AltTester® package in Unity Editor
Instrument your app with AltTester® Unity SDK
Start the AltTester® Server Module
Run your app in Unity or on desired platform
Write and execute first test for your app

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.

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.

Window menu with AltTester® Unity SDK Options

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.

Build Settings menu from Unity

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

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 the alttester and junit dependencies (and make sure to use the latest AltTester® driver version):

<dependency>
    <groupId>com.alttester</groupId>
    <artifactId>alttester</artifactId>
    <version>2.2.0</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 install pytest-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 with test.

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 and Teardown 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 one
  
  In the Teardown suite the AltDriver needs to be stopped

*** 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 commmand

Robot 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 and output.xml - the html files can be opened in the browser and for every test in log.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’.