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.2.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

Anthelion runs on both macOS and Windows. Follow the steps for your operating system. On either platform, the required runtimes (Java JDK, Android SDK, Node.js, Python) are downloaded automatically on first launch — see First Launch & Setup.

macOS

1. Obtain the installer. You will receive a .dmg file (e.g., Anthelion-Standalone-1.2.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.

Windows

1. Obtain the installer. You will receive an .exe file (e.g., Anthelion Orchestrator Setup 1.2.0.exe).
2. Run the installer by double-clicking it. You can accept the default install location or choose your own, then follow the prompts to finish. A Start Menu entry and a desktop shortcut are created automatically.
3. Launch Anthelion Orchestrator from the Start Menu or the desktop shortcut.

Android Device Setup (USB Debugging)

To test on a physically-connected Android device, you must enable Developer options and USB debugging so Anthelion can detect and drive the device. This applies on both macOS and Windows.

1. Enable Developer Options

1. On the Android device, open Settings → About phone (on some devices: About device → Software information).
2. Find Build number and tap it seven times. You will see a “You are now a developer” confirmation.

2. Enable USB Debugging

1. Go to Settings → System → Developer options (the exact location varies by manufacturer).
2. Turn on USB debugging.
3. Connect the device to your computer with a USB cable. On the device, an “Allow USB debugging?” prompt appears — tap Allow (tick Always allow from this computer to avoid being asked again).

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. Its test suites and 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 a suite — for example daily_smoke_suite — click Run, and choose your device. Anthelion automatically installs the Trash Cat app, launches it, and runs the suite's tests in order, capturing screenshots at each step.
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.

Automation Settings

Some runtime behaviour should be decided once for a whole project, not repeated in every suite. That lives in Automation Settings — a single automation.config.json at the root of your workspace, sitting next to workspace.config.json in the explorer. It is version-controlled with the project, so the whole team shares one definition.

What you can set

• Native permission dialogs — how OS permission popups (camera, microphone, …) are handled while tests run. Accept automatically (the default) lets the framework grant them; turning on "Let tests handle them" provisions the session with auto-accept off so tests drive the prompt themselves — for decline testing, compliance checks, or an accept demo.
• Dismissable popups — a catalog of in-game promo popups (a live-ops offer, a returning-player bundle) that a test can dismiss by name with dismiss_popup_if_present(popup="…"), or without naming one at all — dismiss_popup_if_present() watches for any popup in the catalog and closes the first that appears. Each entry names the popup and says how to detect and close it. Because the locators live here rather than in the scripts, moving a popup in the game is a one-line change in this file — every script that guards it follows. See the Popup Guard in the API Reference.

When a suite needs an override

Open a suite's override editor to change either setting for that suite alone. Both controls default to Inherit — leave them there and the suite simply follows the workspace.

• Native dialogs — a three-way choice: Inherit, Accept automatically, or Let tests handle them. Choosing one replaces the workspace value for this suite.
• Popups this suite handles itself — tick any workspace popup that this suite is testing rather than ignoring. That takes it out of the suite's catalog entirely, so nothing dismisses it here by any route, and the suite's own script is free to drive it.

A suite can only subtract from the catalog. It can never define a popup of its own, because two definitions of the same popup is exactly the drift Automation Settings exists to remove. If an override ends up matching the workspace settings anyway, the editor offers to Remove override so the file does not linger as dead weight.

If you open a workspace created before Automation Settings existed, the app offers to move the old per-suite keys into it for you in one click. Until you accept, those old keys are ignored and the workspace runs on defaults.

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.
• Stop on failure — whether the suite run halts at the first failing script.

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

Native permission dialogs and dismissable popups are not suite settings — they are shared across the workspace in Automation Settings, which a suite may override where it genuinely differs.

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.

One concern per file

Anthelion auto-imports every helper file in a helpers folder, so you never edit an index or registry to add one. Because of that, keep one concern per file and name each file for what it does — _login.py, _menu_navigation.py, _currency_asserts.py — rather than collecting everything into a single module. Single-purpose files keep shared code easy to find, share, and override, and produce smaller, clearer diffs. The starter _common_helper.py you see in a new workspace is just a seed: rename it for its concern and add sibling files as new concerns appear.

Workspace vs Suite helpers

Helpers live at two levels, and the closer level wins:

• Workspace Helpers — the workspace-level folder, shared by every suite. Put cross-suite utilities here (login flow, common navigation, domain assertions).
• Suite Helpers — a helpers/ folder inside a single suite, scoped to that suite. A suite helper overrides a workspace helper of the same name, so a suite can specialize shared behavior without affecting the rest.

Prefer the workspace level for anything two or more suites use; drop down to suite level only for suite-specific behavior.

Creating & using a Helper Script

Select the Workspace Helpers node (or a suite's helpers node) in the explorer and add a new script — it is created in the corresponding helpers directory and auto-imported. In a test, bring all in-scope helpers in with from helpers import * and call one by passing your test case, e.g. _login(self); the helper receives it as tc and can use tc.ant_driver and the tc.assert* methods.

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).
• If a promo popup appears mid-recording, tap its close control as you normally would, then turn that step into a popup guard from the staging area — not from the hierarchy menu. See Guarding a popup.
• 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.
• Guarding a popup. Turn a recorded tap into a popup guard with the 🛡️ optional toggle — see below.

Guarding a popup

A promo popup — a live-ops offer, a returning-player bundle — may appear on some runs and not others. A recorded tap on it fails on the runs where it never shows. A popup guard is the fix: it handles the popup if it's there and skips cleanly if it isn't.

1. While recording, tap the popup's close control on the device so the step is captured like any other tap.
2. Click the 🛡️ optional toggle on that step in the staging area.
3. A confirmation dialog opens and waits for you — nothing is written until you accept it. Usually it shows the locators, the timeout, and which of the two forms below it will use; when the recorder can't tell which popup you meant it asks instead (see below). Cancel writes nothing and leaves the step a normal tap.
4. Confirm, and the recorded tap is replaced by the guard.

Which form you get depends on whether the popup is already in Automation Settings:

A new workspace starts with an empty catalog, so the inline form is what you'll see first. To switch a guard to the shared by-name form: add the popup to Automation Settings, then guard the step again — the dialog will now recognise it.

When the recorder has to ask

Sometimes the dialog can't settle the match on its own — the object you tapped could belong to more than one catalogued popup, or its name matches an entry that doesn't say where that popup lives. Rather than guess, the dialog shows a pick-list:

• Nothing is preselected, and Add guard stays disabled until you choose. A default here would be the same silent guess the question exists to avoid.
• Each candidate shows why it matched and its detect locator; ones that couldn't be confirmed are badged unconfirmed.
• None of these is always an option — take it when the popup genuinely isn't in your catalog, and you get the inline form.

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

What Anthelion Does Not Support

Anthelion automates functional testing of your game's own content — UI, gameplay, scenes, and in-game flows. A few things fall outside that scope by design. This section documents them so expectations are clear.

Third-party ads (ad testing & ad dismissal)

There are two independent reasons for this:

• Ad networks prohibit automated interaction with live ads. Every major network treats clicks or impressions generated by automated tools on live ads as invalid traffic, which can lead to suspension of your ad account and clawback of earnings. Their published policies direct developers to use test ads for any testing — and test ads do not reflect real ad demand, so automated ad delivery cannot be meaningfully validated in the first place.
• Ads render outside the game and cannot be closed programmatically. Fullscreen ads are drawn by the ad SDK at the operating-system layer, outside the Unity scene that Anthelion drives. The ad SDKs also deliberately provide no way to close or dismiss a displayed ad from code — by design, only the end user can close it.

Sources (ad-network policies): Google AdMob — Invalid traffic and How you can prevent invalid activity (“Clicking live ads in your own app is not allowed. Use test ads”); AppLovin — Policies for Publishers (“Impressions and clicks on ads must be the result of legitimate human end user activity”).