Using the Command Line Toolset to Run Unity Tests

In the game development cycle, Quality Assurance and testing can be tedious and time consuming. Because of this, these tasks are all too often delayed for small studios. Things like critical bug fixes or new features typically take a higher priority and time is not consistently spent on automated testing solutions.

That said, every so often a bug gets leaked into a release or a mysterious compile error crops up in the main code repository, making the need for testing clear again. To mitigate these risks, teams will typically perform unit testing with tools like nUnit or Google Test. However, additional steps are required to execute Unity specific code and tests through an automated process.

Having a programmatic way of integrating testing tools with Unity can benefit teams greatly by offloading repetitive tasks like build releases or running unit tests on an automated system. Luckily Unity has an often overlooked feature: its command line toolset. This is available on all supported Unity editor platforms, including the Unity Linux beta. By using the command line toolset, teams can automate events like builds and unit testing.

For our team at KinematicSoup, we chose to use Unity’s command line as it provided us with the flexibility we needed. In our case, when we learned that Unity for Linux supported the command line toolset, we wanted to be able to migrate our deployment and build systems to Linux. To do this, we needed the Windows deployment and asset bundle builder tools we built for our current system to work on Linux in the future. The command line toolset in Unity allowed us to do this, and here’s how:

 

Using Command Line methods

The basic format of invoking Unity command line methods is to call the Unity editor application followed by the command line options:  “/Unity.exe <options>”. In order to do this you will need to know the paths of the installation locations for Unity. The default Unity install locations for Windows, Mac and Linux are as follows:

  • Windows: C:\Program Files\Unity\Editor\Unity.exe
  • OSX: /Applications/Unity/Unity.app/Contents/MacOS/Unity
  • Linux: /opt/Unity/Editor/Unity

Before we discuss how to run custom classes and methods through the command line, let’s briefly review the built in Unity command line options. The built in functions allow you to do things like build an asset package or build a targeted release. The following list is an excerpt from the full documentation.

  • -batchmode - this should always be present when calling Unity from the command line, it lets Unity know not to open pop ups.

  • -nographics - tells Unity to not load any GUI or windows. Unfortunately Unity will still load the Direct X frameworks which will throw errors on systems without graphics capabilities. For example, a headless Linux build machine. We will discuss a work around for this later in the blog.

  • -projectPath <path> - opens the Unity project at the specified path. This will likely also be used every time.

  • -logFile <path> - Unity will redirect the log output to this file. This is really useful for builds and debugging.

  • -buildWindows64Player <build output path> - builds a win64 version of your project.

  • -importPackage <package path> - imports the package at the given location.

  • -exportPackage <Asset Path> <Export Path> - exports the assets at <Asset Path> into an asset bundle at the location and name of <Export Path>.

 

Invoking Custom Methods

The Unity command line functions are often not enough to complete required tasks, which is where the ability to invoke custom methods becomes very helpful. The syntax to call a custom Unity method is as follows:

/unity.exe <parameter1> <parameter2>...<parameterN> -projectPath <project path> -exit -batchmode -executeMethod <nameSpace.class.method>

Where parameter1 through parameterN are strings to pass into your Unity method.

This can be used to call a public static method where the script is saved in an “Editor” folder (resides in a folder in the assets directory with the name “Editor”). Below is an example of a generic C# class that could be called from the command line.                               

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
using UnityEngine;
using UnityEditor;
using System;

Namespace myNameSpace
{
   class myClass
   {
       Public static void myMethod()
       {
          string[] params;
          params = Environment.GetCommandLineArgs();

          //DO SOMETHING 
 
          EditorApplication.Exit(0);
       }
   }
}

In order to parse the command line parameters that are passed in, the Unity class will need to use the query Environment.GetCommandLineArgs(), which will return a string array of arguments. From here you can do whatever is needed, whether making a web request or incrementing a build.

 

Special Notes on building with Headless Systems

When running Unity on a headless system you will need some sort of virtual frame buffer. As previously mentioned, the -nographics option will prevent any windows from loading but still loads the DX11 environment. On Linux the fix is quite simple, just use the xvfb package (on Ubuntu open a console and run “sudo apt-get install xvfb”) then append xvfb-run in front of your Unity command. For example:

 xvfb-run ../unity/Editor/unity…

 

This should give you a basic idea of how to use the Unity command line interface and how it can be used integrate automated tests with Unity. As your team grows, more rigorous testing will be a vital part of ensuring smooth production. Utilizing automated testing can greatly decrease the time it takes to test your software, and provides a tool that can be used consistently throughout development. Interfacing these tests with the Unity platform takes this one step further and gives your tests the flexibility and adaptability required for modern game development.

To learn more about what we are working on to help developers build better games and ship them sooner, check out our Unity multi-user scene collaboration tool, Scene Fusion. 

 

References : http://docs.unity3d.com/Manual/CommandLineArguments.html

Written by Bob Cao, developer at KinematicSoup.