Get Started

To run the first test for your Unreal app you need to:

Download the AltTester® Plugin
Set up the AltTester® Unreal SDK in your project
Start the AltTester® Server Module
Run your app in Unreal Editor or on desired platform
Write and execute first test for your app

Note

If you don’t have access to the source code of the app, you need to ask a person with access to provide you with a version of the app that includes the AltTester® Plugin.

Download the AltTester® Plugin

To add the AltTester® Unreal SDK to your Unreal application, you first need to download the AltTester® Plugin. You can obtain it by visiting the AltTester® website.

Important

To download the AltTester® Plugin on macOS, you can use the wget command for convenience. Otherwise, if downloading via a browser, ensure to either allow the files from Privacy & Security Settings if macOS prevents the file from being opened or remove the quarantine attribute from the downloaded files.

Please check the Troubleshooting section for more detailed instructions on how to solve this problem.

Set up the AltTester® Unreal SDK in your project

Extract the AltTesterUnrealSDK-Package.zip: Unzip the downloaded file and navigate to the Plugin folder.

Move the AltTester-Unreal-SDK folder: Place the AltTester-Unreal-SDK folder into the UE_5.x\Engine\Plugins\Marketplace directory (Note: If the Marketplace folder does not exist, create it manually).
Open your project in Unreal Engine: Once your project is loaded, go to the top toolbar, click Edit, and then select Plugins from the dropdown menu to open the Plugins browser.

Enable AltTester®: In the Plugins browser, search for AltTester using the search bar, and check the Enabled box next to the AltTester® icon.

Restart the editor: A prompt will appear at the bottom of the Plugins window indicating that the editor must be restarted for the changes to occur. Restart the editor to complete the process.

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 Unreal project.

Start the AltTester® Server Module

The AltTester® Server Module is incorporated in AltTester® Desktop. In order to start it, all you have to do is to open AltTester® Desktop.

Compatibility matrix for AltTester® Unreal SDK and AltTester® Desktop

	AltTester® Desktop	AltTester® Driver
AltTester® Unreal SDK versions	2.2.x	2.2.x
v.1.0.x	✓	✓

Run your app in Unreal Editor or on desired platform

Before running your tests you need to start the instrumented Unreal application. Upon startup, your instrumented Unreal app should display a popup with the message: “Waiting for connections on port: {Port}”. The popup disappears when your app has successfully connected to the tests.

Write and execute first test for your app

To write tests with AltTester® SDK you need to import the AltDriver in your tests project.

AltTester® package contains AltDriver class used to connect to the instrumented app. 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 Unreal objects and interact with the app.

Prerequisite:

.NET installed.
Instrumented build.
The AltTester® Desktop installed on your PC.

Connection:

The AltTester® Desktop must be running on your PC while the tests are running.

The AltTester® Desktop app is running.
The instrumented build is running.
Configure the IP of the build in order to match the IP of the machine (PC) the Desktop app is running on.
Then press the restart button in the AltTester® dialog and wait until the Connected to AltTester® Server… message is displayed in the dialog.

Test Setup:

You can use any IDE you want. As a suggestion, we prefer Visual Studio Code.
To be able to run our test scripts, we should use a testing framework. For this tutorial, we will use the NUnit testing framework.
In order to use NUnit, you should start by creating an NUnit project. To do this, you need to create an empty folder (this will be the project folder) and open it in Visual Studio Code. Open a terminal (we preferred git bash) and run the command below. This command will create a basic NUnit project for you:

dotnet new nunit

To be able to interact with the game through your tests, you need AltDriver. To add the AltDriver to your testing project, all you need to do is to use the following command in your terminal:

dotnet add package AltTester-Driver --version x.y.z

Note that the x.y.z is the version of AltDriver you want to install.

Writing tests:

There are many ways in which the project can be organized. We suggest using the Page Object Model design pattern to organize your project into pages folders and tests folders.
To initialize the AltDriver in your project, you should import it. You can do it by using the following syntax: using AltTester.AltTesterUnitySDK.Driver;.
After that you can initialize the AltDriver: altDriver = new AltDriver();.

Note: At the moment, we use the same AltDriver for both the AltTester Unreal SDK and the AltTester Unity SDK, which is why the namespace includes AltTesterUnitySDK. However, this will be updated in the future to better reflect its usage with the Unreal SDK.

