Anthelion User Guide

Professional test automation for mobile games. Record, script, execute, and analyze tests across Android and iOS with Unity engine support.

System Requirements

Unity SDK Setup

The Anthelion SDK integrates into your Unity project as a package. It embeds a lightweight communication layer that enables test automation and live hierarchy inspection.

Installation

1. Locate the SDK package. You will receive a .tgz file (e.g., com.anthelion.sdk-1.0.0.tgz) alongside the desktop application installer.
2. Open your Unity project and navigate to Window → Package Manager.
3. Click the + button in the top-left corner and select "Add package from tarball...".
4. Browse to and select the .tgz file. Unity will import the com.anthelion.sdk package and resolve its dependency (com.unity.nuget.newtonsoft-json).
5. Build your game normally. No code changes or manual initialization required. The SDK initializes automatically at runtime and remains dormant unless launched through Anthelion.

Supported Commands

The SDK ships with 25+ built-in commands including FindObject, Tap, Drag, SetText, GetText, GetHierarchy, CaptureScreenshot, LoadScene, and more. These are invoked remotely by test scripts and the Anthelion orchestrator.

Install the Desktop Application

1. Obtain the installer. You will receive a .dmg file (e.g., Anthelion-Standalone-1.0.0.dmg).
2. Open the DMG and drag Anthelion.app into your Applications folder.
3. Launch Anthelion from Applications. The application is notarized and signed, so it will open without any security prompts.

iOS Device Setup (WebDriverAgent)

Before you can run tests on any iOS device, you must build and sign WebDriverAgent (WDA) once on your machine. WDA is the bridge that lets Anthelion drive iOS devices; without a signed build of WDA from your Apple Developer account, iOS device automation will not work.

You will need:

• An Apple Developer account (free or paid) signed into Xcode.
• Xcode installed and launched at least once to accept the license agreement.
• The iOS device connected via USB and unlocked.

One-Time Setup Steps

These steps mirror the Settings → iOS Device Setup panel inside the Anthelion application. You can perform the setup from either location.

1. In Anthelion, open Settings and click Open WebDriverAgent in Xcode. Xcode will launch with the bundled WDA project.
2. In the Xcode scheme selector at the top of the window, select WebDriverAgentRunner (not WebDriverAgentLib or IntegrationApp).
3. In the Xcode sidebar, select the WebDriverAgent project (blue project icon at the top).
4. Select the WebDriverAgentLib target → Signing & Capabilities tab → enable Automatically manage signing and choose your Apple Developer Team from the dropdown.
5. Select the WebDriverAgentRunner target and repeat the same signing setup (automatic signing, your Team).
6. Change the WebDriverAgentRunner Bundle Identifier to a unique value, for example com.yourcompany.WebDriverAgentRunner. Xcode will reject duplicates if the default identifier is already registered.
7. Connect your iOS device via USB and select it as the build destination in the Xcode toolbar.
8. Clean the build folder with Cmd+Shift+K, then run the tests with Cmd+U. Xcode will build, sign, install, and launch WDA on the device.
9. On the iOS device itself, open Settings → General → VPN & Device Management and trust the developer certificate that was just installed. Without this step, iOS will refuse to launch WDA.

First Launch & License Activation

On first launch, Anthelion runs a one-time setup that installs required runtimes and starts infrastructure services. This typically takes 2–5 minutes.

Step 1: Activate Your License

A license activation dialog appears automatically. Enter your license key in the format:

XXXXX-XXXXX-XXXXX-XXXXX

Click Activate. The license is validated and bound to your machine. You will see confirmation with your license details including expiration date and licensed features.

Step 2: Automated Infrastructure Setup

After license activation, Anthelion automatically installs and configures the required runtime environment. A progress bar displays each phase:

Step 3: Ready

Once setup completes, you are taken to the Dashboard. Connect a device via USB to begin testing.

Sample Project: Trash Cat

Anthelion ships with a complete sample project built on Unity's Trash Cat (Endless Runner) game. This gives you a working example to explore before integrating the SDK into your own game — pre-built APK/IPA, a ready-made test workspace, and four test scripts covering common automation scenarios.

