Learn how to install and use the GameDriver Test Assistant (TA) to work with your automated game or application testing
Introduction
The 2025.01 release of the GameDriver Test Assistant, or TA, is the first iteration of an entirely new way of developing, executing, and maintaining automated tests for video games and other applications built using 3D/Game engines. The TA is a standalone application that is fully independent of the engine. This allows you to connect to the running game or application under test, and do things that would normally require the engine editor, such as querying objects at runtime, recording user inputs, and viewing application logs.
Getting Started
First, download the Test Assistant from the GameDriver.io/download page. Once downloaded, simply run the executable (i.e. GameDriverTA-v1.x.x-winx64-setup.exe)
Windows will likely open a dialog indicating that the application is unknown, or requires Administrative privileges. If you encounter the dialog below, select “More info” then “Run anyway”.
> 
Setup will continue, and files will then be installed on your computer.
Once complete, simply run the Test Assistant executable from your Start Menu. Upon the initial launch, you may see a dialog asking for permission to Private and Public networks. This is necessary for the TA to connect to running instances of your game or application.
Windows 11 Firewall permissions dialog
And that’s it! You can use the GameDriver Test Assistant by following the Usage instructions below.
Licensing
Before you get started using the Test Assistant, you will need a license. If you received a license via email or the GameDriver website, simply navigate to the Help > Install (or Update) License menu in the TA application, and locate the .gdtal file containing the license. If you do not have a license yet, you may be required to supply the HostID of your test machine to request one. To obtain your HostID to provide to our team, simply access the Help > About menu in the TA application, and locate the HostID shown.
Usage
Using the Test Assistant is easy. Simply connect to a running instance of a game or application that has the GameDriver Agent embedded, and you can immediately start to see activity and objects in the UI. To initiate a connection, navigate to the Connect > Connection Manager dialog menu. Here you will see any instances of the game engine running on the hostname or IP address shown. To connect to a different machine, enter the hostname or IP address of the machine running the application you wish to test, along with the port number (the default port is 19734), and click Connect.
Querying Objects
Once connected to a running editor or standalone application, you can immediately start to traverse the object tree and capture relevant information for your testing. The Object Explorer is a snapshot of the object tree at any given time, and will automatically refresh every 10s unless manually refreshed. It will also refresh the child objects and properties every time an object is selected.
To inspect the object, simply select it in the tree. If you wish to see the components, methods, or properties of that object, select the object and wait for the query to resolve the underlying values. This usually takes less than a few seconds, depending on the size and complexity of the scene and objects. When selected, the Inspector will update to reflect the value(s) of the selected node.
From the Inspector, you can capture values such as the name, tag, position, or rotation of the object. You can also grab the HierarchyPath to be used for the specific object, component, property, or method shown. This is an important aspect of building or maintaining automated tests as the HPath will allow you to query or manipulate the object directly.
Recording
The Test Assistant Recorder is a quick way to capture inputs and understand what steps were taken by the user. To use the Recorder, simply select the Circle located on the toolbar:
From there, you can perform the actions you intend to automate in your target application. Be sure not to record too many steps at a time, as it will become difficult to determine where one set of actions occurred. Once finished, select the Square logo in the toolbar to stop the recording.
Once stopped, you can see the recorded steps in the NewRecording** window below.
For the initial release of the TA, recorded steps are based on coordinate clicks in the application, along with wait times between steps. Additional steps can be added to the recording using the API auto-complete feature, simply type “api.” and you will see a list of available commands and their usage.
This approach is useful when you need to insert steps such as clicking an object by HPath using ClickObject, or setting an object value using SetObjectFieldValue. In the example below, we have used the Object Explorer to identify the object in the game needed to advance to the start of the level. We simply right-click the object in the Object Explorer and select Copy HierarchyPath. Then we can paste that string into the ClickObject command in the Recording window.
Recording Replay
The initial release of the Test Assistant does not allow for direct replay of recorded or authored steps. This feature is expected to be enabled in a near-term release. To replay recorded or authored events, simply copy and paste these into an existing .NET Class Library as described in our Getting Started guide, and execute the steps there.
Note: Due to the dynamic nature of applications built using game engines, recordings may require some adjustment before use in replay.
Additional Recording Options
- To start a new recording, select the File > New option in the top menu bar of the Test Assistant.
- To regenerate a recording from a recently captured one, select Quick Regeneration.
- To load a previously generated recording from the original .json file, select Open RawEvents file.
- To change the XR Thresholds for recording, select Settings > Recorder Settings.
These settings are described in this KB article on recording settings.
Viewing Logs
The Log Viewer allows you to see logs from the GameDriver Client, TA Diagnostics, or Unity Editor to catch exceptions from the game engine automatically.
Selecting any line from the Log Viewer will show you the details of that message on the right pane of the window.
What’s Next?
We have a lot of features in store for the Test Assistant, but rather than wait until everything was finished and potentially delay the release for another month or quarter, we wanted to put it out as soon as we had feature parity with the tools that exist in the game editors today. This allows us to capture feedback on the tool while new features are added. We’re also able to release the TA much more frequently than the core SDK, which requires much more effort to test across every version of Unity and Unreal Engine, along with the various supported platforms. Some of the features planned for the Test Assistant are listed below, in no specific order.
- Test Replay: Run authored or recorded tests directly in the TA.
- Recording Enhancements: Record object interactions, insert comments, checkpoints, and more…
- Low Code Test Creation: Drag-and-drop style test creation.
- Model-based Testing: Capture and store object references as part of the test case, allowing for more complex and powerful test definitions.
- Localization Quality Assurance: Additional features targeting LQA use cases such as AI-assisted language comparison, visual verification of text rendering, and more…
- Multi-host Testing: Connect to multiple running application instances for multi-player test execution.
- Test Debugging: Breakpoints, call stacks, assertions, API REPL, and trace-level logging
- Image and Video Categorization: Machine-learning enabled visual comparison, object tracking, and more…
- Defect Management Integration: Send test failures directly to your defect management system, such as Jira or Bugzilla.
- Device Cloud Integration: Connect directly to device clouds for on-device testing, such as Kobiton.
Note: Features mentioned above are not guaranteed to be delivered, or that they will be delivered on a specific timeline.
Frequently Asked Questions
- Intended Users: Is TA primarily targeted at QA testers who don’t have development experience, or is it also meant for developers looking for a more streamlined test creation workflow?
Answer: The TA can be used by anyone involved in the testing process.
- Integration with Existing Workflows: How does TA integrate with existing GameDriver-based test automation setups? Can it export tests that plug directly into existing .NET frameworks (NUnit, XUnit, etc.), or is there a different execution mechanism?
Answer: Upon initial release, the TA does not have built-in test execution capabilities. However, this is planned for a near-term release. When available, the TA will include a base implementation of NUnit to allow for ease of playback of recorded or authored test steps. Additional functionality will require the recorded or authored steps to be exported to a .NET class.
- Recorder Functionality: The document mentions that Replay is coming soon—will this allow full playback of recorded interactions for automated execution, similar to traditional UI test recorders?
Answer: Yes, and no. Games and applications developed in game engines are notoriously non-deterministic. As a result, some modification of the recorded steps is usually required to make the test more replayable.
- Will recorded test steps (from the Recorder) be exportable as .NET test scripts for integration with NUnit/XUnit?
Answer: The initial release requires test steps to be exported to a test framework such as NUnit/XUnit, or BDD framework such as SpecFlow. However, future releases this will be optional.
- How does Object Explorer handle deeply nested objects—does it provide full object trees or only selective properties?
Answer: In order to keep requests to the running application lightweight, the TA
- Does the GameDriver TA require the GameDriver Agent to be embedded in the build, or can it connect to a remote instance without modification?
Answer: Currently the GameDriver Agent needs to be pre-built into the application under test in order to operate. This may change in the future.
- What are the differences between using Test Assistant vs. writing tests manually with the GameDriver SDK?
Answer: Currently the main difference between using the TA versus the traditional approach is that you need to have access to the application
- Can Test Assistant be used for end-to-end automation across different devices (e.g., starting in a PC editor and finishing in an XR headset)?
Answer: The Test Assistant can connect to the application running on a PC, Mobile Device, Console, or XR device/headset. The initial release is mainly intended for test creation and maintenance by connecting to the application running on the device or PC, but test replay is planned for a near-term release.
- How does Test Assistant handle dynamic objects that are instantiated at runtime?
Answer: All objects are accessible to the Test Assistant, including those that are created dynamically.
- What level of access does TA have to private and protected Unity object properties/methods?
Answer: The TA has access to all methods attached to objects and components running in the application.
- How does Test Assistant maintain object references between sessions when working with dynamically changing UI elements or game objects?
Answer: The TA does not currently maintain object references between sessions. All object information is dynamically captured and displayed.
- Does TA support automation across networked multiplayer sessions? If so, how are multiple agents managed?
Answer: The initial release is limited to a single session, but multiple-session test execution is planned for a future release.
- Does the TA support Unity and Unreal Engine?
Answer: The initial release supports Unity only, but Unreal Engine is planned for a very near-term release.
- Does the TA support macOS and Linux?
Answer: The initial release is Windows-only, but macOS is planned for a future release.