<commit_before>## Settings

Settings are a new concept introduced by appium. They are currently not a part of the Mobile JSON Wire Protocol, or the Webdriver spec.

Settings are a way to specify the behavior of the appium server.

Settings are:
 - Mutable, they can be changed during a session
 - Only relevant during the session they are applied. They are reset for each new session.
 - Control the way the appium server behaves during test automation. They do not apply to controlling the app or device under test.

An example of a setting would be `ignoreUnimportantViews` for Android. Android can be set to ignore elements in the View Hierarchy which it deems irrelevant. Setting this can cause tests to run faster. A user who *wants* to access the ignored elements however, would want to disable `ignoreUnimportantViews`, and reenable it afterwards.

Another example of a use-case for settings would be telling appium to ignore elements which are not visible.

Settings are implemented via the following API endpoints:

### [Update Device Settings](/docs/en/commands/session/settings/update-settings.md)

**POST** /session/:sessionId/appium/settings

>Expects a JSON hash of settings, where keys correspond to setting names, and values to the value of the setting.
```
{
  settings: {
   ignoreUnimportantViews : true
  }
}
```

### [Retrieve Device Settings](/docs/en/commands/session/settings/get-settings.md)

**GET** /session/:sessionId/appium/settings

>Returns a JSON hash of all the currently specified settings.
```
{
  ignoreUnimportantViews : true
}
```

## General Supported Settings

|Name|Description|Values|
|----|----|----|
|`shouldUseCompactResponses`| Returns compact (standards-compliant) & faster responses in find element/s. Defaults to `true` | `false` or `true` |
|`elementResponseAttributes`| The comma-separated list of fields to return with each element. It works only `shouldUseCompactResponses` is `false`. Defaults to "type,label" in iOS, "" in Android. | e.g., `"name,text,rect,attribute/name,attribute/value"` |

