Get Started

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

Import AltUnity Tester package in Unity Editor
Instrument your game with AltUnity Tester
Run your game in Unity or on desired platform
Write and execute first test for your game

Note

If you don’t have access to source code of the game you need to ask a person with access to give you an instrumented version of the game.

Note

From version 1.7.0 on we’ll be referring to AltUnity Server as AltUnity Tester.

Import AltUnity Tester package in Unity Editor

To instrument your Unity application with AltUnity Tester you first need to import the AltUnity Tester package into Unity. This can be done either by downloading from the Unity Asset Store or from the GitLab pages.

Download from Unity Asset Store - link.
Go to your Asset Store Downloads Manager from Unity Editor.
Import the package into your Unity project.

Important

To make sure the import was correct, check if you can open AltUnity Tester Editor Window from Unity Editor -> AltUnity Tools -> AltUnityTester.

window menu with altUnity Tester

Instrument your game with AltUnity Tester

Steps:

Open AltUnity Tester Editor window from Unity Editor -> AltUnity Tools -> AltUnityTester

In the Build Settings section set AltUnity Tester 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 game or “Build & Run” to start your instrumented game after the build succeeded
Check the console to see if the build was successful.

Important

AltUnity Tester 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 AltUnity Tester.

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 game 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*.

Run your game 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 AltUnity Tester Window
In platform section select Editor
Click Play in Editor

Prerequisites:

Have IProxy installed: brew install libimobiledevice

Steps:

Open AltUnity Tester Window
In platform section select iOS
Click Build & Run

Note

Check the following link to see how to build and run your game for iOS (.ipa file) – link.

Write and execute first test for your game

To write tests with AltUnity Tester you need to import the AltUnity Driver in your tests project.

AltUnity Tester package contains AltUnityDriver class used to connect to the instrumented game. 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 game.

AltUnity C# Driver is already included in AltUnity Tester 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 -> AltUnityTest. This will create a template file in which you could start to write your test.
Name the file MyFirstTest.
Open AltUnity Tester Window.
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 Altom.AltUnityDriver;

public class MyFirstTest
{
  private AltUnityDriver altUnityDriver;

  [OneTimeSetUp]
  public void SetUp()
  {
    altUnityDriver = new AltUnityDriver();
  }

  [OneTimeTearDown]
  public void TearDown()
  {
    altUnityDriver.Stop();
  }

  [Test]
  public void TestStartGame()
  {
    altUnityDriver.LoadScene("Scene 2 Draggable Panel");

    altUnityDriver.FindObject(By.NAME, "Close Button").Tap();
    altUnityDriver.FindObject(By.NAME, "Button").Tap();

    var panelElement = altUnityDriver.WaitForObject(By.NAME, "Panel");
    Assert.IsTrue(panelElement.enabled);
  }
}

using NUnit.Framework;
using Altom.AltUnityDriver;

public class MyFirstTest
{
  private AltUnityDriver altUnityDriver;

  [OneTimeSetUp]
  public void SetUp()
  {
    AltUnityPortForwarding.ForwardAndroid();
    altUnityDriver = new AltUnityDriver();
  }

  [OneTimeTearDown]
  public void TearDown()
  {
    altUnityDriver.Stop();
    AltUnityPortForwarding.RemoveForwardAndroid();
  }

  [Test]
  public void TestStartGame()
  {
    altUnityDriver.LoadScene("Scene 2 Draggable Panel");

    altUnityDriver.FindObject(By.NAME, "Close Button").Tap();
    altUnityDriver.FindObject(By.NAME, "Button").Tap();

    var panelElement = altUnityDriver.WaitForObject(By.NAME, "Panel");
    Assert.IsTrue(panelElement.enabled);
  }
}

using NUnit.Framework;
using Altom.AltUnityDriver;

public class MyFirstTest
{
  private AltUnityDriver altUnityDriver;

  [OneTimeSetUp]
  public void SetUp()
  {
    AltUnityPortForwarding.ForwardIos();
    altUnityDriver = new AltUnityDriver();
  }

  [OneTimeTearDown]
  public void TearDown()
  {
    altUnityDriver.Stop();
    AltUnityPortForwarding.KillAllIproxyProcess();
  }

