Advanced Usage

This guide covers some of the more advanced features, patterns and configuration options of AltTester Unity SDK.

Custom input vs. regular input

AltTester’s custom input is active, by default, in any instrumented build. This means that certain input related actions (the ones that are part of Unity’s Input class) will be inactive for regular input (the device’s input). Because of this, pressing a key from the keyboard for example will not have any effect on the game. However, the simulated input from the tests, like the PressKey command, will be able to manipulate the object within the scene. While the custom input is active, the icon from the right bottom corner is green. You can change this behaviour by clicking on the AltTester’s icon and unchecking the box with the Custom Input message. Now the icon will turn darker, signaling that the regular input is active. In this state, you can interfere with the object from the game using the keyboard or other input. Keep in mind that, input actions from the AltTester Desktop won’t have any effect while regular input is active. At the same time, if you want to run some automated tests, the custom input will be activated automatically for you.

Build games from the command line

To build your Unity application from command line you need a static method in your project that handles the build logic. To instrument your Unity application with AltTester Unity SDK, your build method must define ALTTESTER scripting symbol and must insert AltTester Prefab in the first scene of the game.

Depending on your project’s setup, there are two ways in which games can be built from the command line:

Note

AltTester Unity SDK does not work by default in release mode. If you instrument your game in release mode, AltTester Prefab self removes from the scenes and the socket server does not start. Best case practice is to customize your build script to insert AltTester Prefab only in Debug mode.

If you do want to use AltTester Unity SDK in release mode see Using AltTester Unity SDK in Release mode section.

1. If you already have a custom build method for your game

If you already have a custom build method for your game, you can add the following lines to your build method. Also, the BuildPlayerOptions should check for BuildOptions.Development and BuildOptions.IncludeTestAssemblies.

var buildTargetGroup = BuildTargetGroup.Android;
AltBuilder.AddAltTesterInScriptingDefineSymbolsGroup(buildTargetGroup);
if (buildTargetGroup == UnityEditor.BuildTargetGroup.Standalone) {
    AltBuilder.CreateJsonFileForInputMappingOfAxis();
}
var instrumentationSettings = new AltInstrumentationSettings();
AltBuilder.InsertAltInScene(FirstSceneOfTheGame, instrumentationSettings);

Note

Change buildTargetGroup above to the target group for which you are building.

2. If you create a new custom build method for your game

The following example script can be used. It sets all the project settings needed and uses the same two important lines from point 1 above.

This example method is configured for the Android platform, so make sure to update it based on your target platform.

static void BuildFromCommandLine () {
    try {
        BuildPlayerOptions buildPlayerOptions = new BuildPlayerOptions();
        buildPlayerOptions.scenes = new string[] {
            "Assets/AltTester/Examples/Scenes/Scene 1 AltDriverTestScene.unity",
            "Assets/AltTester/Examples/Scenes/Scene 2 Draggable Panel.unity",
            "Assets/AltTester/Examples/Scenes/Scene 3 Drag And Drop.unity",
            "Assets/AltTester/Examples/Scenes/Scene 4 No Cameras.unity",
            "Assets/AltTester/Examples/Scenes/Scene 5 Keyboard Input.unity",
            "Assets/AltTester/Examples/Scenes/Scene 7 Drag And Drop NIS.unity",
            "Assets/AltTester/Examples/Scenes/Scene 7 New Input System Actions.unity",
            "Assets/AltTester/Examples/Scenes/Scene 8 Draggable Panel NIP.unity",
            "Assets/AltTester/Examples/Scenes/Scene 9 NIS.unity",
            "Assets/AltTester/Examples/Scenes/Scene 10 Sample NIS.unity,
            "Assets/AltTester/Examples/Scenes/Scene 11 ScrollView Scene.unity",
            "Assets/AltTester/Examples/Scenes/Scene6.unity"
        };

        buildPlayerOptions.locationPathName = "sampleGame.apk";
        buildPlayerOptions.target = BuildTarget.Android;
        buildPlayerOptions.options = BuildOptions.Development | BuildOptions.IncludeTestAssemblies | BuildOptions.AutoRunPlayer;

        // Setup for AltTester
        var buildTargetGroup = BuildTargetGroup.Android;
        AltBuilder.AddAltTesterInScriptingDefineSymbolsGroup (buildTargetGroup);
        if (buildTargetGroup == UnityEditor.BuildTargetGroup.Standalone)
            AltBuilder.CreateJsonFileForInputMappingOfAxis();
        var instrumentationSettings = new AltInstrumentationSettings();
        AltBuilder.InsertAltInScene (buildPlayerOptions.scenes[0], instrumentationSettings);

        var results = BuildPipeline.BuildPlayer (buildPlayerOptions);
        AltBuilder.RemoveAltTesterFromScriptingDefineSymbols (BuildTargetGroup.Android);

    } catch (Exception exception) {
        Debug.LogException (exception);
    }
}

The following command is used to call the build method:

