Handle Android app orientation issues

Learn about possible solutions if you are facing issues with Android app orientation on BrowserStack App Automate.

Issue

When you run tests on BrowserStack App Automate, you may encounter the following Android app orientation issues :

App remains in landscape mode irrespective of the orientation set
App randomly switches to landscape mode in-between a test

Cause

Android apps that use device sensors to determine orientation may move to landscape mode irrespective of the orientation set. This happens because BrowserStack mobile devices are kept in landscape position as a default and are programmatically set to portrait mode. Therefore, if an Android app uses device sensor data to determine orientation it may automatically switch to landscape mode.
In Android tests that use Appium commands activate_app or background_app, Appium may set the device orientation to auto-rotate and as a result, the app might switch to landscape mode in-between the tests.

Resolutions

Ensure your Android app does not use device sensor to determine app orientation. If your app determines screenOrientation using device sensor values, ensure that it is set to non-sensor value such as unspecified, user or fullUser. For more details, check Android screenOrientation documentation.

On Android version 10 and above, you can also make use of the following BrowserStack executors to make the app adhere to user-set orientation rather than orientation set by device sensor values.

JavascriptExecutor jse = (JavascriptExecutor)driver;
// enable user-set orientation on Android version >=12 devices
jse.executeScript("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation enabled\"
         }
     }"
);

// disable user-set orientation on Android version >=12 devices
jse.executeScript("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation disabled\"
         }
     }"
);

// enable user-set orientation on Android version 10,11 devices
jse.executeScript("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation enabled\"
         }
     }"
);

// disable user-set orientation on Android version 10,11 devices
jse.executeScript("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation disabled\"
         }
     }"
);

// enable user-set orientation on Android version >=12 devices
await driver.execute("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation enabled\"
         }
     }"
);

// disable user-set orientation on Android version >=12 devices
await driver.execute("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation disabled\"
         }
     }"
);

// enable user-set orientation on Android version 10,11 devices
await driver.execute("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation enabled\"
         }
     }"
);

// disable user-set orientation on Android version 10,11 devices
await driver.execute("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation disabled\"
         }
     }"
);

// enable user-set orientation on Android version >=12 devices
((IJavaScriptExecutor)driver).ExecuteScript("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation enabled\"
         }
     }"
);

// disable user-set orientation on Android version >=12 devices
((IJavaScriptExecutor)driver).ExecuteScript("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation disabled\"
         }
     }"
);

// enable user-set orientation on Android version 10,11 devices
((IJavaScriptExecutor)driver).ExecuteScript("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation enabled\"
         }
     }"
);

// disable user-set orientation on Android version 10,11 devices
((IJavaScriptExecutor)driver).ExecuteScript("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation disabled\"
         }
     }"
);

# enable user-set orientation on Android version >=12 devices
driver.execute_script("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation enabled\"
         }
     }"
);

# disable user-set orientation on Android version >=12 devices
driver.execute_script("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation disabled\"
         }
     }"
);

# enable user-set orientation on Android version 10,11 devices
driver.execute_script("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation enabled\"
         }
     }"
);

# disable user-set orientation on Android version 10,11 devices
driver.execute_script("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation disabled\"
         }
     }"
);

caps["javascriptEnabled"] = "true" #include this capability for JavaScript executors to work
# enable user-set orientation on Android version >=12 devices
driver.execute_script("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation enabled\"
         }
     }"
);

# disable user-set orientation on Android version >=12 devices
driver.execute_script("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm fixed-to-user-rotation disabled\"
         }
     }"
);

# enable user-set orientation on Android version 10,11 devices
driver.execute_script("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation enabled\"
         }
     }"
);

# disable user-set orientation on Android version 10,11 devices
driver.execute_script("browserstack_executor: {
          \"action\":\"adbShell\", 
          \"arguments\": {
            \"command\" : \"wm set-fix-to-user-rotation disabled\"
         }
     }"
);

If your Android test uses commands such as activate_app or background_app and your app is moving to landscape mode in-between the tests, explicitly set the orientation of the device again using Appium setOrientation command after these Appium commands are invoked.

Examples

// Put the app in background
driver.runAppInBackground();

//...

// Put the app in foreground.
driver.activateApp(<app_package>);

// Set the orientation of the device.
driver.rotate(ScreenOrientation.PORTRAIT);

// Put the app in background
driver.background();

//...

// Put the app in foreground.
driver.activateApp(<app_package>);

// Put the app in foreground.
driver.setOrientation('PORTRAIT');

// Put the app in background
driver.BackgroundApp()

//...

// Put the app in foreground.
driver.activateApp(<app_package>);

// Set the orientation of the device.
driver.Orientation = ScreenOrientation.Portrait;

# Put the app in background
driver.background_app()

#...

# Put the app in foreground
driver.activate_app(<package_name>)

# Set the orientation of the device.
driver.orientation = "PORTRAIT"

#Put the app in background.
@driver.background_app()

#...

#Put the app in foreground.
@driver.activate_app(<package_name>)

# Set the orientation of the device.
@driver.rotation = :portrait