Advanced Usage

Build games from the command line

To build your game from command line you need a static method in your project that handles the build logic.
To instrument your game with AltUnity Server, your build method must define AltUnity Tester and must insert AltUnity 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

AltUnity Tester does not work by default in release mode. If you instrument your game in release mode, AltUnity Prefab self removes from the scenes and the socket server does not start. Best case practice is to customize your build script to insert AltUnity Prefab only in Debug mode. If you do want to use AltUnity Tester in release mode see Using AltUnity Server 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 two lines to your build method:

var buildTargetGroup = BuildTargetGroup.Android;
AltUnityBuilder.AddAltUnityTesterInScritpingDefineSymbolsGroup(buildTargetGroup);
if (buildTargetGroup == UnityEditor.BuildTargetGroup.Standalone)
    AltUnityBuilder.CreateJsonFileForInputMappingOfAxis();
AltUnityBuilder.InsertAltUnityInScene(FirstSceneOfTheGame);

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/AltUnityTesterExamples/Scenes/Scene 1 AltUnityDriverTestScene.unity",
            "Assets/AltUnityTesterExamples/Scenes/Scene 2 Draggable Panel.unity",
            "Assets/AltUnityTesterExamples/Scenes/Scene 3 Drag And Drop.unity",
            "Assets/AltUnityTesterExamples/Scenes/Scene 4 No Cameras.unity",
            "Assets/AltUnityTesterExamples/Scenes/Scene 5 Keyboard Input.unity",
            "Assets/AltUnityTesterExamples/Scenes/Scene6.unity"
        };

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

        // Setup for AltUnity
        var buildTargetGroup = BuildTargetGroup.Android;
        AltUnityBuilder.AddAltUnityTesterInScritpingDefineSymbolsGroup (buildTargetGroup);
        if (buildTargetGroup == UnityEditor.BuildTargetGroup.Standalone)
            AltUnityBuilder.CreateJsonFileForInputMappingOfAxis();
        AltUnityBuilder.InsertAltUnityInScene (buildPlayerOptions.scenes[0]);

        var results = BuildPipeline.BuildPlayer (buildPlayerOptions);
        AltUnityBuilder.RemoveAltUnityTesterFromScriptingDefineSymbols (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:

<UnityPath>/Unity -projectPath $PROJECT_DIR -executeMethod AltUnityTestRunner.RunTestFromCommandLine -tests MyFirstTest.TestStartGame -logFile logFile.log -batchmode -quit

Run tests on a Continuous Integration Server

  1. Instrument your game build with altUnity Tester from Unity or by building from the command line.

  2. Start the game build on a device.

  3. Run your tests - see commands in the “Run tests from the command line” section.

An example CI configuration file can be viewed in the AltUnity Tester 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 AltUnity Server, on a device, you need to tell your AltUnity Driver 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 AltUnity classes.

The following are some cases when Port Forwarded is needed:

  1. Connect to the game running on a USB connected device

  2. 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) or

  • in the test code by using the methods available in AltUnity classes.

  • from AltUnity Tester Editor - Port Forwarding Section

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

For installing ABD, check this article <https://developer.android.com/studio/command-line/adb>_ 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 AltUnity Tester 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

Note

The default port on which the AltUnity Server is running is 13000. Port can be changed when making a new game build or make use of port forwarding if needed.

Connect to AltUnity server running inside the game

There are multiple scenarios on how to connect to the AltUnity Server running inside a game:

  1. Connect to the game running on the same machine as the test code

  2. Connect to the game running on a USB connected device by using Port Forwarding.

  3. Connect to the device running the game by using an IP address

  4. Connect to multiple devices running the game by using Port Forwarding.

  5. Connect to multiple builds of the application running on the same device

Connect to the game running on the same machine as the test code

port forwarding case 1

In this case Port Forwarding is not needed as both the game and tests are using localhost (127.0.0.1) connection and the default 13000 port.

Connect to the game running on a USB connected device

If the device running the game is connected through a USB connection, commands sent to localhost port 13000 can be automatically forwarded to the device.

