Skip to main content

Best Practices & Troubleshooting Guide for Mobile Local Appium Execution with TestGrid

Appium Best Practices, Mandatory Capabilities & CI/CD Execution Guide

For Stable Automation on TestGrid Device Cloud

This document outlines mandatory capabilities, timeout configurations, CI/CD pipeline strategies, retry mechanisms, and session cleanup best practices to ensure stable and scalable Appium automation on TestGrid Device Cloud.

Following these guidelines helps prevent:

  • UiAutomator2 instrumentation crashes

  • Socket hang-ups

  • Stuck or orphaned sessions

  • Session overlap in CI/CD pipelines

  • Device locking issues

  • Flaky automation executions

Common Issues Observed

1. UiAutomator2 Instrumentation Process Crashed

Usually caused by:

  • Stale Appium sessions

  • Improper session cleanup

  • Reusing the same systemPort

  • Long sequential executions

  • Low launch timeouts

2. Socket Hang-Up / Session Not Started

Occurs when:

  • Previous session not terminated

  • Port conflicts

  • Device still locked

  • CI killed job before cleanup

3. UiAutomator2 Process Stuck After Element Interaction

Occurs when:

  • Heavy UI actions without waits

  • App becomes unresponsive

  • Test continues after partial failure

  • Session remains alive after crash

4. Session Overlap in CI/CD Runs

Occurs when:

  • Same device reused across jobs

  • driver.quit() not executed

  • Parallel + sequential runs mixed

  • Back-to-back pipelines start too fast

Mandatory Capabilities (Must Be Added in User Code)

Common Capabilities (Android & iOS)

{
"appium:platformName": "<Android | iOS>", // Target platform
"appium:automationName": "<UiAutomator2 | XCUITest>", // Automation engine
"appium:udid": "<Device_UDID>", // Unique device ID
"tg:userToken": "<Your_User_Token>" // TestGrid authentication
}

 

Why Required

  • Authenticates user session

  • Binds execution to one device

  • Prevents unauthorized sessions

Android Capabilities (Mandatory + Recommended)

{
// Platform & device
"appium:platformName": "Android",
"appium:automationName": "UiAutomator2",
"appium:deviceName": "<Device_Name>",
"appium:platformVersion": "<Android_Version>",
"appium:udid": "<Device_UDID>",// PORT MANAGEMENT (MANDATORY)
"appium:systemPort": "<Unique_System_Port>",

// App behavior
"appium:autoGrantPermissions": true,
"appium:noReset": true,
"appium:fullReset": false,

// Stability timeouts
"appium:uiautomator2ServerLaunchTimeout": 90000,
"appium:newCommandTimeout": 300,

// TestGrid metadata
"tg:userToken": "<Your_User_Token>",
"tg:projectName": "<Project_Name>"
}

 

ChromeDriver Configuration for Mobile Chrome/Web Automation


Overview: For Mobile Chrome/Web automation on Android devices, TestGrid manages the required ChromeDriver setup on the device-cloud side.
The client does not need to create or configure a separate ChromeDriver setup. The required ChromeDriver binaries are maintained and configured on the TestGrid side.

Client-Side Configuration: The client only needs to add the required capability in their automation code:"chromedriverExecutableDir": "/Applications/XAMPP/xamppfiles/htdocs/device-cloud/ChromeDrivers/". This capability specifies the ChromeDriver directory used by Appium when establishing a Mobile Chrome/Web automation session.TestGrid-Side SetupThe following configuration is handled by the TestGrid team:

  • ChromeDriver binaries are maintained in the required directory.
  • The appropriate ChromeDriver version is made available based on the Chrome browser version running on the target Android device.
  • The ChromeDriver setup is configured on the TestGrid/device-cloud side.
  • The client is not required to manually install, upload, or maintain ChromeDriver binaries.


Client Responsibility: The client only needs to:

  • Use the required capability in their automation code.
  • Execute the automation through the TestGrid environment.
  • Ensure that the capability is included when running Mobile Chrome/Web automation.

ChromeDriver Compatibility: The ChromeDriver version must be compatible with the Chrome browser version installed on the target Android device. TestGrid manages the required ChromeDriver binaries on the platform side to support the automation session. 

  • Important Note: The client does not need to set up or maintain ChromeDriver separately. TestGrid handles the ChromeDriver configuration and required binaries on the platform side. The client only needs to add the specified capability to their automation code.

Note: The chromedriverExecutableDir capability is applicable when the automation setup uses a custom/local ChromeDriver directory. It is not a mandatory capability for every Appium Mobile Chrome/Web automation setup.

 

Why These Matter

