Skip to content

adbEspressoAPI.rst

Latest commit

 

History

History
309 lines (210 loc) · 8.03 KB

adbEspressoAPI.rst

File metadata and controls

309 lines (210 loc) · 8.03 KB

ADB Commands API Reference

In this section

Overview

The ADB Commands API allows you to execute Android Debug Bridge (ADB) shell commands remotely from within your Espresso tests. This API provides direct access to the device's shell environment, enabling advanced testing scenarios that require system-level interactions.

.. grid:: 2 2 1 1

   .. grid-item-card:: 🚀 Key Benefits
      :class-header: bg-primary text-white

      * **Direct Device Control**: Execute shell commands on test devices
      * **Advanced Testing**: Perform system-level operations during tests
      * **Flexible Integration**: Works seamlessly with Espresso test framework
      * **Remote Execution**: Execute commands without physical device access

   .. grid-item-card:: 🔧 Common Use Cases
      :class-header: bg-success text-white

      * **File System Operations**: List, create, or modify files
      * **App State Management**: Clear app data or cache
      * **System Settings**: Modify device settings for testing
      * **Network Operations**: Configure network conditions

API Specification

.. tabs::

   .. tab:: Request Details

      **HTTP Method:** ``POST``

      **Endpoint URL:**

      .. code-block:: text

         http://<RobusTest URL>/v3/device/shell?accesskey=<user_access_key>

      **Request Headers:**

      .. code-block:: text

         Content-Type: application/json

      **Request Payload:**

      .. code-block:: json

         {
           "_id": "device_id",
           "command": "<ADB SHELL COMMAND>"
         }

   .. tab:: Response Format

      **Success Response:**

      .. code-block:: json

         {
           "status": "success",
           "output": "command execution result",
           "exitCode": 0
         }

      **Error Response:**

      .. code-block:: json

         {
           "status": "error",
           "message": "Command execution failed",
           "exitCode": 1
         }

   .. tab:: Authentication

      **Access Key:**

      Your access key is required as a query parameter in the URL. You can obtain your access key from:

      1. **User Profile**: Navigate to User Profile → Access Keys
      2. **Project Settings**: Found in Project Dashboard → Settings

      **Security Notes:**

      * Keep your access key secure
      * Never commit access keys to version control
      * Rotate keys regularly for security

Parameters Reference

API Parameters
Parameter Type Description Example Required
_id String Device ID of the target device for command execution "2132SDSFDSFDSF" Yes
command String ADB shell command to execute on the device "ls /data/local/tmp/" Yes
accesskey String User access key for authentication (URL parameter) "1234DFFGG24FDSD" Yes

Device ID Retrieval

Since the Device ID is required for the API payload, you can obtain it within your Espresso test using the following Java code:

.. tabs::

   .. tab:: Java Code

      .. code-block:: java

         Bundle testBundle = InstrumentationRegistry.getArguments();
         String deviceID = testBundle.getString("deviceID");

         // Use the deviceID in your API call
         System.out.println("Current Device ID: " + deviceID);

   .. tab:: Kotlin Code

      .. code-block:: kotlin

         val testBundle = InstrumentationRegistry.getArguments()
         val deviceID = testBundle.getString("deviceID")

         // Use the deviceID in your API call
         println("Current Device ID: $deviceID")

Sample Implementation

Here's a complete example of how to use the ADB Commands API:

.. tabs::

   .. tab:: Basic Example

      **Request:**

      .. code-block:: http

         POST /v3/device/shell?accesskey=1234DFFGG24FDSD HTTP/1.1
         Host: devicelab.robustest.com
         Content-Type: application/json

         {
           "_id": "2132SDSFDSFDSF",
           "command": "ls /data/local/tmp/"
         }

      **Response:**

      .. code-block:: json

         {
           "status": "success",
           "output": "file1.txt\nfile2.txt\ntest_data/",
           "exitCode": 0
         }

   .. tab:: Advanced Example

      **Clear App Data:**

      .. code-block:: json

         {
           "_id": "2132SDSFDSFDSF",
           "command": "pm clear com.example.app"
         }

      **Install APK:**

      .. code-block:: json

         {
           "_id": "2132SDSFDSFDSF",
           "command": "pm install /data/local/tmp/test.apk"
         }

      **Check Battery Level:**

      .. code-block:: json

         {
           "_id": "2132SDSFDSFDSF",
           "command": "dumpsys battery | grep level"
         }

   .. tab:: cURL Example

      .. code-block:: bash

         curl -X POST \
           'http://devicelab.robustest.com/v3/device/shell?accesskey=1234DFFGG24FDSD' \
           -H 'Content-Type: application/json' \
           -d '{
             "_id": "2132SDSFDSFDSF",
             "command": "ls /data/local/tmp/"
           }'

Common ADB Commands

.. grid:: 2 2 1 1

   .. grid-item-card:: 📁 File Operations
      :class-header: bg-info text-white

      * **List Directory**: ``ls /path/to/directory``
      * **Create Directory**: ``mkdir /path/to/new/directory``
      * **Copy File**: ``cp /source/file /dest/file``
      * **Remove File**: ``rm /path/to/file``
      * **Change Permissions**: ``chmod 755 /path/to/file``

   .. grid-item-card:: 🔧 System Operations
      :class-header: bg-warning text-white

      * **Clear App Data**: ``pm clear com.package.name``
      * **Install APK**: ``pm install /path/to/app.apk``
      * **Check Processes**: ``ps | grep process_name``
      * **Memory Info**: ``dumpsys meminfo``
      * **Battery Status**: ``dumpsys battery``

Best Practices

Note

Security Considerations:

  • Only execute trusted commands
  • Validate command parameters to prevent injection attacks
  • Use appropriate error handling for failed commands
  • Monitor command execution for security anomalies

Tip

Performance Tips:

  • Keep commands lightweight to avoid test timeouts
  • Use specific paths rather than wildcards when possible
  • Cache device IDs to avoid repeated retrievals
  • Implement retry logic for transient failures

Error Handling

Common error scenarios and their solutions:

Common Errors
Error Type Description Solution
Invalid Device ID Device ID not found or inactive Verify device availability and correct ID
Command Timeout Command execution exceeded timeout Use simpler commands or increase timeout
Permission Denied Insufficient permissions for command Use appropriate permissions or alternative commands
Authentication Error Invalid access key Verify access key validity and permissions 
.. seealso::

   **Related Documentation:**

   * :doc:`hubespresso` - Espresso Hub Integration
   * :doc:`switchWiFiAPI` - WiFi Network Switching API
   * :doc:`hubjobpayload` - Job Payload API Reference
   * :doc:`automationreports` - Understanding Test Reports