Private Device Farm

The Private Cloud Listener is an npm package installed on your Mac Mini/Windows machine. It authenticates with QApilot, receives test jobs, and controls the attached devices. Currently this is support for android devices only.

---

Prerequisites

Before starting setup, confirm the following are in place.

Hardware & OS

• Mac Mini or Windows device

• Android device(s) connected via USB, or emulator(s) configured

• Stable network connection between Mac Mini and QApilot servers

Software

• Node.js 18 or later installed

• npm 9 or later installed

• Appium 2.x installed globally (npm i -g appium)

• Android SDK installed and adb available in PATH

• ChromeDriver downloaded (or auto-download enabled)

• Java JDK 11 or later installed

• ANDROID_HOME environment variable set correctly

QApilot Access

• QApilot account (with Tenant Admin role for configuration)

• Access to the QApilot Settings panel

• Private Device Farm feature enabled on your tenant (contact support if not visible)

• Test app uploaded to QApilot and a Test Plan ready to run

Devices

• USB debugging enabled on each Android device

• Each device trusted on the Mac Mini (adb devices shows them as authorized)

• Device screen remains on during testing (disable auto-lock)

• No other ADB sessions active on target devices

---

Setup

Step 1 - Generate credentials in QApilot (Tenent Admin)

1. Sign in to QApilot and navigate to Settings → Private Device Farm.

2. Click Add New Listener.

3. Enter a name for this listener (e.g. mac-mini-lab-01).

4. Copy the Listener Token shown - this is only displayed once.

5. Note your Username, Password, and the Server URL for your tenant.

Store the Listener Token securely. It cannot be retrieved after this step. If lost, generate a new one from the same Settings page.

Credential reference

Field	Description
--username	Your QApilot account email
--password	Your QApilot account password
--token	Listener token generated in this step
--server	Your tenant API URL (e.g. https://api.qapilot.io/)

---

Step 2 - Start the Appium server

Run the following command on the same Mac Mini where the listener is installed:

appium \
  --port 4723 \
  --allow-insecure chromedriver_autodownload,adb_shell \
  --base-path=/wd/hub \
  --allow-cors

Configuration reference

Flag	Value	Purpose
--port	4723	Port Appium listens on
--allow-insecure	chromedriver_autodownload	Auto-downloads matching ChromeDriver
--allow-insecure	adb_shell	Allows ADB shell commands for device control
--base-path	/wd/hub	Standard WebDriver base path
--allow-cors	—	Allows cross-origin requests from QApilot

---

Step 3 - Install the Private Cloud Listener

Install (on Mac Mini)

npm i -g qapilot-privatecloud-listener-1.2.0.tgz

Upgrade (existing installations)

npm uninstall -g qapilot-listener
npm i -g qapilot-privatecloud-listener-1.2.0.tgz

Start the listener

qapilot-listener \
  --username <your-email> \
  --password <your-password> \
  --token <your-listener-token> \
  --server https://api.qapilot.io/

When the listener starts successfully, it will appear as Online in Settings → Private Device Farm in QApilot.

---

Step 4 - Assign devices in QApilot

1. Go to Settings → Private Device Farm in QApilot.

2. Confirm your listener shows as Online.

3. Devices detected by the listener will appear in the device list.

4. Assign each device a display name and set its state to Active.

---

Step 5 - Configure app and test management

1. Upload your .apk file via App Management in QApilot.

2. Open your test plan and assign it to one or more private devices.

3. Set the execution environment to Private Device Farm.

4. Save and run a test to verify the end-to-end connection.

---

Validation Checklist

Run through these checks after completing setup to confirm everything is working correctly.

• Listener appears as Online in QApilot Settings

• All target devices show in the device list with correct names

• adb devices shows all physical devices as authorized

• Emulators are visible and in a running state

• Appium server responds at http://localhost:4723/wd/hub/status

• Test app is uploaded and visible in App Management

• Test suite is assigned to at least one private device

• A manual test run completes without connection errors

• Test results appear in the QApilot results dashboard

• Pass / fail status is captured correctly

• Device state updates to Busy during a test run

• Device state returns to Online after a test completes

• CI/CD pipeline trigger reaches private devices (if applicable)

• No ADB conflicts observed during parallel test runs

• ChromeDriver auto-download succeeds on first WebView test

• Listener reconnects automatically after a network interruption

---

Security Considerations

• The Listener Token grants access to your QApilot tenant. Treat it like a password and store it in a secrets manager, not in plain text or source control.

• Devices on the private farm are isolated to your tenant and are not shared with other QApilot users.

• Rotate listener tokens periodically via Settings → Private Device Farm.

• Restrict Mac Mini access to authorised personnel only. Anyone with machine access can view running Appium sessions.

• Use a dedicated QApilot service account for the listener rather than a personal account.

---

Troubleshooting

Listener shows as Offline Check that the listener process is running on the Mac Mini. Verify the --server URL and credentials are correct. Confirm outbound HTTPS access to api.qapilot.io is not blocked by a firewall.

Devices not appearing in QApilot Run adb devices on the Mac Mini and confirm devices show as authorized. Restart the ADB server with adb kill-server && adb start-server, then restart the listener.

Appium fails to start Verify ANDROID_HOME is set and that adb is available in your PATH. Ensure no other process is using the specific port 4723.

Tests fail immediately with a connection error Confirm Appium is running and the base path is set to /wd/hub. Check that the correct device UDID is being passed to the test configuration.