Advanced Usage

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 AltUnity Tester, your build method must define ALTUNITYTESTER scripting symbol 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 connection to proxy will not initiate. 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 Tester 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();
var instrumentationSettings = new AltUnityInstrumentationSettings();
AltUnityBuilder.InsertAltUnityInScene(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/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();
        var instrumentationSettings = new AltUnityInstrumentationSettings();
        AltUnityBuilder.InsertAltUnityInScene (buildPlayerOptions.scenes[0], instrumentationSettings);

        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.

Using AltUnity Tester in Release mode

By default AltUnity Tester does not run in release mode. We recommended that you do not instrument your Unity application in release mode with AltUnity Tester. That being said, if you do want to instrument your application 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 AltUnity Driver (from the tests) and the logs from the AltUnity Tester (from the instrumented Unity application)

AltUnity Tester logging

Logging inside the instrumented Unity application is handled using a custom NLog LogFactory. The Server LogFactory can be accessed here: Altom.AltUnityTester.Logging.ServerLogManager.Instance

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

  • FileLogger

  • UnityLogger

Logging inside the instrumented app 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 enableLogging in AltUnityDriver constructor.

Logging is handled using a custom NLog LogFactory. The Driver 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)

/* start altunity driver with logging disabled */
var altUnityDriver = new AltUnityDriver (enableLogging=false);

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

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