port forwarding case 2

In this scenario you can use Port Forwarding to enable AltUnity Driver to connect to the device via localhost.

Check Port Forwarding for more details about Port Forwarding and Setup Port Forwarding section on how to make the setup.

Connect to the device running the game by using an IP address

port forwarding case 3

You can connect directly through an IP address if the altUnity server port is available and the IP address is reachable. It is recommended to use Port Forwarding since IP addresses could change and would need to be updated more frequently.

The following command can be used to connect to the altUnity server inside the game:

altUnityDriver = new AltUnityDriver ("deviceIp", 13000); 

Connect to multiple devices running the game

port forwarding case 4

For two devices you have to do the same steps above, by connecting through port forwarding twice.

So, in the end, you will have:

  • 2 devices, each with one AltUnity Server

  • 1 computer with two AltUnity Drivers

Then, in your tests, you will send commands from each of the two AltUnity Drivers.

The same happens with n devices, repeat the steps n times.

Connect to multiple builds of the application running on the same device

If you want to run two builds on the same device you will need to change the AltUnity Server Port.

For example, you will build a game with AltUnity Server running on Server Port 13001 and another one that runs on Server Port 13002.

port forwarding case 5

Then in your tests you will need to instantiate two AltUnity server drivers for each of the Server Ports.

Important

On mobile devices, AltUnity Driver can only interact with a single game at a time and the game needs to be in focus.

On Android/iOS only one application is in focus at a time so you need to switch (in code) between the applications if using two drivers at the same time. This applies even when using split screen mode.

You can change the port for your game build from the AltUnityTesterEditor window inside your Unity project.

altUnity Server Settings

Note

After you have done the Server Port forwarding or connected to the AltUnity driver directly, you can use it in your tests to send commands to the server and receive information from the game.

Using AltUnity Server in Release mode

By default AltUnity Server does not run in release mode. We recommended that you do not build your game in release mode with AltUnity Tester. That being said, if you do want to instrument your game with AltUnity Tester in release mode, you need to uncheck RunOnlyInDebugMode flag on AltUnityRunnerPrefab inside AltUnity Tester asset folder AltUnityTester/Prefab/AltUnityRunnerPrefab.prefab

Logging

There are two types of logging that can be configured in AltUnityTester. The logs from the driver (from the tests) and the logs from the server (from the instrumented game)

AltUnity Server logging

Logging is handled using a custom NLog LogFactory. The Server LogFactory can be accessed here: Altom.Server.Logging.ServerLogManager.Instance

There are two logger targets that you can configure on the server:

  • FileLogger

  • UnityLogger

Logging on the server side can be configured from the driver using the SetServerLogging command:

altUnityDriver.SetServerLogging(AltUnityLogger.File, AltUnityLogLevel.Off);
altUnityDriver.SetServerLogging(AltUnityLogger.Unity, AltUnityLogLevel.Info);

AltUnity Driver logging

Logging on the driver is handled using NLog in C#, loguru in python and log4j in Java. By default logging is disabled in the driver (tests). If you want to enable it you can set the logFlag in AltUnityDriver constructor.

Logging is handled using a custom NLog LogFactory. The Server LogFactory can be accessed here: Altom.AltUnityDriver.Logging.DriverLogManager.Instance

There are three logger targets that you can configure on the driver:

  • FileLogger

  • UnityLogger //available only when runnning tests from Unity

  • ConsoleLogger //available only when runnning tests using the Nuget package

If you want to configure different level of logging for different targets you can use Altom.AltUnityDriver.Logging.DriverLogManager.SetMinLogLevel(AltUnityLogger.File, AltUnityLogLevel.Info)

var altUnityDriver = new AltUnityDriver (logFlag=false); //starts altunity driver with logging disabled

var altUnityDriver = new AltUnityDriver (logFlag=true); //starts altunity driver with logging enabled for Debug.Level; this is the default behaviour

Altom.AltUnityDriver.Logging.DriverLogManager.SetMinLogLevel(AltUnityLogger.File, AltUnityLogLevel.Info); //set logging level to Info for File target