Skip to main content

​
Required Permissions

Qaptly Pilot requires several system permissions to function properly:

​
Accessibility Service

Purpose: Allows Qaptly to interact with UI elements during test automation. Setup Steps:
  1. Open Settings on your device
  2. Navigate to Accessibility
  3. Find Qaptly Pilot or Qaptly Auto Service
  4. Toggle the service ON
  5. Confirm the permission prompt

​
Display Over Other Apps

Purpose: Enables screen streaming and overlay controls. Setup Steps:
  1. Open Settings > Apps > Qaptly Pilot
  2. Tap Appear on top or Display over other apps
  3. Enable the permission

​
Storage Access

Purpose: Required for saving screenshots and test artifacts. Setup Steps:
  1. Open Settings > Apps > Qaptly Pilot
  2. Tap Permissions
  3. Enable Storage or Files and media

​
Initial Configuration

​
First Launch

When you first open Qaptly Pilot:
  1. Welcome Screen: Review the app introduction
  2. Permissions Request: Grant the required permissions
  3. Connection Setup: The app will be ready to connect to Qaptly Desktop
Qaptly Auto splash screen

​
Step-by-Step Setup Guide

After completing the installation process, launch the Qaptly Pilot app to configure required permissions.

​
Step 1: Launch Qaptly Pilot

Open the Qaptly Pilot app from your device’s app drawer. The app will check for required permissions and display their status: Initial setup screen showing required permissions If you completed the installation steps correctly, Developer Mode and USB Debugging should already be marked as Enabled: Developer Mode and USB Debugging completed

​
Step 2: Enable Accessibility Service

Tap the Enable button under Accessibility Service (Required) to open Android Settings: Android Accessibility settings page Scroll down to find the Downloaded apps section and locate Qaptly Auto: Qaptly Auto in accessibility list

​
Step 3: Configure Qaptly Auto Service

Tap on Qaptly Auto to open the service details page: Qaptly Auto service settings Toggle the Use Qaptly Auto switch to ON.

​
Step 4: Confirm Accessibility Permission

When you enable the service, Android will display a security warning explaining what permissions will be granted. Check the box “I’m aware of the possible risks, and assume all possible consequences voluntarily” and tap OK: Accessibility permission warning

​
Step 5: Verify Accessibility Service

After granting the permission, return to the Qaptly Pilot app. You should see the Execution History screen, indicating that the Accessibility Service is now active: In the first time, there is nothing in the list. After some tests, it will be full of entries showing the actions performed by the service. Execution History screen

​
Step 6: Configure Optional Settings (Recommended)

The app will now show optional configurations that improve functionality: Optional settings configuration
  • Battery Optimization (Recommended): Already set to Ignored ✓ - This ensures the service runs reliably in the background
  • Display Over Other Apps (Optional): Tap Configure to enable this if you need screen streaming features
  • Qaptly IME (Optional): Tap Configure to enable Qaptly Input Method for better text input support

​
Step 7: Enable Qaptly IME (Optional)

If you choose to configure Qaptly IME, you’ll be taken to the keyboard settings where you can enable it: Keyboard settings with Qaptly IME Toggle Qaptly IME ON to enable the input method.

​
Step 8: Complete Setup

After configuring all settings, tap the Complete button to finish the setup process. Qaptly Pilot is now fully configured and ready to connect to Qaptly Desktop.

​
Connection to Desktop

Qaptly Pilot connects to the Qaptly Desktop application:
  1. Ensure your device is connected via USB (with USB debugging enabled)
  2. Open Qaptly Mac/Windows
  3. Navigate to Pilot Control
  4. Click on the Devices tab
  5. Start Qaptly Pilot Service
  6. Your device should appear in the device list with Ready status

​
Wireless Connection (ADB over Wi-Fi)

To use Qaptly Pilot wirelessly, you need to enable Wireless Debugging and connect via ADB over Wi-Fi.

​
Prerequisites

  • Your Android device running Android 11 or higher.
  • Your Android device and your computer must be connected to the same Wi-Fi network.

​
Setup Steps

  1. On your Android device, go to Settings > Developer options.
  2. Scroll down and enable Wireless debugging.
  3. Tap on Wireless debugging to enter its settings menu.
  4. Tap Pair device with pairing code. A pop-up will appear displaying a 6-digit Wi-Fi pairing code and an IP address & Port (e.g., 192.168.1.100:44444).
  5. On your computer, open a terminal and run the ADB pair command:
  6. When prompted, enter the 6-digit pairing code shown on your device.
  7. After successful pairing, go back to the main Wireless debugging screen to find the Device IP address & Port (Note: this port is usually different from the pairing port, e.g., 192.168.1.100:5555).
  8. Run the connect command in your terminal:
  9. Once connected, your device will appear in Qaptly Desktop without needing a USB cable.

​
Troubleshooting

​
App Not Appearing in Accessibility Settings

  • Reinstall the app
  • Restart your device
  • Check Android version compatibility

​
Permissions Keep Getting Disabled

  • Check for battery optimization settings
  • Add Qaptly Pilot to the exception list
  • Disable adaptive battery for this app
Related: