Device automation and automatic setup

A phone that DK Studio cannot drive is a phone you test by hand. Every platform the studio supports has its own automation surface, and the platform prepares it for you: the studio knows what the platform needs, the agent installs it on the bench, and the studio reports what came of it.

This page describes the automatic setup chain, what each platform's automation requires, and how to read the state the studio keeps for every device.

The automatic setup chain

When a device connects to a bench, the studio runs one chain for it. The chain is four commands, and each command is an ordinary agent command — visible, re-runnable and accountable on the command log.

Step	Command	What it does
Check	app_status	Asks the device whether the automation package is already installed.
Fetch	fetch_artifact	Downloads the driver package from the platform onto the bench.
Install	install_app	Installs the downloaded package on the device.
Automate	start_automation	Brings the automation surface up and reports its endpoint.

The check comes first on purpose. A phone that already carries the automation package is in the middle of somebody's session, and reinstalling over it would interrupt work that is already running. Only the device knows what is on it.

Who starts the chain

The chain starts in three ways, and they mean the same thing.

A phone arrives. The rule for that platform decides. With the rule on, the platform starts the chain for a device the moment it connects.

Somebody asks. An operator on the bench presses Start runner on a phone, and the agent finds out the driver is not on it. The agent does not improvise — the signed driver lives on the platform, so the agent asks the platform to install it, and the platform runs the very same chain. The bench waits; the runner comes up by itself.

A task is dispatched. A run reaches a phone, and the phone has to be able to automate: the driver on the device, the automation surface up. The studio checks that before it hands the task over. If the phone is not ready, the studio runs the same chain while the task waits on the command log. The task goes out by itself once the chain reaches Ready; if the chain stops on a failure, the task ends with that failure code instead of hanging.

The automation goes away. The automation endpoint lives on a host port of the bench, so the platform cannot see whether it is still there — only the bench can. The bench watches it: when the endpoint stops answering, because a phone was unplugged or a runner died, the bench says so and the studio records that device as no longer ready. The next task that reaches it runs the chain again. The driver is still on the phone, so the chain only has to bring the endpoint back up.

When the platform has no driver configured for that platform, it says so immediately rather than leaving the operator waiting: the driver has to be uploaded and bound to the platform first, under Admin → Device setup. The bench reports where the chain stopped and why — the step it reached, the failure code, and the tool's own words about it. A phone whose driver refuses to install says exactly that on the bench, not only on the platform.

What each platform needs

The three platforms differ in what automation means to them. The studio models this as two kinds of driver.

iOS — WebDriverAgent

iOS automation is WebDriverAgent: a runner app that exposes a WebDriver endpoint on the device.

Driver package	A signed WebDriverAgent runner: an .ipa, or the .app archive the lab builds
Package id	The bundle id of the runner, for example com.facebook.WebDriverAgentRunner.xctrunner
On the device	Developer mode on, the bench trusted by the device
On the bench	go-ios, with its tunnel running
Automation surface	A WebDriver endpoint on a host port of the bench — every device gets one of its own

The bench installs the signed package the same way any other application is installed on iOS, and the automation endpoint answers /status once the runner is up.

Android — the uiautomator2 server

Android automation is the uiautomator2 server: an instrumentation server that runs on the device and speaks WebDriver from there.

Driver package	A signed .apk of the uiautomator2 server
Package id	The package of the uiautomator2 server, for example io.appium.uiautomator2.server.test
On the device	USB debugging on, and the device authorised for this bench
On the bench	adb
Automation surface	A WebDriver endpoint on a host port of the bench — every device gets one of its own

The device serves the automation on its own port 6790; the bench forwards that port to the configured host port, so the studio reaches the phone at http://127.0.0.1:<hostPort> from the bench. The endpoint answers /status once the server is up.

HarmonyOS — the device's own uitest

HarmonyOS ships its automation with the device. There is no separate driver to install: the device's own uitest command is the automation surface, spoken over hdc.

Driver package	None — the device's uitest is built in
Package id	The bundle name of the app under test, for example com.example.app
On the device	Developer mode on, and the device authorised over hdc
On the bench	hdc
Automation surface	uitest over hdc — dumpLayout, uiInput, screenCap, uiRecord

Because the surface is a command surface rather than an HTTP endpoint, HarmonyOS has no automationUrl. The studio records that the device is ready, and the commands themselves are what an operator sees.

Rules and manual runs

A setup rule is one per platform, and it holds three things: whether automatic setup runs, which driver package to install, and which host port the automation answers on. The rule applies to the whole bench pool of that platform. On HarmonyOS there is no host port — the entry point is a command on the device, not an endpoint.

The rule governs the automatic trigger only. When an operator asks for a device to be set up by hand, the flow runs regardless of whether the rule is on — the rule decides what happens when a phone is plugged in, not what a person is allowed to do.

What the studio records

Every device carries the outcome of its last setup, so the panel can say why a phone is not ready rather than only that it is not.

Field	Meaning
installed	Whether the automation package is on the device
lastStep	The furthest step the chain reached: check, fetch, install, automation, ready
lastError	Why the chain stopped, when it stopped
automationUrl	The WebDriver endpoint, on the platforms that have one

The failure codes are:

Code	Meaning
DRIVER_NOT_CONFIGURED	No driver package is configured for this platform
DRIVER_NOT_INSTALLED	The driver package is not on the device
ARTIFACT_UNAVAILABLE	The driver package could not be fetched
INSTALL_FAILED	The driver package could not be installed
DEVICE_UNREACHABLE	The device did not answer
AUTOMATION_UNAVAILABLE	The device has no automation capability — check developer mode
AUTOMATION_START_FAILED	The automation did not come up in time
AUTOMATION_LOST	The automation was up and then went away — the bench reported it

A device that stopped on a failure can be run again from the same page; the rerun starts the chain from the top and overwrites the previous outcome.

Where this lives in the interface

The setup rules, the drivers you have uploaded, and the live state of every connected device are on one page, under Admin → Device setup. Upload a driver package, turn the rule on for its platform, and connect a phone: the page shows the device reaching Ready, with the endpoint it answers on.