Virtual Remote USB Devices (vUSB) with TestGrid

Overview

Virtual USB (vUSB) is a mobile debugging tool that replicates the experience of connecting a TestGrid Real Devices Cloud to your personal computer via a USB cable. This allows you to debug applications using your preferred in-house development and testing tools as if the device were directly connected to your workstation.
Key Features:

• Build and deploy apps directly from any IDE (e.g., Android Studio, Xcode).
• Streamline early-stage development workflows.
• Combine live and automated testing as per your requirements.
• Monitor device performance metrics such as CPU consumption, memory usage, and network performance (dependent on your IDE/tools).

Note:  Virtual USB is intended exclusively for debugging purposes. It supports local-hosted automation script execution and manual connections, and it currently supports iOS 16 and earlier versions.

Prerequisites

• TestGrid account credentials.
• A system running Windows, macOS, or Linux.
• Administrative rights to install software on your machine.
• Java Development Kit (JDK) installed.

For iOS App Testing:

• macOS or Linux (not supported on Windows).
• Xcode installed (macOS only).

For Android App Testing:

• Android Debug Bridge (ADB) version 1.0.39 or higher.
• Android Studio version 4 or higher.

Step 1: Go to the TestGrid Portal and find a left-side navigation Virtual USB option.

• After clicking on the Virtual USB option, you will see the option to download virtual USB.jar.

Step 2: Establish a Connection to the Real Device Cloud

Open a terminal (Command Prompt on Windows or Terminal on macOS/Linux) on your local machine and run the appropriate command below to start the Virtual USB (Remote USB) connection.

For Android Devices

java -jar RemoteUSB.jar Server \
  --userToken <your_user_token> \
  --server https://<your_domain>.testgrid.io/ \
  --is_android true \
  --is_socket true

For iOS Devices

sudo java -jar RemoteUSB.jar Server \
  --userToken <your_user_token> \
  --server https://<your_domain>.testgrid.io/ \
  --is_ios true \
  --is_socket true

Once the command is executed successfully, a virtual USB tunnel will be established between your local machine and the TestGrid real device cloud. You can then proceed with local automation execution or manual debugging using the connected device.

Note: Virtual USB requires Java version 20 or higher. Please ensure that Java 20+ is installed and properly configured on your local machine before proceeding.

Learn how to obtain your user token.

Step 3: Accept Application Execution

A pop-up will appear requesting permission to execute the application. Click Allow. After executing the command, the session data log will run in the background. Do not close the session or the terminal.

For Notarization Steps (macOS-Users)
To avoid repeated macOS notarization prompts and permission popups, follow these one-time setup steps for each new release:

a) Download and Extract the Latest Package

• Download the latest ZIP package provided.
• After extraction, locate the cli-mac.dmg file.
• Double-click the .dmg file to mount it.
• Inside, you’ll find two cli executable files.

b) Copy both CLI files and put on “executables”

• Copy both cli files.
• Paste them into the designated executable folder (used by the Virtual USB feature)

⚠️ Important: This step ensures the files are properly notarized and will eliminate the repeated permission popups on macOS.
Once this setup is completed:

• You can proceed with the normal process as usual.
• macOS permissions will only be requested during this initial setup.
• Future runs will not trigger notarization popups unless a new release is installed.
• In case of a new release, simply repeat the above steps.

Step 4: List and Manage Available Devices

Use the following commands to view and manage devices connected through Virtual USB.

List Available Devices

Run the command below to retrieve a list of all available devices along with their status, connection details, and server information:

Check Device Status

To check the status of all devices, use:

To check the status of a specific device (whether it is free or in use), use:

Restart Services

If you encounter connectivity issues or the system becomes unresponsive, restart the Virtual USB services using:

Restarting the services can help resolve common connection or synchronization issues.

Step 5: Connect to a Device

To start a virtual USB session with a specific device, run the following command:

Once the connection is successful, the terminal will display a confirmation message indicating that the device has been connected and is ready for use.

Step 6: Verify Device Connection

After successfully connecting to the device, verify the connection using the appropriate method based on the platform.

iOS (Xcode)

For iOS devices, the connected device will appear in Xcode, allowing developers to design, build, test, and debug applications using a unified workflow.

Android (Command Line / Android Studio)

For Android devices, you can verify the connection using either Android Studio or the command line.

To mirror and confirm the connected device via the command line, run:

If the device is connected successfully, the Android device screen will be displayed, confirming that the virtual USB connection is active.

Step 7: Disconnect the Device

To disconnect a device from the Virtual USB session and release it back to the cloud, run the following command:

Once the command executes successfully, the terminal will display a confirmation message indicating that the device has been disconnected.

Troubleshooting Guide: Device List Command Issues

While running the device list command, you may encounter certain errors. The following sections explain common issues and how to resolve them effectively.

1. Error: java.io.IOException: HTTP Error: 500

Cause: This error indicates a server-side issue.

Solution
Please contact the TestGrid support team for assistance:
📧 support@testgrid.io

2. Error: adb devices Shows Devices as offline

Cause
This occurs when ADB (Android Debug Bridge) loses connectivity with the device.

Solution

1. Stop the ADB server:

   adb kill-server

2. Restart the ADB server:

   adb start-server

3. Retry the device list command.

4. Ensure the device is properly connected and authorized for debugging.

3. Restart Virtual USB Services

If device connectivity issues persist, restart the Virtual USB services using the following command:

Restarting services often resolves unresponsive or stale connections.

4. Ensuring Seamless Execution

After restarting the ADB server or Virtual USB services:

1. Re-run the Virtual USB JAR file.

2. Execute the device list command again.

This should re-establish a proper connection and successfully fetch the list of available devices.

5. Configure ADB for sudo Users (macOS / Linux)

If ADB commands fail when using sudo, configure the secure path for sudo users by running:

This ensures ADB is accessible when commands require elevated permissions.

Conclusion

With Virtual USB, debugging and automation become seamless and efficient—allowing you to leverage TestGrid Real Devices Cloud as if the devices were physically connected to your local machine. Proper configuration and the troubleshooting steps above help ensure a stable and reliable execution experience.