The Sauce Labs Cookbook

Sauce Headless

Front End Performance Testing


External Resources

More Info

Page tree
Skip to end of metadata
Go to start of metadata

Virtual USB for Real Devices simulates connecting a real device with a USB cable directly to your local machine during a live or automated testing session. This will allow you to interact directly with a device in the Sauce Labs cloud via an integrated development environment (IDE) like Android Studio and Xcode, or browser-based tools like Chrome DevTools and Safari Web Inspector.

With Virtual USB, you can use homegrown developing and testing tools because it integrates into the development environment as if the device was directly connected to the workstation. When you debug your applications, Virtual USB provides the ability to build and deploy an application directly from the IDE. You can also directly monitor device performance metrics such as CPU consumption, device memory, and network data performance.

NOTE - Limited Access: Your access may depend on whether you're using the Legacy platform or the Sauce Labs platform. For more information on upcoming and available features for Real Devices, refer to the feature preview doc.


  • This feature is available only on Private devices
  • For Android, make sure you're using an Android Debug Bridge (ADB) version that is above 1.0.39

Legacy Client Instructions

The information in this topic is for our latest Virtual USB Client release: v1.8.0. If you have a legacy version of the client (v.1.0 - v.1.2), check out Using Early Versions of Sauce Labs Virtual USB

Download the Latest Virtual USB Client

Virtual USB Client 1.8.0 (2020-06-29)

Android Virtual USB

Android Virtual USB Change Log

Click here to see the change log of the Android Virtual USB client.

iOS Virtual USB

Beta note

Virtual USB for iOS Devices is in beta, contact your Customer Success Manager to get access.

iOS Virtual USB change log

Click here to see the change log of the iOS Virtual USB client.

Known Limitations

  • Xcode/Safari has to be closed before connecting to an iOS Virtual USB session (or relaunch it after connecting). Otherwise, the device won't show up.
  • Devices attached to the host locally are not useable while using iOS Virtual USB. When the server is shut down, it asks again for permissions to put the original `/var/run/usbmuxd` socket back into its place, and Xcode/Safari have to be re-launched to show the local devices.

Launch and Connect Virtual USB to a Real Android Device Live Testing Session

Accessing Instructions in the Client

You can also find instructions for using the Virtual USB client by running java -jar vusb-client.jar --help.

  1. Download and install the Virtual USB for Live Testing client to the same machine where you have Android Studio installed. Java is required to run Virtual USB.

  2. Get your User API key from the Account Settings menu in the Sauce Labs Real Device Cloud web interface. 

    Finding Your Real Device API Key

    This is not the same as your project API key, and is specific to your Sauce Labs account.

  3. From a command line, launch the client. You will have to choose between the EU or the US datacenter, depending on which device you are trying to connect to:

    java -jar vusb-client.jar server --datacenter <EU/US>
    java -jar vusb-client.jar server --datacenter EU
  4. Once the server is open, you can now start a session. From another command line window, launch the client again using this command to create a new session:

    java -jar vusb-client.jar startSession --apiKey <API_KEY> --deviceName <DEVICE_NAME>
    java -jar vusb-client.jar startSession --apiKey 37D274BC3A65A34BB3DA4DDF7B77E341 --deviceName Motorola_Moto_Z_real

    Static Allocation

    This will allow you to allocate a device for your session. That means the device will be in use and not available for other uses until your session is over.

  5. When Virtual USB connects to your live testing session, it will return a success message and a link to watch the device running your test in real time. 

    Example of success message
    37D274BC3A65A34BB3DA4DDF7B77E341		Motorola Moto Z		ANDROID		7.0
    localhost:7000	online
  6. Copy the port number and use it to connect adb to your session device using Virtual USB.

    adb connect localhost:<paste returned port here>

    adb connect localhost:7000

  7. At this point, vUSB will be fully connected. You can use Android Studio (or Google Chrome's Remote Debugging) to debug your app, execute automation based on adb, or any other tool that is adb-compliant. For example, using adb shell, you can start the camera of the connected device:

    adb shell
    am start -a

Closing a Virtual USB connection

  1. Make sure you disconnect your device from ADB using adb disconnect <IPAddress>:<portNumber>

    adb disconnect localhost:7000
  2. If open, close your SauceLabs device view in your browser.

Unsupported ADB commands

These ADB Commands are not supported for use with Sauce Labs Virtual USB

  • adb-reverse

Connecting to the Chrome Inspector

As mentioned above, one powerful way to work with your Real Device is by viewing web pages through the full spectrum of tools allowed by the Chrome Inspector. This example will demonstrate how to export a HAR file to your local machine from a Live Testing session. HAR (Http ARchive) files are useful for inspecting the HTTP requests generated by your web pages, allowing you to inspect API calls, user analytics, third party web service calls, or any other kind of network traffic you want to capture.

Follow the above steps to initialize the Sauce Labs vUSB client, connect to your device, and initialize an adb connection. Once you verify that you are connected to the device, open a Chrome tab locally and put chrome://inspect in the address bar. This will open the Chrome Inspector:

Now, you don't actually have Chrome open on the device yet. We can issue additional adb commands to make that happen:

$ ./adb shell am start -n

$ ./adb shell am start -a android.intent.action.VIEW -d

These commands launch the Chrome app, and then navigate to the Swag Labs site. Once these have been successful, you should see a new set of options under the Remote Target heading in your chrome://inspect tab:

If you click on the inspect link, a new window will open, displaying Chrome DevTools the same as if the device were sitting on your desk, connected to a USB cable. Clicking the Network tab and reloading the page will display all HTTP requests made during the refresh:

Note the down arrows on the top right: . This allows you to export a HAR file locally. If you click it, it will prompt you with a Save dialog. Choose a location for the file.

This HAR file contains every HTTP request/response gathered during the page load, as well as all the headers, parameters, timing info, and other things. Using this information, you can dive deep into the way your web pages are put together, and you can do it on any configured device, without having to worry about power management or keeping up with the physical device.