Running the tests:

To run your test, open a terminal window in the project folder and paste the following command:

dotnet test

Example test file:

using NUnit.Framework;
using AltTester.AltTesterUnitySDK.Driver;

public class MyFirstTest
{
    private AltDriver altDriver;

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

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

    [Test]
    public void TestStartGame()
    {
        altDriver.LoadScene("MainMenu");

        altDriver.FindObject(By.NAME, "Close Button").Click();
        altDriver.FindObject(By.NAME, "Button").Click();

        var panelElement = altDriver.WaitForObject(By.NAME, "Panel");
        Assert.IsTrue(panelElement.enabled);
    }
}

using AltTester.AltTesterUnitySDK.Driver;
using AltTester.AltTesterUnitySDK.Driver.AltReversePortForwarding;
using NUnit.Framework;

public class MyFirstTest
{
    private AltDriver altDriver;

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

    [OneTimeTearDown]
    public void TearDown()
    {
        altDriver.Stop();
        AltReversePortForwarding.RemoveReversePortForwardingAndroid();
    }

    [Test]
    public void TestStartGame()
    {
        altDriver.LoadScene("MainMenu");

        altDriver.FindObject(By.NAME, "Close Button").Click();
        altDriver.FindObject(By.NAME, "Button").Click();

        var panelElement = altDriver.WaitForObject(By.NAME, "Panel");
        Assert.IsTrue(panelElement.enabled);
    }
}

Prerequisite:

Java installed.
Instrumented build.
The AltTester® Desktop installed on your PC.

Connection:

The AltTester® Desktop must be running on your PC while the tests are running.

The AltTester® Desktop app is running.
The instrumented build is running.
Configure the IP of the build in order to match the IP of the machine (PC) the Desktop app is running on.
Then press the restart button in the AltTester® dialog and wait until the Connected to AltTester® Server… message is displayed in the dialog.

Test Setup:

You can use any IDE that works with Java, but for this setup tutorial, we will use IntelliJ.
In order to have the structure already created for us and the possibility to install/update dependencies in an easy way, we can choose to create a MAVEN project.
In the new pom.xml generated, you should add the alttester and junit dependencies (and make sure to use the latest AltTester® driver version):

<dependency>
    <groupId>com.alttester</groupId>
    <artifactId>alttester</artifactId>
    <version>2.2.0</version>
</dependency>

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter-engine</artifactId>
    <version>5.11.0-M1</version>
</dependency>

When you have these steps completed and you don’t have any errors, you are able to jump into the next section.

Writing tests:

There are many ways in which the project can be organized. We suggest using the Page Object Model design pattern to organize your project into pages folders and tests folders.
To initialize the AltDriver in your project, you should import it. You can do it by using the following syntax: import com.alttester.AltDriver;.
After that you can initialize the AltDriver: driver = new AltDriver();.
Considering that we’re using JUnit as a testing framework, you can find more information about JUnit in its official documentation.

Running the tests:

Considering that we are using IntelliJ, the tests can be run using the runner that is inside of it. More information about this can be found in the official documentation of IntelliJ.

Example test file:

import org.junit.AfterClass;
import org.junit.Assert;
import org.junit.BeforeClass;
import org.junit.Test;
import com.alttester.AltDriver;
import com.alttester.AltObject;
import com.alttester.Commands.FindObject.AltFindObjectsParameters;
import com.alttester.Commands.FindObject.AltWaitForObjectsParameters;

import java.io.IOException;

public class myFirstTest {

        private static AltDriver altDriver;

        @BeforeClass
        public static void setUp() throws IOException {
                altDriver = new AltDriver();
        }

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

