- Docs
- Resources
- Agent Pool & Device Farm
- Local device setup
Local device setup
Mobile and desktop tests on your own computer need three things next to the agent: the device or app, Appium on port 4723 and the right driver. These guides walk you through them.
In short
On this page you can
- Install Android Studio, the SDK parts and an emulator for local mobile tests.
- Install and start Appium with one command and keep it running.
- Prepare a Windows PC (Windows driver, WinAppDriver) or a Mac (Mac2 driver, Xcode) for desktop tests.
- Check that SmartestQA sees your phone or emulator and that Appium runs.
How to use it
- Open Device Farm › Test Agents and select your Localhost agent.
- Open Local Emulator Setup (MOBILE) or Local Desktop Setup (DESKTOP on Windows); on a Mac follow the macOS steps on this page.
- Work through the steps with Next; copy each command with its copy icon.
- Start the agent with the API key shown in the last step.
- In MOBILE projects, check Connected Devices for the device and the green Appium chip.
You need
A MOBILE or DESKTOP project, and the SmartestQA agent on the same computer as the device or app (Install an agent). The guides are in Device FarmTest Agents, right panel, second tab. In WEB projects the tab is not shown.
Each guide is a list of steps. Click a step title to jump to it, or use Back and Next. After the last step, Finish shows “You're all set!”; Restart takes you back to step 1. The guide does not check your machine: it tells you what to run and what you should see.
Android emulator on your computer#
Tab Local Emulator Setup, titled Local Android Emulator Setup. Works on Windows, macOS and Linux.
Install Android Studio
The Windows, Mac and Linux buttons open Google’s Android Studio download page. The installer includes the SDK, the emulator and the tools.
Install Required SDK Components
In Android Studio go to More Actions › SDK Manager and make sure these are installed: Android SDK Platform (API 34 or newer), Android SDK Build-Tools, Android Emulator, Android SDK Platform-Tools (adb).
Create a Virtual Device (AVD)
Tools › Device Manager › Create Device. Pick a phone such as Pixel 7, a system image such as API 34 with Google APIs, then Finish.
Start the Emulator
In Device Manager click ▶ next to the virtual device. The emulator window opens within seconds.
Verify the Device with adb
In a terminal run the command below.
Terminaladb devicesThe emulator is listed as
device, notoffline.Install Appium Server
Appium is the bridge between SmartestQA and the device. It needs Node.js; use a current LTS version, because older Node.js versions make the Appium install fail with
ERR_REQUIRE_ESM. Paste this single line: it installs Appium and the Android driver, then starts the server.Terminalnpm install -g appium && appium driver install uiautomator2 && appiumYou see “Appium REST http interface listener started on http://0.0.0.0:4723”. The terminal stays busy; that is the server running.
Connect the Smartest Agent
Start the agent from the Download Client tab with the API key shown in this step (it has a copy icon). When the dot turns green, the emulator is ready.
Do not close the Appium terminal
Appium runs in the foreground of that terminal. Closing it makes the next test fail with “Server Unreachable / ECONNREFUSED 127.0.0.1:4723”. To start it again later, run appium in a new terminal.
A real Android phone works the same way: connect it by USB with USB debugging on, and once adb devices lists it as device, SmartestQA sees it under Real Devices. iOS devices and simulators need the agent on a Mac.
When the device is ready, pick it as the device of your run: in ConfigurationProject PanelMobile Config choose the local device (see Mobile and desktop apps), or select it when you set up a pipeline in Schedule. For recording, see Discover › Mobile.
Windows machine for desktop tests#
Tab Local Desktop Setup, titled Local Desktop (Windows) Setup. The tab covers Windows; for a Mac, see Mac for desktop tests.
Install Node.js
Appium is a Node.js application. Check your version with the command below; Download Node.js (Windows) opens the Node.js download page. Use a current LTS version.
PowerShellnode -vInstall Appium & Windows Driver
Copy the single PowerShell line shown in this step and run it. It downloads and runs the SmartestQA setup script, which installs Appium and the Windows driver, downloads and installs the latest WinAppDriver (Windows asks for administrator approval once), turns on Developer Mode, frees port 4723 and starts Appium.
You see “Appium REST http interface listener started on http://0.0.0.0:4723”. Leave this terminal open.
Enable Developer Mode
If it is still off: Settings › Privacy & Security › For developers, turn Developer Mode on, confirm, and restart if Windows asks. Without it, WinAppDriver crashes mid-session and the test stops with “session terminated / driver unreachable”.
Verify the Windows Driver
Open a second terminal, leaving the Appium one running, and run the command below.
PowerShellappium driver list --installedwindowsis in the list of installed drivers.Connect the Smartest Agent
Start the agent with the API key shown in this step. When the dot turns green, the machine is ready for desktop runs and the Desktop Recorder.
Next: configure the application in Desktop Configuration (see Mobile and desktop apps) and record it with the Desktop Recorder.
Mac for desktop tests#
DESKTOP projects can test macOS apps as well as Windows apps. On a Mac the runner drives the app with Appium’s Mac2 driver, which works through Apple’s XCTest. The Local Desktop Setup tab shows the Windows steps, so prepare a Mac with the steps below. You need an administrator account on the Mac for the setup.
Install Xcode
Install Xcode 13 or newer from the App Store and open it once, so it finishes installing its components. The Command Line Tools alone are not enough. Then make the full Xcode the active one.
Terminalsudo xcode-select -s /Applications/Xcode.app/Contents/DeveloperInstall Appium and the Mac2 driver
Appium needs Node.js; use a current LTS version (check with
node -v). Then install Appium and the Mac2 driver.Terminalnpm install -g appium appium driver install --source=npm appium-mac2-driverVerify the Mac2 driver
Run the commands below. The second one checks the driver’s requirements, such as Xcode, and says what is missing.
Terminalappium driver list --installed appium driver doctor mac2mac2is in the list of installed drivers.Allow the macOS permissions
Open System Settings › Privacy & Security and allow the items in the table below. “The app that runs the agent” is SmartTest-Desktop, or Terminal if you start the agent from a Terminal window. Xcode Helper is in the folder this command opens; drag it into the Accessibility list.
Terminalopen /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Agents/Permission Allow for Needed for Accessibility Xcode Helper and the app that runs the agent Test runs and the Desktop Recorder: clicks, keys and reading the app’s elements. Screen Recording The app that runs the agent Screenshots of recorded steps. Without it, the Desktop Recorder records the steps without screenshots. Input Monitoring The app that runs the agent The Desktop Recorder: capturing your clicks and key presses. Then run this command once, so macOS does not ask for authentication each time a test session starts.
Terminalautomationmodetool enable-automationmode-without-authenticationInstall and connect the macOS agent
In Download Client click Mac (
SmartTest-Desktop-macOS-latest.zip), or copy the macOS command from Install Via CLI (Download Client). Start the agent with your agent’s API key (The API key).The agent’s dot turns green. The Mac is ready for desktop runs and the Desktop Recorder.
Appium must be running when a desktop test starts, at the Appium Server URL of Desktop Configuration (default http://localhost:4723). If Appium is installed but not running, the agent tries to start it; you can also start it yourself with appium in a terminal and leave that terminal open. The first time you open the Desktop Recorder on a Mac, the agent builds its macOS recorder with Xcode, so that first start takes longer.
Next: in Desktop Configuration choose the platform macOS (Mac2Driver) and add the app with its Bundle ID (for example com.example.MyApp) or its App Path (for example /Applications/MyApp.app); see Desktop Configuration. Then record it with the Desktop Recorder.
Check the device: Connected Devices#
In MOBILE projects the agent list has a Connected Devices group under your online Localhost agent. It lists what that agent can reach right now.
- Appium chip: green Appium when the server answers (hover for version and address), red Appium off when it does not, with “Appium server not found” and the hint to run
appiumin a new terminal. - Groups: Real Devices and Emulators / Simulators. An Android project shows only Android devices, an iOS project only iOS devices, a MOBILE project both.
- Empty: “No Android devices found” or “No iOS devices found (macOS agent required)”.
- Refresh asks the agent again. Nothing is shown while the agent is Offline.
- Use Device Live on a device row opens its screen in the browser. See Live device sessions.
If something goes wrong#
- “Appium server not found” / “Appium off”
- “Server Unreachable / ECONNREFUSED 127.0.0.1:4723”
- Appium install fails with ERR_REQUIRE_ESM
- adb lists the emulator as offline
- “No Android devices found” / “No iOS devices found”
- Desktop test stops with “session terminated / driver unreachable”
- “Xcode is missing or not selected (macOS)”
- “A macOS permission is missing”
Didn’t find your answer?Write to support with your project name and what you see on screen.
info@smartestqa.ai