What's Included

When Anthelion launches for the first time, it automatically sets up the sample project in your Documents folder:

Sample Test Scripts

The default suite includes four test scripts that demonstrate key Anthelion capabilities:

Try It: Run the Sample Tests

1. Open the workspace. In Anthelion, go to Workspace and open the TrashCatAutomationWorkspace folder. The default suite and its four test scripts appear in the explorer.
2. Connect a device. Plug in an Android or iOS device via USB. It appears in the Devices page.
3. Run the suite. Select the default_suite, click Run, and choose your device. Anthelion automatically installs the Trash Cat app, launches it, and executes all four tests sequentially.
4. Review results. After execution, go to Results to see pass/fail status, screenshots, video recordings, and detailed logs for each test.

Integrating the SDK into Your Own Game

When you're ready to test your own game, the SDK integration is identical to how it's set up in the Trash Cat sample:

1. Open your Unity project and go to Window → Package Manager.
2. Click the + button and select "Add package from tarball...". Choose the .tgz SDK package file that ships with Anthelion.
3. Build your game normally for Android (APK) or iOS (Xcode project → IPA). No additional configuration needed — the SDK auto-initializes at runtime.

Application Pages

Anthelion organizes its interface into five main pages, accessible from the sidebar navigation on the left.

Additional pages include Settings for application configuration and license management.

Dashboard

The Dashboard is your landing page after startup. It provides:

• System Status — server connection state, connected device count, and active session indicators.
• Workspace Management — list of known workspaces with options to create, open, or remove workspaces. Click any workspace to open it in the Workspace page.
• Quick Actions — create a new workspace or open an existing folder as a workspace.

Devices

The Devices page shows all connected devices detected by Appium Device Farm.

• Device Table — lists each device with its name, platform (Android/iOS), OS version, connection type, and current status (online/offline/busy).
• Filters — filter devices by platform, OS version, status, or connection source.
• Device Actions — select a device to install apps, uninstall apps, or launch installed applications.
• Auto-Refresh — the device list refreshes automatically every 10 seconds.

Workspace

The Workspace is the primary interface for test development. It uses a three-panel layout: file explorer on the left, script editor in the center, and execution panel on the right. See the Workspace section below for full details.

Results

The Results page displays your complete test execution history. Each result shows status, device, duration, and pass/fail counts. Click any result to view detailed logs, video, screenshots, and callstacks. See the Results section below for full details.

Settings

The Settings page provides application configuration:

• Device Communication — enable or disable the Multipeer Bridge for iOS device connectivity over the local network.
• Cloud Providers — configure integrations with cloud device farms (AWS Device Farm, LambdaTest, etc.) for running tests on remote devices.
• License Management — view your current license status, days remaining, and customer details. Deactivate your license if transferring to another machine.
• Issue Reporting — report bugs or feature requests directly from the application, optionally attaching logs for troubleshooting.

Workspace

The Workspace is where you build, record, and execute tests. It is organized into three panels and a menu bar.

The menu bar at the top provides dropdown menus for workspace, script, build, compilation, execution, and save operations.

Creating Test Suites & Scripts

Create a Test Suite

1. Open the Workspace menu in the menu bar or right-click in the explorer panel.
2. Select "Add Suite". Enter a name for the suite. A new folder is created in your workspace directory.
3. The suite appears in the explorer tree. Expand it to view its scripts.

Add a Test Script