  [Test]
  public void TestStartGame()
  {
    altUnityDriver.LoadScene("Scene 2 Draggable Panel");

    altUnityDriver.FindObject(By.NAME, "Close Button").Tap();
    altUnityDriver.FindObject(By.NAME, "Button").Tap();

    var panelElement = altUnityDriver.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 AltUnityTestRunner.RunTestFromCommandLine -tests MyFirstTest.TestStartGame -logFile logFile.log -batchmode -quit

AltUnityDriver is available also as a nuget package. You can use the nuget package to write your tests in a separate tests project, independent of the Unity application.

Create a new test project

dotnet new nunit

Install AltUnityDriver nuget package

dotnet add package AltUnityDriver --version 1.7.0

Run your tests

dotnet test

Example test file:

using NUnit.Framework;
using Altom.AltUnityDriver;

public class MyFirstTest
{
  private AltUnityDriver altUnityDriver;

  [OneTimeSetUp]
  public void SetUp()
  {
    altUnityDriver = new AltUnityDriver();
  }

  [OneTimeTearDown]
  public void TearDown()
  {
    altUnityDriver.Stop();
  }

  [Test]
  public void TestStartGame()
  {
    altUnityDriver.LoadScene("Scene 2 Draggable Panel");

    altUnityDriver.FindObject(By.NAME, "Close Button").Tap();
    altUnityDriver.FindObject(By.NAME, "Button").Tap();

    var panelElement = altUnityDriver.WaitForObject(By.NAME, "Panel");
    Assert.IsTrue(panelElement.enabled);
  }
}

using NUnit.Framework;
using Altom.AltUnityDriver;

public class MyFirstTest
{
  private AltUnityDriver altUnityDriver;

  [OneTimeSetUp]
  public void SetUp()
  {
    AltUnityPortForwarding.ForwardAndroid();
    altUnityDriver = new AltUnityDriver();
  }

  [OneTimeTearDown]
  public void TearDown()
  {
    altUnityDriver.Stop();
    AltUnityPortForwarding.RemoveForwardAndroid();
  }

  [Test]
  public void TestStartGame()
  {
    altUnityDriver.LoadScene("Scene 2 Draggable Panel");

    altUnityDriver.FindObject(By.NAME, "Close Button").Tap();
    altUnityDriver.FindObject(By.NAME, "Button").Tap();

    var panelElement = altUnityDriver.WaitForObject(By.NAME, "Panel");
    Assert.IsTrue(panelElement.enabled);
  }
}

using NUnit.Framework;
using Altom.AltUnityDriver;

public class MyFirstTest
{
  private AltUnityDriver altUnityDriver;

  [OneTimeSetUp]
  public void SetUp()
  {
    AltUnityPortForwarding.ForwardIos();
    altUnityDriver = new AltUnityDriver();
  }

  [OneTimeTearDown]
  public void TearDown()
  {
    altUnityDriver.Stop();
    AltUnityPortForwarding.KillAllIproxyProcess();
  }

  [Test]
  public void TestStartGame()
  {
    altUnityDriver.LoadScene("Scene 2 Draggable Panel");

    altUnityDriver.FindObject(By.NAME, "Close Button").Tap();
    altUnityDriver.FindObject(By.NAME, "Button").Tap();

    var panelElement = altUnityDriver.WaitForObject(By.NAME, "Panel");
    Assert.IsTrue(panelElement.enabled);
  }
}

AltUnity Java Driver is available as a maven package or as a standalone jar. Use one of the following methods to import the driver in your tests project.

Method 1: Add AltUnity Java Driver as a dependency in your pom.xml file:
<dependency>
    <groupId>com.altom</groupId>
    <artifactId>altunitytester-java-client</artifactId>
    <version>1.7.0</version>
</dependency>
Method 2: Use the .jar file from GIT (without building it from source)
Download AltUnity Java Driver.

Install the .jar file:
mvn install:install-file -Dfile=./target/altunitytester-java-client-jar-with-dependencies.jar -DgroupId=ro.altom -DartifactId=altunitytester -Dversion=1.7.0 -Dpackaging=jar``

Run your tests by using the following command (in the test project folder):

mvn test

Example test file:

import org.junit.AfterClass;
import org.junit.Assert;
import org.junit.BeforeClass;
import org.junit.Test;
import ro.altom.altunitytester.AltUnityDriver;
import ro.altom.altunitytester.AltUnityObject;
import ro.altom.altunitytester.Commands.FindObject.AltFindObjectsParameters;
import ro.altom.altunitytester.Commands.FindObject.AltWaitForObjectsParameters;

import java.io.IOException;

public class myFirstTest {
        
    private static AltUnityDriver altUnityDriver;

    @BeforeClass
    public static void setUp() throws IOException {
        altUnityDriver = new AltUnityDriver();
    }

    @AfterClass
    public static void tearDown() throws Exception {
        altUnityDriver.stop();
    }

    @Test
    public void openClosePanelTest() {

        altUnityDriver.loadScene("Scene 2 Draggable Panel");

        AltFindObjectsParameters altFindObjectsParametersCamera = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.PATH, "//Main Camera")
                .build();
        AltUnityObject camera = altUnityDriver.findObject(altFindObjectsParametersCamera);

        AltFindObjectsParameters closeButtonObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Close Button")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        altUnityDriver.findObject(closeButtonObjectsParameters).tap();

        AltFindObjectsParameters buttonObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Button")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        altUnityDriver.findObject(buttonObjectsParameters).tap();

        AltFindObjectsParameters panelObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Panel")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        AltWaitForObjectsParameters panelWaitForObjectsParameters = new AltWaitForObjectsParameters
                .Builder(panelObjectsParameters).build();
        AltUnityObject panelElement = altUnityDriver.waitForObject(panelWaitForObjectsParameters);

        Assert.assertTrue(panelElement.isEnabled());
    }
}

import org.junit.AfterClass;
import org.junit.Assert;
import org.junit.BeforeClass;
import org.junit.Test;
import ro.altom.altunitytester.AltUnityPortForwarding;
import ro.altom.altunitytester.AltUnityDriver;
import ro.altom.altunitytester.AltUnityObject;
import ro.altom.altunitytester.Commands.FindObject.AltFindObjectsParameters;
import ro.altom.altunitytester.Commands.FindObject.AltWaitForObjectsParameters;

import java.io.IOException;

public class myFirstTest {
        