        @Test
        public void openClosePanelTest() {
                altDriver.loadScene("MainMenu");

                AltFindObjectsParameters closeButtonObjectsParameters = new AltFindObjectsParameters.Builder(
                                AltDriver.By.NAME, "Close Button")
                                .build();
                altDriver.findObject(closeButtonObjectsParameters).Click();

                AltFindObjectsParameters buttonObjectsParameters = new AltFindObjectsParameters.Builder(
                                AltDriver.By.NAME, "Button")
                                .build();
                altDriver.findObject(buttonObjectsParameters).Click();

                AltFindObjectsParameters panelObjectsParameters = new AltFindObjectsParameters.Builder(
                                AltDriver.By.NAME, "Panel")
                                .build();
                AltWaitForObjectsParameters panelWaitForObjectsParameters = new AltWaitForObjectsParameters.Builder(
                                panelObjectsParameters).build();
                AltObject 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 com.alttester.AltReversePortForwarding;
import com.alttester.AltDriver;
import com.alttester.AltObject;
import com.alttester.Commands.FindObject.AltFindObjectsParameters;
import com.alttester.Commands.FindObject.AltWaitForObjectsParameters;

import java.io.IOException;

public class MyFirstTest {

    private static AltDriver altDriver;

    @BeforeAll
    public static void setUp() throws IOException {
            AltReversePortForwarding.reversePortForwardingAndroid();
            altDriver = new AltDriver();
    }

    @AfterAll
    public static void tearDown() throws Exception {
            altDriver.stop();
            AltReversePortForwarding.removeReversePortForwardingAndroid();
    }

    @Test
    public void openClosePanelTest() {
            altDriver.loadScene(new AltLoadSceneParams.Builder("MainMenu").build());

            AltFindObjectsParams closeButtonObjectsParameters = new AltFindObjectsParams.Builder(
                            AltDriver.By.NAME, "Close Button")
                            .build();
            altDriver.findObject(closeButtonObjectsParameters).Click();

            AltFindObjectsParams buttonObjectsParameters = new AltFindObjectsParams.Builder(
                            AltDriver.By.NAME, "Button")
                            .build();
            altDriver.findObject(buttonObjectsParameters).Click();

            AltFindObjectsParams panelObjectsParameters = new AltFindObjectsParams.Builder(
                            AltDriver.By.NAME, "Panel")
                            .build();
            AltWaitForObjectsParams panelWaitForObjectsParameters = new AltWaitForObjectsParams.Builder(
                            panelObjectsParameters).build();
            AltObject panelElement = altDriver.waitForObject(panelWaitForObjectsParameters);

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

Prerequisite:

Python installed.
Instrumented build.
The AltTester® Desktop installed on your PC.

Connection:

The AltTester® Desktop must be running on your PC while the tests are running.

The AltTester® Desktop app is running.
The instrumented build is running.
Configure the IP of the build in order to match the IP of the machine (PC) the Desktop app is running on.
Then press the restart button in the AltTester® dialog and wait until the Connected to AltTester® Server… message is displayed in the dialog.

Test Setup:

We suggest using the git bash terminal type for all the commands below.
You can use any IDE you want. As a suggestion, we prefer Visual Studio Code and PyCharm.
To actually run the tests we need a test framework. One of the most popular python testing frameworks is pytest which is easy to download because you just need to use the following command in your terminal:

pip install pytest

To be able to interact with the game through your tests, you need AltDriver. It contains all the methods you need such as click(), wait_for_object(), find_object() and so on. To add the AltDriver to your testing project, all you need to do is to use the following command in your terminal:

pip install AltTester-Driver

The following setup steps are not mandatory, but if you choose to use them, you will act like a pro.

Install assertpy - for easy and nice assertions.
Most of the time on a project, you will have to provide some reports with the results of your tests. In order to provide them, you can use pytest-html-reporter which generates nice and detailed reports with the results of your tests. To install pytest-html-reporter use the following command:

pip install pytest-html-reporter

Writing tests:

There are many ways in which the project can be organized. We suggest using the Page Object Model design pattern to organize your project into pages folders and tests folders.
The AltDriver can be used in your code after you import it. Here is the import syntax: from alttester import AltDriver, then you can instantiate an object of AltDriver type: alt_driver = AltDriver() . By doing this, you are able to use all the methods that come from AltDriver().
Considering that we are using pytest, the names of the tests should start with test.

Running the tests:

Running tests using pytest can be easily done using the commands for cmd.
Run all the tests: navigate through the cmd in the folder that contains the tests folder and use the following command:

pytest tests/

Run a specific test file: navigate into the tests folder and use the following command:

pytest test_name.py

Run a specific test method from a file: navigate into the tests folder and use the following command:

pytest test_name.py -k name_of_test_you_wanna_run

For running tests with the HTML reporter, all you have to do is to add this extra argument to your running command:

--html-report=./report/report.html.

This will generate a report under the report folder.

Example test file:

import unittest

from alttester import *


class MyFirstTest(unittest.TestCase):

    alt_driver = None

    @classmethod
    def setUpClass(cls):
        cls.alt_driver = AltDriver()

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

    def test_open_close_panel(self):
        self.alt_driver.load_scene("MainMenu")

        self.alt_driver.find_object(By.NAME, "Close Button").click()
        self.alt_driver.find_object(By.NAME, "Button").click()

        panel_element = self.alt_driver.wait_for_object(By.NAME, "Panel")
        self.assertTrue(panel_element.enabled)

import unittest

from alttester import *


class MyFirstTest(unittest.TestCase):

    alt_driver = None

    @classmethod
    def setUpClass(cls):
        AltReversePortForwarding.reverse_port_forwarding_android()
        cls.alt_driver = AltDriver()

    @classmethod
    def tearDownClass(cls):
        cls.alt_driver.stop()
        AltReversePortForwarding.remove_reverse_port_forwarding_android()

    def test_open_close_panel(self):
        self.alt_driver.load_scene("MainMenu")

        self.alt_driver.find_object(By.NAME, "Close Button").click()
        self.alt_driver.find_object(By.NAME, "Button").click()

        panel_element = self.alt_driver.wait_for_object(By.NAME, "Panel")
        self.assertTrue(panel_element.enabled)

Prerequisite:

Robot Framework installed.
Instrumented build.
The AltTester® Desktop installed on your PC.

Connection:

The AltTester® Desktop must be running on your PC while the tests are running.

The AltTester® Desktop app is running.
The instrumented build is running.
Configure the IP of the build in order to match the IP of the machine (PC) the Desktop app is running on.
Then press the restart button in the AltTester® dialog and wait until the Connected to AltTester® Server… message is displayed in the dialog.

Test Setup:

You can use any IDE you want. As a suggestion, we prefer Visual Studio Code and PyCharm.

Writing tests:

First you need to create a new project with a Robot class under it, which can store your tests
In the Settings section:
- Import the AltTesterLibrary
- Next create the Setup and Teardown suites for your tests
  
  In the Setup suite you need to include the initialization of the AltDriver - make sure to also add the ip, host and app name as parameters if the connection data for the connected instrumented app is not the default one
  
  In the Teardown suite the AltDriver needs to be stopped

*** Settings***
Library    AltTesterLibrary
Suite Setup    Initialize Altdriver
Suite Teardown    Stop Altdriver 

The Test Cases section stores all your tests which should have a specific and relevant name

*** Test Cases ***
Test My First Test

Running the tests:

To run your test use the robot commmand

Robot Framework test cases are created in files and directories, and they are executed by giving the path to the file or directory in question to the selected runner script

Examples:
robot my_first_test.robot
robot path/to/my_tests/
After running the test the Robot will generate 3 files: report.html, log.html and output.xml - the html files can be opened in the browser and for every test in log.html there will be a status highlight, the keywords used, as well as a potential error that might have occured during the test

Example test file:

*** Settings***
Library    AltTesterLibrary
Suite Setup    Initialize Altdriver
Suite Teardown    Stop Altdriver 

*** Test Cases ***
Test Open Close Panel
    Load Scene    MainMenu
    ${close_button}=    Find Object    NAME    Close Button
    Click Object    ${close_button}
    ${button}=    Find Object    NAME    Button
    Click Object    ${button}
    ${panel_element}=         Wait For Object    NAME         Panel
    Should Be True    ${panel_element.enabled}

*** Settings***
Library    AltTesterLibrary
Suite Setup    SetUp Tests   
Suite Teardown    Teardown Tests    

*** Test Cases ***
Test Open Close Panel
    Load Scene    MainMenu
    ${close_button}=    Find Object    NAME    Close Button
    Click Object    ${close_button}
    ${button}=    Find Object    NAME    Button
    Click Object    ${button}
    ${panel_element}=         Wait For Object    NAME         Panel
    Should Be True    ${panel_element.enabled}
    
*** Keywords ***
SetUp Tests
    Reverse Port Forwarding Android
    Initialize Altdriver

Teardown Tests
    Stop Altdriver
    Remove Reverse Port Forwarding Android

Now your project can use all the AltDriver Commands.

Note

Before the connection step, start the instrumented app and wait for the green popup with the message: Waiting to connect to AltTester® Server on IP:port with app name: ‘your app name’.