[Image Elements](https://github.com/appium/appium/blob/master/docs/en/advanced-concepts/image-elements.md) also has image elements specific settings.

### Android Only

|Name|Description|Values|
|----|----|----|
|`ignoreUnimportantViews`|Boolean which sets whether Android devices should use `setCompressedLayoutHeirarchy()` which ignores all views which are marked IMPORTANT_FOR_ACCESSIBILITY_NO or IMPORTANT_FOR_ACCESSIBILITY_AUTO (and have been deemed not important by the system), in an attempt to make things less confusing or faster. `false` by default. | `false` or `true` |

#### UiAutomator2

|Name|Description|Values|
|----|----|----|
|`allowInvisibleElements`| Boolean which set whether Android device should show all elements, visible and invisible. `false` by default. | `false` or `true` |
|`enableNotificationListener`| Boolean which sets whether the Android device should enable or disable the `NotificationListener`. `true` by default.  | `false` or `true` |
|`actionAcknowledgmentTimeout`| Int (milliseconds) which is the same as [setActionAcknowledgmentTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setActionAcknowledgmentTimeout(long)). If a negative value is given, it would set to default(3 * 1000 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g., `5000` |
|`keyInjectionDelay`| Int (milliseconds) which is the same as [setKeyInjectionDelay](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setKeyInjectionDelay(long)). If a negative value is given, it would set to default(0 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g., `5000` |
|`scrollAcknowledgmentTimeout`| Int (milliseconds) which is the same as [setScrollAcknowledgmentTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setScrollAcknowledgmentTimeout(long)). If a negative value is given, it would set to default(200 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g., `300` |
|`waitForIdleTimeout`| Int (milliseconds) which is the same as [setWaitForIdleTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setWaitForIdleTimeout(long)). If a negative value is given, it would set to default(10 * 1000 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g., `10000` |
|`waitForSelectorTimeout`| Int (milliseconds) which is the same as [setWaitForSelectorTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setWaitForSelectorTimeout(long)). If a negative value is given, it would set to default(10 * 1000 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g., `10000` |
|`normalizeTagNames`| Translate all class names used as XML tags to the limited set of ASCII characters supported by Apache Harmony library. Used by default in Android to avoid possible XML parsing exceptions caused by XPath lookup. The translation is based on [junidecode](https://github.com/gcardone/junidecode). This prevents [this error case](https://github.com/appium/appium/issues/11854). Defaults to `false`. | `false` or `true` |
|`shutdownOnPowerDisconnect`| Shutdown the server through the broadcast receiver on [ACTION_POWER_DISCONNECTED](https://developer.android.com/reference/android/content/Intent.html#ACTION_POWER_DISCONNECTED). Defaults to `true` | `false` or `true` |
|`trackScrollEvents`| Turn on or off the tracking of scroll events as they happen. If `true`, a field, `lastScrollData`, is added to the results of `getSession`, which can then be used to check on scroll progress. Turning this feature off significantly increases touch action performance. Defaults to `true` | `true` or `false` |
|`wakeLockTimeout`| Allows to change the timeout of the acquired wake lock. The lock is acquired on server startup and is held until the UIAutomator2 server is killed or the timeout expires. Setting this value to zero or a negative number will release the lock immediately if it is held. Defaults to '24 * 60 * 60 * 1000' milliseconds. | e.g. `0`, `60000` (1 min) |
|`enableMultiWindows`| If enabled then the page source and xpath lookup will include all windows available to the accessibility rather than the active one only. It might help to resolve finding elements on windows like `android.widget.PopupWindow`. Defaults to `false` and returns an active root window. Read [appium-uiautomator2-server#301](https://github.com/appium/appium-uiautomator2-server/pull/301) for mroe details. |`true` or `false` |


### iOS Only

#### XCUITest

|Name|Description|Values|Appium versions|
|----|----|----|----|<commit_msg>docs: Document settings related to UIAutomator2 mjpeg [screen] streaming feature + cleanup (#14203)<commit_after>## Settings

Settings are a new concept introduced by appium. They are currently not a part of the Mobile JSON Wire Protocol, or the Webdriver spec.

Settings are a way to specify the behavior of the appium server.

Settings are:
 - Mutable, they can be changed during a session
 - Only relevant during the session they are applied. They are reset for each new session.
 - Control the way the appium server behaves during test automation. They do not apply to controlling the app or device under test.

An example of a setting would be `ignoreUnimportantViews` for Android. Android can be set to ignore elements in the View Hierarchy which it deems irrelevant. Setting this can cause tests to run faster. A user who *wants* to access the ignored elements however, would want to disable `ignoreUnimportantViews`, and reenable it afterwards.

Another example of a use-case for settings would be telling appium to ignore elements which are not visible.

Settings are implemented via the following API endpoints:

### [Update Device Settings](/docs/en/commands/session/settings/update-settings.md)

**POST** /session/:sessionId/appium/settings

>Expects a JSON hash of settings, where keys correspond to setting names, and values to the value of the setting.
```
{
  settings: {
   ignoreUnimportantViews : true
  }
}
```

### [Retrieve Device Settings](/docs/en/commands/session/settings/get-settings.md)

**GET** /session/:sessionId/appium/settings

>Returns a JSON hash of all the currently specified settings.
```
{
  ignoreUnimportantViews : true
}
```

## General Supported Settings

|Name|Description|Values|
|----|----|----|
|`shouldUseCompactResponses`| Returns compact (standards-compliant) & faster responses in find element/s. Defaults to `true` | `false` or `true` |
|`elementResponseAttributes`| The comma-separated list of fields to return with each element. It works only `shouldUseCompactResponses` is `false`. Defaults to "type,label" in iOS, "" in Android. | e.g., `"name,text,rect,attribute/name,attribute/value"` |

[Image Elements](https://github.com/appium/appium/blob/master/docs/en/advanced-concepts/image-elements.md) also has image elements specific settings.

### Android Only

|Name|Description|Values|
|----|----|----|
| `ignoreUnimportantViews` | Controls whether the Android device should use `setCompressedLayoutHeirarchy()` which ignores all views which are marked IMPORTANT_FOR_ACCESSIBILITY_NO or IMPORTANT_FOR_ACCESSIBILITY_AUTO (and have been deemed not important by the system), in an attempt to make things less confusing or faster. Defaults to `false`. | `false` or `true` |

#### UiAutomator2

|Name|Description|Values|
|----|----|----|
| `actionAcknowledgmentTimeout` | Same as: [setActionAcknowledgmentTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setActionAcknowledgmentTimeout(long)). If a negative value is given, it would set to default (3 * 1000 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g., `5000` |
| `allowInvisibleElements` |  Controls whether the Android device should show all elements, visible and invisible. Defaults to `false`. | `false` or `true` |
| `enableMultiWindows` |  If enabled then the page source and xpath lookup will include all windows available to the accessibility rather than the active one only. It might help to resolve finding elements on windows like `android.widget.PopupWindow`. Defaults to `false` and returns an active root window. Read [appium-uiautomator2-server#301](https://github.com/appium/appium-uiautomator2-server/pull/301) for more details. | `true` or `false` |
| `enableNotificationListener` |  Controls whether the Android device should enable or disable the `NotificationListener`. Defaults to `true`.  | `false` or `true` |
| `keyInjectionDelay` | Same as: [setKeyInjectionDelay](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setKeyInjectionDelay(long)). If a negative value is given, it would set to default (0 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g., `5000` |
| `mjpegBilinearFiltering` | Controls whether or not to apply bilinear filtering to source screenshot resize algorithm. Enabling this flag may improve the quality of the resulting scaled bitmap, but will introduce a [small] performance hit. Defaults to `false`. | `false` or `true` |
| `mjpegScalingFactor` | Controls the scaling factor of streamed screenshots. 100 means no scaling is applied (e.g. 100% of the original size). The bigger image size is the more CPU performance is needed to encode it. Integer values between `1` and `100` are available. Defaults to `50`. | `1` to `100` |
| `mjpegServerFramerate` | Controls the framerate of streamed screenshots. Greater framerate values create greater CPU load. That actual maximum framerate value is limited by the performance of the device under test. Integer values between `1` and `60` are available. Defaults to `10`. | `1` to `60` |
| `mjpegServerPort` | Controls the MJPEG server port. Integer values between `1024` and `65535` are available. Defaults to `7810`. | `1024` to `65535` |
| `mjpegServerScreenshotQuality` | Controls the quality of streamed screenshots. Where the best quality is 100 and the worst is 1. The greater the value is the more CPU time is needed to encode a single bitmap into JPEG format. Usually a value between 25 and 90 is fine for this setting. Greater values affect performance too much without visible quality improvements and lower ones introduce visible distortions into the resulting image. Integer values between `1` and `100` are available. Defaults to `50`. | `1` to `100` |
| `normalizeTagNames` | Translate all class names used as XML tags to the limited set of ASCII characters supported by Apache Harmony library. Used by default in Android to avoid possible XML parsing exceptions caused by XPath lookup. The translation is based on [junidecode](https://github.com/gcardone/junidecode). This prevents [this error case](https://github.com/appium/appium/issues/11854). Defaults to `false`. | `false` or `true` |
| `scrollAcknowledgmentTimeout` | Same as: [setScrollAcknowledgmentTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setScrollAcknowledgmentTimeout(long)). If a negative value is given, it would set to default (200 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g. `300` |
| `serverPort` | Controls the server port. Integer values between `1024` and `65535` are available. Defaults to `6790`. | `1024` to `65535` |
| `shutdownOnPowerDisconnect` | Shutdown the server through the broadcast receiver on [ACTION_POWER_DISCONNECTED](https://developer.android.com/reference/android/content/Intent.html#ACTION_POWER_DISCONNECTED). Defaults to `true`. | `false` or `true` |
| `trackScrollEvents` | Controls the tracking of scroll events as they happen. If `true`, a field, `lastScrollData`, is added to the results of `getSession`, which can then be used to check on scroll progress. Turning this feature off significantly increases touch action performance. Defaults to `true`. | `false` or `true` |
| `waitForIdleTimeout` | Same as: [setWaitForIdleTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setWaitForIdleTimeout(long)). If a negative value is given, it would set to default (10 * 1000 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g. `10000` |
| `waitForSelectorTimeout` | Same as: [setWaitForSelectorTimeout](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html#setWaitForSelectorTimeout(long)). If a negative value is given, it would set to default (10 * 1000 milliseconds). Handled by [UiAutomator Configurator](https://developer.android.com/reference/android/support/test/uiautomator/Configurator.html) in Android API 18 and above. | e.g. `10000` |
| `wakeLockTimeout` | Controls the timeout of the acquired wake lock. The lock is acquired on server startup and is held until the UIAutomator2 server is killed or the timeout expires. Setting this value to zero or a negative number will release the lock immediately if it is held. Defaults to '24 * 60 * 60 * 1000' milliseconds. | e.g. `0`, `60000` (1 min) |

### iOS Only

#### XCUITest

|Name|Description|Values|Appium versions|
|----|----|----|----|
{'fraction_non_alphanumeric': 0.10100699987719514, 'fraction_numerical': 0.015964632199435096, 'mean_word_length': 5.1367746797287115, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 7, 'https://': 30, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 1, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '350612', 'n_tokens_mistral': 4706, 'n_tokens_neox': 4385, 'n_words': 1745}