    private static AltUnityDriver altUnityDriver;

    @BeforeClass
    public static void setUp() throws IOException {
        AltUnityPortForwarding.forwardAndroid();
        altUnityDriver = new AltUnityDriver();
    }

    @AfterClass
    public static void tearDown() throws Exception {
        altUnityDriver.stop();
        AltUnityPortForwarding.removeForwardAndroid();
    }

    @Test
    public void openClosePanelTest() {

        altUnityDriver.loadScene("Scene 2 Draggable Panel");

        AltFindObjectsParameters altFindObjectsParametersCamera = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.PATH, "//Main Camera")
                .build();
        AltUnityObject camera = altUnityDriver.findObject(altFindObjectsParametersCamera);

        AltFindObjectsParameters closeButtonObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Close Button")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        altUnityDriver.findObject(closeButtonObjectsParameters).tap();

        AltFindObjectsParameters buttonObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Button")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        altUnityDriver.findObject(buttonObjectsParameters).tap();

        AltFindObjectsParameters panelObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Panel")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        AltWaitForObjectsParameters panelWaitForObjectsParameters = new AltWaitForObjectsParameters
                .Builder(panelObjectsParameters).build();
        AltUnityObject panelElement = altUnityDriver.waitForObject(panelWaitForObjectsParameters);

        Assert.assertTrue(panelElement.isEnabled());
    }
}

import org.junit.AfterClass;
import org.junit.Assert;
import org.junit.BeforeClass;
import org.junit.Test;
import ro.altom.altunitytester.AltUnityPortForwarding;
import ro.altom.altunitytester.AltUnityDriver;
import ro.altom.altunitytester.AltUnityObject;
import ro.altom.altunitytester.Commands.FindObject.AltFindObjectsParameters;
import ro.altom.altunitytester.Commands.FindObject.AltWaitForObjectsParameters;

import java.io.IOException;

public class myFirstTest {
        
    private static AltUnityDriver altUnityDriver;

    @BeforeClass
    public static void setUp() throws IOException {
        AltUnityPortForwarding.forwardIos();
        altUnityDriver = new AltUnityDriver();
    }

    @AfterClass
    public static void tearDown() throws Exception {
        altUnityDriver.stop();
        AltUnityPortForwarding.killAllIproxyProcess();
    }

    @Test
    public void openClosePanelTest() {

        altUnityDriver.loadScene("Scene 2 Draggable Panel");

        AltFindObjectsParameters altFindObjectsParametersCamera = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.PATH, "//Main Camera")
                .build();
        AltUnityObject camera = altUnityDriver.findObject(altFindObjectsParametersCamera);