1. Select a suite in the explorer, then go to Script → Add Script (or right-click the suite).
2. Enter a script name and choose the language (Python, C#, or Java). Python is the primary language for test scripts.
3. The script opens in the center editor with a template including imports, setup, and teardown boilerplate.

Suite Configuration

Each suite has a configuration (suite.config.json) that defines:

• Script execution order — the sequence in which scripts run during suite execution.
• Script inclusion — which scripts are included in the suite run.
• Default build per platform — which APK or IPA to install before tests.

Select a suite and click the configuration icon to edit these settings in a visual editor.

Managing Builds

Use Build → Add Build Files to import your game's APK (Android) or IPA (iOS) into the workspace. Set a build as the default for its platform so tests automatically install the correct build.

Helper Scripts

The Workspace Helpers folder is a special section in the explorer for shared utility code. Helper scripts are available to all test scripts in the workspace but are not executed directly as tests.

Use Cases

• Common setup and teardown routines shared across multiple tests.
• Utility functions for game-specific operations (e.g., login flows, menu navigation).
• Reusable assertion helpers for your game's domain.

Creating a Helper Script

Select the Workspace Helpers node in the explorer and add a new script. The script is created in the helpers directory and can be imported by any test script in the workspace using standard Python imports.

Recording Tests

Recording lets you interact with your game on a real device and automatically capture those interactions as test script commands.

Start a Recording Session

1. Open a test script in the editor that you want to record into.
2. Go to Execution → Record Script from the menu bar.
3. Select the target device from the device dropdown. Only online devices matching the script's target platform are shown.
4. Select the build file (APK/IPA) to install. Anthelion automatically suggests the default build for the device's platform.
5. Click Start Recording. Anthelion installs the build, launches the game, and begins capturing interactions.

During Recording

• Play your game normally on the device. Every tap, swipe, drag, and text input is captured as a test command.
• The device screen streams live in the right panel. Click on the stream to trigger a raycast that identifies UI elements under that point.
• The hierarchy tree updates in real time showing the game's current scene objects. Right-click any object to add commands via the context menu.
• Captured commands appear in the staging area (or are inserted directly into the script, depending on mode).
• Use Pause to temporarily stop capturing while you navigate menus or perform setup actions you don't want recorded.

End Recording

Click Stop Recording. Any remaining staged commands can be reviewed and inserted. The script in the editor now contains all recorded commands.

Live Screen Streaming & Raycast

The device screen viewer shows a real-time MJPEG stream of your device during recording or test execution.

Screen Interaction (Raycast)

Click anywhere on the device stream to perform a UI raycast. Anthelion sends the screen coordinates to the game's SDK, which identifies the UI element at that position. The matching element is then highlighted in the hierarchy tree, making it easy to:

• Discover the name and path of any visible UI element.
• Right-click the highlighted element to generate commands for it.
• Inspect component properties in the inspector panel.

Orientation

The viewer auto-detects portrait/landscape orientation. You can also toggle orientation manually using the rotation button.

Command Staging Area

The staging area is a review buffer between command capture and script insertion. It operates in two modes:

Working with Staged Commands

• Each command displays a compact header with sequence number, command type badge, description, and timestamp.
• Click to expand a command and see the generated code preview, source badge (auto-recorded, inspector, hierarchy), and metadata.
• Click Insert on a single command to add it to the script at the current cursor position.
• Click Insert All to batch-insert all staged commands.
• Click Remove to discard a command, or Clear All to start fresh.

Context Menu & Auto Script Generation

Right-clicking any object in the hierarchy tree opens a context menu with commands organized by category. Each command generates the corresponding Python code and sends it to the staging area (or directly to the script).

Command Categories

Smart Filtering

The context menu automatically adapts to the selected object:

• Drag commands only appear for draggable elements (Sliders, Scrollbars).
• Set Text only appears for editable InputFields.
• Get Text appears for Text, TextMeshPro, and InputField components.
• Physics Raycast appears for objects with 3D colliders; UI Raycast for Canvas elements.
• Find Object uses the most specific locator available (TAG > NAME > PATH).

Property Inspection & Modification

For advanced validation, select an object in the hierarchy to open the Inspector Panel. This shows all components attached to the GameObject and their properties. You can:

• View current property values in real time.
• Generate get_component_property commands to read properties in scripts.
• Generate set_component_property commands to modify properties during test execution.
• Call custom methods on components via the Call Method dialog.

Lua Scripting for Gameplay Automation

Anthelion supports Lua scripts that execute directly inside the Unity game runtime. Unlike Python test scripts that run externally and send commands over the network, Lua scripts run on the device within the game process.

When to Use Lua

• Complex gameplay automation — when you need frame-level control or access to internal game state that isn't exposed through the standard command API.
• Performance-critical sequences — Lua executes locally without network round-trips.
• Game-specific logic — automate boss fights, crafting sequences, inventory management, or other complex multi-step gameplay.

Adding a Lua Script

1. Create a Lua file in your workspace or add an existing .lua file.
2. Write your automation logic using the Anthelion Lua API, which provides access to the game's scene objects and components.
3. Reference the Lua script from your Python test using the execute_lua command, which uploads and runs the script on the device.

Running Tests

Run a Single Script

1. Open the script you want to run in the editor.
2. Go to Execution → Play Script, or use the play button in the toolbar.
3. Select the target device from the device selection dialog. You can select multiple devices to run the script in parallel.
4. The test is queued on each selected device and execution begins.

Run a Full Suite

1. Select the suite in the explorer.
2. Go to Execution → Play Suite.
3. Select target device(s). All scripts in the suite run in the configured order on each device.

Parallel Execution

Select multiple devices in the device selection dialog to run tests in parallel across devices. Each device executes independently with its own progress tracking.

Execution Panel

The right panel shows real-time execution status for each device:

• Progress bar with current execution phase (Installing App, Launching, Connecting, Executing, Cleanup).
• Active execution card showing the running script and elapsed time.
• Queue of pending scripts waiting to run.
• Cancel buttons to stop individual executions or entire suite runs.

Compilation (C# / Java)

If your test scripts or helper scripts use C# or Java (supplementary languages), you need to compile them before execution:

• Compilation → Compile File — compile the currently open script.
• Compilation → Compile Suite — compile all scripts in the selected suite.
• Compilation → Compile Workspace — compile all scripts in the workspace.

Compilation output is displayed in a dedicated modal showing success/failure and error messages.

Results

The Results page is your central hub for reviewing test execution outcomes. It displays a chronologically ordered history of all test runs.

Results List

Each result is displayed as a card showing:

• Status badge — Running (blue), Completed (green), Failed (red), Cancelled (grey).
• Script or suite name and the device it ran on.
• Duration of the execution.
• Pass/fail counts for suites (e.g., "3/5 passed").
• Timestamp of when the execution started.

Suite Grouping

When running a suite, individual script results are grouped under the suite execution. The suite card shows aggregate statistics (total scripts, passed, failed) with expandable per-script details.

Active Sessions

A pulsing badge on the Results navigation item indicates how many tests are currently running. Active sessions appear at the top of the results list with live status updates.

Pagination

Results are paginated (20 per page) with server-side pagination for performance. Navigate between pages using the pagination controls at the bottom.

Result Details

Click any result card to open the Test Results Viewer, which provides comprehensive diagnostic information organized into tabs:

Video Recording

When available, the results viewer includes an embedded video player showing a recording of the device screen during test execution. This is invaluable for understanding visual bugs, animation issues, and the exact sequence of UI changes.

Downloading Results & Reports

Anthelion provides two download formats for test results:

How to Download

• From the Results list: each result card has download icons for ZIP and HTML.
• From the Test Results Viewer: use the download buttons in the top-right corner of the detail modal.

Quick Reference

Test Script Structure (Python)

import unittest
from anthelion_driver import AnthelionDriver

class MyGameTest(unittest.TestCase):

    def setUp(self):
        self.driver = AnthelionDriver()
        self.driver.connect()

    def test_main_menu(self):
        # Find and tap a button
        btn = self.driver.find_object(by="name", value="PlayButton")
        btn.tap()

        # Wait for a scene element
        self.driver.wait_for_object(by="path", value="/Canvas/GamePanel")

        # Capture a screenshot
        self.driver.capture_screenshot("game_started")

        # Assert an element exists
        score = self.driver.find_object(by="name", value="ScoreText")
        self.assertIsNotNone(score)

    def tearDown(self):
        self.driver.disconnect()

if __name__ == '__main__':
    unittest.main()

Common Workflows