appium-altunity-plugin
Advanced tools
An Appium 2.0 plugin that gives direct access to the AltUnity tester server
This is an Appium 2.x plugin for AltUnity Tester.
The motivation behind this plugin is to make AltUnity Tester completely compatible with Appium, so that an Appium user doesn't need to learn the AltUnity API or download any extra clients or tools. In addition, it enables access to the excellent AltUnity Tester functionality while not being bound by the particular programming language requirements of that project (C# or Python).
The big idea behind AltUnity Tester in general is to allow for easier automation of Unity games, across all Unity platforms (mobile, desktop, etc...). While Appium already provides solid automation capabilities for UI-based apps, games tend to not use standard UI components and thus present themselves as a single opaque element to automation. AltUnity Tester is a Unity component you can include in your game that exposes a special websocket server from within the instrumented game. This allows for communication "into" the Unity context from the outside world, enabling inspecting of objects and triggering behaviours. The other half of AltUnity Tester is a set of client libraries used to speak to the WebSocket server more easily. These are written in Python and C#.
Many testers want to use both Appium and AltUnity, since Appium provides a lot of device automation features outside of what's happening in-game. Without this plugin, test authors needed to mix and match Appium and AltUnity API clients. With this plugin, test authors can stay entirely within the Appium scriptwriting paradigm and still take advantage of the power of AltUnity Tester.
UNITY context, within which other functionality is made availableExample: if the AltUnity Tester port is 13000, and you're running on an Android device,
you'll want to use ADB to forward the port to one on your system:
adb forward tcp:13000 tcp:13000
Use the Appium plugin manager to install the most recent version of this plugin:
appium plugin install --source=npm appium-altunity-plugin
Then, when you start the Appium server, you need to ensure you have enabled the plugin for that
particular server instance, by including it in the list of plugins to use. The short name of this
plugin is altunity:
appium --use-plugins=altunity
In terms of the client side of this plugin, no special installation is required as the plugin does not introduce any new commands, but rather makes use of existing Appium commands.
Note: each Appium client library has its own conventions and command names. The examples given here use the WebDriverIO client library. Any Appium library will work just as well with this platform, but you may have to search the docs of another library in case the command names or conventions differ slightly from what is provided here.
When you start a session with this plugin active, two new capabilities are required in addition to whatever capabilities would normally be required to launch the app/game:
altUnityHost: a string, indicating on which host Appium can find the AltUnity socket serveraltUnityPort: a number, indicating on which port the AltUnity socket server is listeningUNITY ContextAll of this plugin's features are hidden behind a new context. This ensures that normal platform
automation is not affected and allows for switching back and forth between the normal 'native'
context and the AltUnity integration. When the plugin is active, you will see UNITY returned in
the list of available contexts. To enter into the UNITY context, simply use the setContext
command:
await driver.setContext('UNITY')
While in the UNITY context, you can take advantage of the other features.
To get the hierarchy of the current Unity scene, simply call:
await driver.getPageSource()
It will return an XML document that you can use as the basis for element finding operations. An example source document is available here.
The plugin supports a subset of the locator strategies available in Appium.
| Strategy | Behaviour | Example |
|---|---|---|
xpath | Query the source XML for matching element(s) | driver.$('//Player') |
id | Find an object by its id or AltId | driver.findElement('id', 'foo') |
css selector | Find an object by its id or AltId* | driver.$('#foo') |
link text | Find an object by its text | driver.$('=text') |
tag name | Find an object by its type | driver.$('<Player>') |
Note that the
css selectorstrategy is only provided as an alias forid, since many client libraries no longer supportiddirectly.
From the perspective of your client library, what you get back from a call to find element(s) is a normal WebElement object. However, from the perspective of Appium, it is not the same as a native UI element. It is instead a reference to an AltUnity object. Accordingly, it has a smaller set of possible interactions, which is outlined below.
Click/tap the element at its coordinates on the screen. This method does not call the click or tap methods provided by AltUnity Tester since I generally found it to be easier to simply tap the appropriate screen position. That way its functioning doesn't depend on whether some element is or isn't on top of some other element.
await element.click()
Check whether the element is on the screen. The plugin decides this based on whether the x and
y values of the element are within the bounds of the screen dimensions as reported by Appium.
await element.isDisplayed()
Get the coordinates of an element.
width and height values of the response will be set to 0 until I figure out how to
retrieve those reliably.x and y values represent the center-point of the element (not top-left as is usual)const {x, y} = await element.getLocation()
const {width, height} = await element.getSize()
Get the text displayed in an element, if it has any, or null otherwise.
const text = await element.getText()
Get an attribute of an element. The only attributes retrievable in this method are the ones that you see in the source XML.
const name = await element.getAttribute('name')
You can define keypress sequences using the W3C WebDriver Actions API. With this plugin, key string
identifiers are taken from this enum. In other words, if you want to
press the escape key, you will need to use the string Escape, or the numeric code defined in the
enum, 27.
Here's an example of how to press and release the escape key with a 750ms pause in between:
await driver.performActions([{
type: 'key',
id: 'keyboard',
actions: [
{type: 'keyDown', value: 'Escape'},
{type: 'pause', duration: 750},
{type: 'keyUp', value: 'Escape'},
]
}])
And here's an example of how to hold down the right arrow button for a longer duration, pressing and releasing the spacebar in the middle (to simulate running and jumping in a platformer game, let's say):
const runWithJump = {
type: 'key',
id:'keyboard',
actions: [
{type: 'keyDown', value: 'RightArrow'},
{type: 'pause', duration: 1500},
{type: 'keyDown', value: 'Space'},
{type: 'pause', duration: 500},
{type: 'keyUp', value: 'Space'},
{type: 'pause', duration: 500},
{type: 'keyUp', value: 'RightArrow'},
{type: 'pause', duration: 1000},
]
}
await driver.performActions([runWithJump])
Touch actions have not yet been implemented. Currently, only clicking found elements is possible.
You can load a Unity scene by its scene name using the set URL / navigate command. When doing so,
use unity:// as the scheme.
await driver.navigateTo('unity://SceneName')
You can get the currently active scene name as well. It will also use the unity:// scheme.
const curScene = await driver.getUrl()
You can get the current game time scale using a special executeScript overload command which takes no arguments. The value will be returned as a float:
const scale = await driver.executeScript('unity: getTimeScale', [])
Likewise you can set the time scale to adjust game speed, using unity: setTimeScale, which takes
a single float parameter, representing the desired time scale:
// run the game at 1.5x speed
await driver.executeScript('unity: setTimeScale', [1.5])
If you don't want to use the Appium plugin but are more interested in using AltUnity directly from TypeScript or JavaScript, you can also take advantage of the AltUnity client developed to enable this plugin. It is located in src/client and exports all types. You can import it in your own Node.js projects like this:
import { AltUnityClient } from 'appium-altunity-plugin'
This assumes that you have added this project to your package.json, for example by:
npm install --save appium-altunity-plugin
Contributions to this plugin are welcome! It is developed under the Apache 2 license.
First, clone the repo:
git clone git@github.com:projectxyzio/appium-altunity-plugin.git
Then change into the repo dir and install dependencies:
npm install
Finally, transpile the project:
npm run build
It's always a good idea to run all tests before making any changes. First, get the sample app used in testing:
npm run pretest
Then, make sure Appium is using the local clone of this plugin (run from the plugin repo dir):
appium plugin uninstall altunity
appium plugin install --source=local $(pwd)
appium --use-plugins=altunity
Then ensure you have an Android emulator or device active and connected via ADB, that it is the only device showing in the device list, and that you have forwarded port 13000:
adb forward tcp:1300 tcp:1300
Finally, make sure adb is available in your PATH. Now you're ready to run the tests!
npm run test:unit
npm run test:e2e
It's a good idea to set things up to automatically transpile any time you save a change to a file:
npm run watch
And remember that anytime you change and transpile the plugin, you'll need to stop and start the Appium server for the changes to take effect.
FAQs
An Appium 2.0 plugin that gives direct access to the AltUnity tester server
The npm package appium-altunity-plugin receives a total of 70 weekly downloads. As such, appium-altunity-plugin popularity was classified as not popular.
We found that appium-altunity-plugin demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Ransomware negotiators share how modern cybercriminals operate like corporations, using specialized teams, negotiation tactics, and reputation management.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.