        AltFindObjectsParameters closeButtonObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Close Button")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        altUnityDriver.findObject(closeButtonObjectsParameters).tap();

        AltFindObjectsParameters buttonObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Button")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        altUnityDriver.findObject(buttonObjectsParameters).tap();

        AltFindObjectsParameters panelObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Panel")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        AltWaitForObjectsParameters panelWaitForObjectsParameters = new AltWaitForObjectsParameters
                .Builder(panelObjectsParameters).build();
        AltUnityObject panelElement = altUnityDriver.waitForObject(panelWaitForObjectsParameters);

        Assert.assertTrue(panelElement.isEnabled());
    }
}

There are two methods of installing the AltUnity Python Driver pip package:

Method 1: Installing using Pip:
pip install --pre altunityrunner
Method 2: Install from the source code in the repository:
cd <project-dir>/Bindings~/python
python setup.py install

Run your test file by using the following command:

python <nameOfYourTestFile.py>

Example test file:

# -*- coding: UTF-8

import os
import unittest
import sys
from altunityrunner import *


class MyFirstTest(unittest.TestCase):

    altUnityDriver = None

    @classmethod
    def setUpClass(cls):
        cls.altUnityDriver = AltUnityDriver()

    @classmethod
    def tearDownClass(cls):
        cls.altUnityDriver.stop()

    def test_open_close_panel(self):
        self.altUnityDriver.load_scene('Scene 2 Draggable Panel')

        self.altUnityDriver.find_object(By.NAME, "Close Button").tap()
        self.altUnityDriver.find_object(By.NAME, "Button").tap()

        panelElement = self.altUnityDriver.wait_for_object(By.NAME, "Panel")
        self.assertTrue(panelElement.enabled)


if __name__ == '__main__':
    suite = unittest.TestLoader().loadTestsFromTestCase(MyFirstTest)
    result = unittest.TextTestRunner(verbosity=2).run(suite)
    sys.exit(not result.wasSuccessful())

# -*- coding: UTF-8

import os
import unittest
import sys
from altunityrunner import *


class MyFirstTest(unittest.TestCase):

    altUnityDriver = None

    @classmethod
    def setUpClass(cls):
        AltUnityPortForwarding.forward_android()
        cls.altUnityDriver = AltUnityDriver()

    @classmethod
    def tearDownClass(cls):
        cls.altUnityDriver.stop()
        AltUnityPortForwarding.remove_forward_android()

    def test_open_close_panel(self):
        self.altUnityDriver.load_scene('Scene 2 Draggable Panel')

        self.altUnityDriver.find_object(By.NAME, "Close Button").tap()
        self.altUnityDriver.find_object(By.NAME, "Button").tap()

        panelElement = self.altUnityDriver.wait_for_object(By.NAME, "Panel")
        self.assertTrue(panelElement.enabled)


if __name__ == '__main__':
    suite = unittest.TestLoader().loadTestsFromTestCase(MyFirstTest)
    result = unittest.TextTestRunner(verbosity=2).run(suite)
    sys.exit(not result.wasSuccessful())

# -*- coding: UTF-8

import os
import unittest
import sys
from altunityrunner import *


class MyFirstTest(unittest.TestCase):

    altUnityDriver = None

    @classmethod
    def setUpClass(cls):
        AltUnityPortForwarding.forward_ios()
        cls.altUnityDriver = AltUnityDriver()

    @classmethod
    def tearDownClass(cls):
        cls.altUnityDriver.stop()
        AltUnityPortForwarding.kill_all_iproxy_process()

    def test_open_close_panel(self):
        self.altUnityDriver.load_scene('Scene 2 Draggable Panel')

        self.altUnityDriver.find_object(By.NAME, "Close Button").tap()
        self.altUnityDriver.find_object(By.NAME, "Button").tap()

        panelElement = self.altUnityDriver.wait_for_object(By.NAME, "Panel")
        self.assertTrue(panelElement.enabled)


if __name__ == '__main__':
    suite = unittest.TestLoader().loadTestsFromTestCase(MyFirstTest)
    result = unittest.TextTestRunner(verbosity=2).run(suite)
    sys.exit(not result.wasSuccessful())

Now your project can use all the AltUnity Driver Commands.

Note

Before running your tests, start the instrumented game and wait for popup with the message: Waiting for connection on port: 13000.