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>"
}

 

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