Get Started

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

1. Import AltUnity Tester package in Unity Editor

2. Instrument your game with AltUnity Server

3. Run the build in Unity Editor or on desired platform

4. Write and execute first test

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.

Import AltUnity Tester package

To instrument your game with AltUnity Server you first need to import the AltUnity Tester package into Unity.

From Unity Asset Store

UnityPackage from Gitlab pages

1. Download from Unity Asset Store - link.

2. Go to your Asset Store Downloads Manager from Unity Editor.

3. Import the package into your Unity project.

1. Download from Gitlab pages (deployed using CI) - link.

2. Import it by drag and drop inside your Unity project.

Important

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

Instrument your game with AltUnity Server

In order for the tests to have access to Unity objects via AltUnity Client you need to instrument the game with AltUnity Server.

Steps:

1. Open AltUnity Tester Window from Unity Editor -> Window -> AltUnityTester.

2. Select on what platform you want to build the game.

3. Press “Build Only” to instrument the game.

4. Check the console to see if the build was successful.

Important

Make sure to set the “Api Compatibility Level” to “.NET 4.x” in Unity when building using the Standalone option.

This setting can be found under Edit menu -> Project Settings -> Player -> Other Settings -> Configuration.

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.

Run your game in Unity or on desired platform

Before running your tests you need to start the game instrumented with AltUnity Server. Upon startup, your game should display a popup with the message: “waiting for connection on port 13000”.

Unity Editor

PC

Android

iOS

1. Open AltUnity Tester Window

2. In platform section select Editor

3. Click Play in Editor

1. Open AltUnity Tester Window

2. In platform section select Standalone

3. Choose your build target

4. Click Build & Run

Important

Make sure to set the “Api Compatibility Level” to “.NET 4.x” in Unity 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:

1. Open AltUnity Tester Window

2. In platform section select Android

3. Click Build & Run

Prerequisites:

• Have IProxy installed: brew install libimobiledevice

Steps:

1. Open AltUnity Tester Window

2. In platform section select iOS

3. Click Build & Run

Note

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

Note

For more details read about port forwarding at this link.

Write and execute first test for your game

To write tests with AltUnity Tester you need to import the AltUnity Client 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.

Note

Example tests below are setup to run on Scene 2 and Scene 3 from the Example folder under the AltUnity Tester package.

If you want to use these examples for other scenes / games, make sure to update the test accordingly.

C#

Java

Python

AltUnity C# Client is already included in AltUnity Tester package. If you are writing tests in C# then you can create your tests directly from Unity.

1. Create a folder named Editor in your Unity Project.

2. Right-click on Editor folder and select Create -> AltUnityTest. This will create a template file in which you could start to write your test.

3. Name the file MyFirstTest.

4. Open AltUnity Tester Window.

5. 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:

Unity Editor & PC

Android

iOS

using NUnit.Framework;
using Assets.AltUnityTester.AltUnityDriver;
using Assets.AltUnityTester.AltUnityDriver.UnityStruct;

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 Assets.AltUnityTester.AltUnityDriver;
using Assets.AltUnityTester.AltUnityDriver.UnityStruct;

public class MyFirstTest
{
  private AltUnityDriver altUnityDriver;

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

  [OneTimeTearDown]
  public void TearDown()
  {
    altUnityDriver.Stop();
    AltUnityPortHandler.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 Assets.AltUnityTester.AltUnityDriver;
using Assets.AltUnityTester.AltUnityDriver.UnityStruct;

public class MyFirstTest
{
  private AltUnityDriver altUnityDriver;

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

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

  [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

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

Method 1:

• Add AltUnity Java Client as a dependency in your pom.xml file:

<dependency>
  <groupId>com.altom</groupId>
  <artifactId>altunitytester-java-client</artifactId>
  <version>1.6.0</version>
</dependency>

Method 2: Use the .jar file from GIT (without building it from source)

• Download AltUnity Java Client.

• Install the .jar file:

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

Example test file:

Unity Editor & PC

Android

iOS

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 altdriver;

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

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

    @Test
    public void openClosePanelTest() {

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

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

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

        AltFindObjectsParameters buttonObjectsParameters = new AltFindObjectsParameters
                .Builder(AltUnityDriver.By.NAME, "Button")
                .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
                .build();
        altdriver.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 = altdriver.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.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 altdriver;

  @BeforeClass
  public static void setUp() throws IOException {
    AltUnityDriver.setupPortForwarding("android", "", 13000, 13000);
    altdriver = new AltUnityDriver();
  }

  @AfterClass
  public static void tearDown() throws Exception {
    altdriver.stop();
    AltUnityDriver.removePortForwarding();
  }

  @Test
  public void openClosePanelTest() {

      altdriver.loadScene("Scene 2 Draggable Panel");
      
      AltFindObjectsParameters altFindObjectsParametersCamera = new AltFindObjectsParameters
              .Builder(AltUnityDriver.By.PATH, "//Main Camera")
              .build();
      AltUnityObject camera = altdriver.findObject(altFindObjectsParametersCamera);

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

      AltFindObjectsParameters buttonObjectsParameters = new AltFindObjectsParameters
              .Builder(AltUnityDriver.By.NAME, "Button")
              .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
              .build();
      altdriver.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 = altdriver.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.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 altdriver;

  @BeforeClass
  public static void setUp() throws IOException {
    AltUnityDriver.setupPortForwarding("ios", "", 13000, 13000);
    altdriver = new AltUnityDriver();
  }

  @AfterClass
  public static void tearDown() throws Exception {
    altdriver.stop();
    AltUnityDriver.removePortForwarding();
  }

  @Test
  public void openClosePanelTest() {

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

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

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

      AltFindObjectsParameters buttonObjectsParameters = new AltFindObjectsParameters
              .Builder(AltUnityDriver.By.NAME, "Button")
              .withCamera(AltUnityDriver.By.ID, String.valueOf(camera.id))
              .build();
      altdriver.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 = altdriver.waitForObject(panelWaitForObjectsParameters);

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

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

mvn test

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

Method 1 - Installing using Pip:

pip install altunityrunner

Method 2 - Install from the source code in the repository:

cd <project-dir>/Bindings~/python

python setup.py install

Example test file:

Unity Editor & PC

Android

iOS

# -*- coding: UTF-8

import os
import unittest
import sys
import json
import time
from altunityrunner import *


class MyFirstTest(unittest.TestCase):

    altdriver = None

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

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

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

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

        panelElement = self.altdriver.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
import json
import time
from altunityrunner import *


class MyFirstTest(unittest.TestCase):
    altdriver = None

    @classmethod
    def setUpClass(cls):
        androidPortForwarding = AltUnityAndroidPortForwarding()
        androidPortForwarding.forward_port_device()

        cls.altdriver = AltUnityDriver()

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

        androidPortForwarding = AltUnityAndroidPortForwarding()
        androidPortForwarding.remove_forward_port_device()

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

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

        panelElement = self.altdriver.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
import json
import time
from altunityrunner import *


class MyFirstTest(unittest.TestCase):
    altdriver = None
    iProxyProcessID = -1

    @classmethod
    def setUpClass(cls):
        iOSPortForwarding = AltUnityiOSPortForwarding()
        cls.iProxyProcessID = iOSPortForwarding.forward_port_device()

        cls.altdriver = AltUnityDriver()

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

        iOSPortForwarding = AltUnityiOSPortForwarding()
        iOSPortForwarding.kill_iproxy_process(cls.iProxyProcessID)

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

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

        panelElement = self.altdriver.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())

Run your test file by using the following command:

python <nameOfYourTestFile.py>

Now your project can use all the AltUnity Client Commands.

Note

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