<UnityPath>/Unity -projectPath $CI_PROJECT_DIR -executeMethod BuilderClass.BuildFromCommandLine -logFile logFile.log -quit

You can find more information about the build command and arguments here.

Note

After building from the command line you can run the tests by using the commands from the next section.

Run tests from the command line

In order to run tests from the command line you can use the following example commands:

Available Alt command line arguments:

-testsClass - runs tests from given class/classes

Example command running tests from a single test class:

<UnityPath>/Unity -projectPath $PROJECT_DIR -executeMethod Altom.AltTesterEditor.AltTestRunner.RunTestFromCommandLine -testsClass MyTestClass -logFile logFile.log -batchmode -quit

Example command running tests from two test classes:

<UnityPath>/Unity -projectPath $PROJECT_DIR -executeMethod Altom.AltTesterEditor.AltTestRunner.RunTestFromCommandLine -testsClass MyTestClass1 MyTestClass2 -logFile logFile.log -batchmode -quit

-tests - runs given test/tests

Example command running a single test:

<UnityPath>/Unity -projectPath $PROJECT_DIR -executeMethod Altom.AltTesterEditor.AltTestRunner.RunTestFromCommandLine -tests MyTestClass.MyTestName -logFile logFile.log -batchmode -quit

Example command running two tests:

<UnityPath>/Unity -projectPath $PROJECT_DIR -executeMethod Altom.AltTesterEditor.AltTestRunner.RunTestFromCommandLine -tests MyTestClass1.MyTestName1 MyTestClass2.MyTestName2 -logFile logFile.log -batchmode -quit

-testsAssembly - runs tests from given assembly/assemblies

Example command running all tests from given assembly:

<UnityPath>/Unity -projectPath $PROJECT_DIR -executeMethod Altom.AltTesterEditor.AltTestRunner.RunTestFromCommandLine -testsAssembly MyAssembly -logFile logFile.log -batchmode -quit

Example command running tests from two assemblies:

<UnityPath>/Unity -projectPath $PROJECT_DIR -executeMethod Altom.AltTesterEditor.AltTestRunner.RunTestFromCommandLine -testsAssembly MyAssembly1 MyAssembly2 -logFile logFile.log -batchmode -quit

-reportPath - the xml test report will be generated here

<UnityPath>/Unity -projectPath $PROJECT_DIR -executeMethod Altom.AltTesterEditor.AltTestRunner.RunTestFromCommandLine -tests MyFirstTest.TestStartGame -reportPath $PROJECT_DIR/testReport.xml -logFile logFile.log -batchmode -quit

mvn test

Using the unittest module:

python -m unittest <name_of_your_test_file.py>

Using the pytest package:

pytest  <name_of_your_test_file.py>

Run tests on a Continuous Integration Server

Instrument your game build with AltTester Unity SDK from Unity or by building from the command line.
Start the game build on a device.
Run your tests - see commands in the “Run tests from the command line” section.

An example CI configuration file can be viewed in the GitLab repository.

What is port forwarding and when to use it

Port forwarding, or tunneling, is the behind-the-scenes process of intercepting data traffic headed for a computer’s IP/port combination and redirecting it to a different IP and/or port.

When you run your game instrumented with AltTester Unity SDK, on a device, you need to tell your AltDriver how to connect to it.

Port forwarding can be set up either through a command line command or in the test code by using the methods available in Alt classes.

The following are some cases when Port Forwarded is needed:

Connect to the game running on a USB connected device
Connect to multiple devices running the game

How to setup port forwarding

Port forwarding can be set up in three ways:

through a command line command (using ADB/IProxy)
in the test code by using the methods available in Alt classes
from AltTester Editor - Port Forwarding Section

All methods listed above require that you have ADB or IProxy installed.

For installing ABD, check this article for more information on ADB.

For installing IProxy brew install libimobiledevice. (Requires IProxy 2.0.2)

Forward the port using the following command:

adb [-s UDID] forward tcp:local_port tcp:device_port

Forward using AltTester Editor: click on the refresh button in the Port Forwarding section in the Editor to see connected devices and then select the device to forward.

Forward the port using the following command:

iproxy LOCAL_PORT DEVICE_PORT -u [UDID]

Forward using AltTester Editor: click on the refresh button in the Port Forwarding section in the Editor to see connected devices and then select the device to forward.

Use the following static methods (from the AltPortForwarding class) in your test file:

ForwardAndroid (int localPort = 13000, int remotePort = 13000, string deviceId = “”, string adbPath = “”)

RemoveForwardAndroid (int localPort = 13000, string deviceId = “”, string adbPath = “”)

Example test file:

using NUnit.Framework;
using Altom.AltDriver;

public class MyFirstTest
{
  private AltDriver altDriver;

  [OneTimeSetUp]
  public void SetUp()
  {
    AltPortForwarding.ForwardAndroid();
    altDriver = new AltDriver();
  }

  [OneTimeTearDown]
  public void TearDown()
  {
    altDriver.Stop();
    AltPortForwarding.RemoveForwardAndroid();
  }

  [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);
  }
}