Capability Purpose
systemPort Prevents socket hang-ups & crashes
uiautomator2ServerLaunchTimeout Allows slow device startup
newCommandTimeout Prevents CI idle timeout
noReset Stability for back-to-back runs
autoGrantPermissions Avoids permission popups

⚠️ Reusing systemPort = #1 Android failure cause

iOS Capabilities (Mandatory + Recommended)

{
"appium:platformName": "iOS",
"appium:automationName": "XCUITest",
"appium:deviceName": "<Device_Name>",
"appium:platformVersion": "<iOS_Version>",
"appium:udid": "<Device_UDID>",// PORT MANAGEMENT (MANDATORY)
"appium:wdaLocalPort": "<Unique_WDA_Port>",

// Stability timeouts
"appium:wdaLaunchTimeout": 900000,
"appium:wdaConnectionTimeout": 900000,
"appium:newCommandTimeout": 300,

// TestGrid
"tg:userToken": "<Your_User_Token>",
"tg:projectName": "<Project_Name>"
}

 

Mandatory Best Practices

1. Always Terminate the Appium Session

driver.quit();

If Not Called:

  • Device remains locked

  • Next session may fail

  • CI pipelines get blocked

  • Results may show timestamps only

2. Mandatory Fallback — Release Device API

If:

  • Test crashes

  • CI aborts job

  • Driver never reaches quit

  • Device remains locked

–> You MUST call the Release API

Release Device API

curl --location --globoff \
'https://your_domain.testgrid.io/api/user/releasedevice/{{device_id}}/' \
--form 'user_token="<Your_User_Token>"'

Use This API When

  • After suite completes without quit

  • CI timeout / force stop

  • Before retrying failed runs

  • Device appears busy

Benefits

  • Frees Appium session

  • Unlocks device

  • Prevents instrumentation crashes

  • Ensures clean next execution

3. CI/CD & Back-to-Back Execution Guidelines

Most customers run pipelines on:

  • Jenkins

  • GitHub Actions

  • GitLab CI

  • Azure DevOps

Golden Rules

  • One device = one session

  • Unique ports per run

  • Always cleanup after execution

  • Avoid overlapping jobs

Recommended CI Execution Flow

Pipeline Start
↓
Start Appium Session
↓
Execute Test / Suite
↓
driver.quit()
↓
(If quit fails) → Release Device API
↓
Next Pipeline Run

 

Long Suite Stability Strategy

For large test suites:

  • Split into batches

  • Restart Appium every N tests

  • Release device between batches

Prevents:

  • Memory leaks

  • UiAutomator2 freezes

  • WDA instability

Wait Strategy (Avoid Hard Sleeps)

❌ Avoid:

Thread.sleep(10000);

✅ Use:

WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));
wait.until(ExpectedConditions.visibilityOfElementLocated(locator));

 

Retry Strategy (Highly Recommended for CI)

Will Retry Mechanisms Help?

✅ Yes — but as mitigation, not a full solution.

Retries Help With:

  • Transient network drops

  • Grid load balancing delays

  • Session init failures

  • Temporary infra glitches

Retries Won’t Help With:

  • Wrong configuration

  • Persistent network failures

  • Offline devices

  • Bad timeout values

Smart Retry Implementation (Java Example)

public AndroidDriver initializeDriverWithRetry(int maxRetries) {
for (int i = 0; i < maxRetries; i++) {
try {
return new AndroidDriver(url, caps);
} catch (Exception e) {
if (i == maxRetries - 1) throw e;
System.out.println("Retry attempt: " + (i + 1));
Thread.sleep(3000);
}
}
return null;
}

 

Timeout Tuning for Stability

capabilities.setCapability("newCommandTimeout", 300); 
capabilities.setCapability("uiautomator2ServerLaunchTimeout", 90000); 
capabilities.setCapability("wdaLaunchTimeout", 900000);

 

Advanced Stability Tips

  • Use exponential backoff retries

  • Add pre-run health checks

  • Monitor device availability

  • Avoid aggressive parallelism

  • Use explicit waits everywhere

CI/CD Safety Checklist

Before every run ensure:

✅ Unique ports assigned
✅ Correct UDID used
✅ Valid tg:userToken
✅ driver.quit() implemented
✅ Release API added as fallback
✅ No overlapping sessions
✅ Retry logic enabled

Summary

Following this guide will:

  • Prevent UiAutomator2 crashes

  • Eliminate socket hang-ups

  • Avoid stuck or orphaned sessions

  • Enable stable CI/CD pipelines

  • Improve automation reliability

  • Reduce flaky executions significantly

Table of Contents