Update javadoc of capabilities to follow latest Appium documents (appium#1204)

* update General capabilities * update Android capabilities * update iOS capabilities * fix headlines * fix reviewed code. * edit Android appWaitActivity docs

Author: Takeshi Kishi

src/main/java/io/appium/java_client/remote/AndroidMobileCapabilityType.java

@@ -19,29 +19,39 @@
 import org.openqa.selenium.remote.CapabilityType;
 
 /**
- * The list of Android-specific capabilities.
- * Read:
- * https://github.com/appium/appium/blob/1.5/docs/en/writing-running-appium/caps.md#android-only
+ * The list of Android-specific capabilities. <br>
+ * Read: <br>
+ * <a href="https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md#android-only">
+ * https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md#android-only</a>
  */
 public interface AndroidMobileCapabilityType extends CapabilityType {
+
  /**
  * Activity name for the Android activity you want to launch from your package.
- * This often needs to be preceded by a . (e.g., .MainActivity instead of MainActivity).
+ * This often needs to be preceded by a {@code .} (e.g., {@code .MainActivity}
+ * instead of {@code MainActivity}). By default this capability is received from the package
+ * manifest (action: android.intent.action.MAIN , category: android.intent.category.LAUNCHER)
  */
  String APP_ACTIVITY = "appActivity";
 
  /**
- * Java package of the Android app you want to run.
+ * Java package of the Android app you want to run. By default this capability is received
+ * from the package manifest ({@literal @}package attribute value)
  */
  String APP_PACKAGE = "appPackage";
 
  /**
- * Activity name for the Android activity you want to wait for.
+ * Activity name/names, comma separated, for the Android activity you want to wait for.
+ * By default the value of this capability is the same as for {@code appActivity}.
+ * You must set it to the very first focused application activity name in case it is different
+ * from the one which is set as {@code appActivity} if your capability has {@code appActivity}
+ * and {@code appPackage}. You can also use wildcards ({@code *}).
  */
  String APP_WAIT_ACTIVITY = "appWaitActivity";
 
  /**
  * Java package of the Android app you want to wait for.
+ * By default the value of this capability is the same as for {@code appActivity}
  */
  String APP_WAIT_PACKAGE = "appWaitPackage";
 
@@ -63,7 +73,10 @@ public interface AndroidMobileCapabilityType extends CapabilityType {
 
  /**
  * (Chrome and webview only) Enable Chromedriver's performance logging (default false).
+ *
+ * @deprecated move to {@link MobileCapabilityType#ENABLE_PERFORMANCE_LOGGING}
  */
+ @Deprecated
  String ENABLE_PERFORMANCE_LOGGING = "enablePerformanceLogging";
 
  /**
@@ -164,8 +177,9 @@ public interface AndroidMobileCapabilityType extends CapabilityType {
  String INTENT_FLAGS = "intentFlags";
 
  /**
- * Additional intent arguments that will be used to start activity. See Intent arguments:
- * http://developer.android.com/reference/android/content/Intent.html
+ * Additional intent arguments that will be used to start activity. See
+ * <a href="https://developer.android.com/reference/android/content/Intent.html">
+ * Intent arguments</a>.
  */
  String OPTIONAL_INTENT_ARGUMENTS = "optionalIntentArguments";
 
@@ -214,8 +228,9 @@ public interface AndroidMobileCapabilityType extends CapabilityType {
 
  /**
  * Allows passing chromeOptions capability for ChromeDriver.
- * For more information see chromeOptions:
- * https://sites.google.com/a/chromium.org/chromedriver/capabilities
+ * For more information see
+ * <a href="https://sites.google.com/a/chromium.org/chromedriver/capabilities">
+ * chromeOptions</a>.
  */
  String CHROME_OPTIONS = "chromeOptions";
 
@@ -244,13 +259,21 @@ public interface AndroidMobileCapabilityType extends CapabilityType {
  String AUTO_GRANT_PERMISSIONS = "autoGrantPermissions";
 
  /**
- * Add androidNaturalOrientation capability to allow for correct handling of
- * orientation on landscape-oriented devices.
+ * Allow for correct handling of orientation on landscape-oriented devices.
+ * Set to {@code true} to basically flip the meaning of {@code PORTRAIT} and {@code LANDSCAPE}.
+ * Defaults to {@code false}.
  */
  String ANDROID_NATURAL_ORIENTATION = "androidNaturalOrientation";
 
  /**
- * The port number, which being used by UIAutomator2.
+ * {@code systemPort} used to connect to <a href="https://github.com/appium/appium-uiautomator2-server">
+ * appium-uiautomator2-server</a> or
+ * <a href="https://github.com/appium/appium-espresso-driver">appium-espresso-driver</a>.
+ * The default is {@code 8200} in general and selects one port from {@code 8200} to {@code 8299}
+ * for appium-uiautomator2-server, it is {@code 8300} from {@code 8300} to {@code 8399} for
+ * appium-espresso-driver. When you run tests in parallel, you must adjust the port to avoid conflicts. Read
+ * <a href="https://github.com/appium/appium/blob/master/docs/en/advanced-concepts/parallel-tests.md#parallel-android-tests">
+ * Parallel Testing Setup Guide</a> for more details.
  */
  String SYSTEM_PORT = "systemPort";
 }

src/main/java/io/appium/java_client/remote/IOSMobileCapabilityType.java

@@ -19,9 +19,14 @@
 import org.openqa.selenium.remote.CapabilityType;
 
 /**
- * The list of iOS-specific capabilities.
- * Read:
- * https://github.com/appium/appium/blob/1.5/docs/en/writing-running-appium/caps.md#ios-only
+ * The list of iOS-specific capabilities. <br>
+ * Read: <br>
+ * <a href="https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md#ios-only">
+ * https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md#ios-only</a>
+ * <br>
+ * and<br>
+ * <a href="https://github.com/appium/appium-xcuitest-driver#desired-capabilities">
+ * https://github.com/appium/appium-xcuitest-driver#desired-capabilities</a>
  */
 public interface IOSMobileCapabilityType extends CapabilityType {
 
@@ -78,7 +83,7 @@ public interface IOSMobileCapabilityType extends CapabilityType {
  String NATIVE_INSTRUMENTS_LIB = "nativeInstrumentsLib";
 
  /**
- * (Sim-only) Enable "real", non-javascript-based web taps in Safari.
+ * Enable "real", non-javascript-based web taps in Safari.
  * Default: false.
  * Warning: depending on viewport size/ratio this might not accurately tap an element.
  */
@@ -164,7 +169,7 @@ public interface IOSMobileCapabilityType extends CapabilityType {
  String APP_NAME = "appName";
 
  /**
- * Capability to pre-authorize a specific SSL cert in the iOS trust store.
+ * (Sim only) Add an SSL certificate to IOS Simulator.
  */
  String CUSTOM_SSL_CERT = "customSSLCert";
 
@@ -175,8 +180,11 @@ public interface IOSMobileCapabilityType extends CapabilityType {
  String TAP_WITH_SHORT_PRESS_DURATION = "tapWithShortPressDuration";
 
  /**
- * The capability to direct Appium to set the simulator scale.
- * The XCUITest specific capability.
+ * Simulator scale factor.
+ * This is useful to have if the default resolution of simulated device is
+ * greater than the actual display resolution. So you can scale the simulator
+ * to see the whole device screen without scrolling.
+ * This capability only works below Xcode9.
  */
  String SCALE_FACTOR = "scaleFactor";
 
@@ -229,7 +237,10 @@ public interface IOSMobileCapabilityType extends CapabilityType {
  * creating tons of unnecessary screenshots and logs,
  * which are impossible to shutdown using programming
  * interfaces provided by Apple
+ *
+ * @deprecated This capability was deleted at Appium 1.14.0
  */
+ @Deprecated
  String PREVENT_WDAATTACHMENTS = "preventWDAAttachments";
 
  /**
@@ -248,18 +259,28 @@ public interface IOSMobileCapabilityType extends CapabilityType {
  String KEYCHAIN_PATH = "keychainPath";
 
  /**
- * Forces uninstall of any existing WebDriverAgent app on device.
- * This can provide stability in some situations. Defaults to false.
+ * If {@code true}, forces uninstall of any existing WebDriverAgent app on device.
+ * Set it to {@code true} if you want to apply different startup options for WebDriverAgent for each session.
+ * Although, it is only guaranteed to work stable on Simulator. Real devices require WebDriverAgent
+ * client to run for as long as possible without reinstall/restart to avoid issues like
+ * <a href="https://github.com/facebook/WebDriverAgent/issues/507">
+ * https://github.com/facebook/WebDriverAgent/issues/507</a>.
+ * The {@code false} value (the default behaviour since driver version 2.35.0) will try to detect currently
+ * running WDA listener executed by previous testing session(s) and reuse it if possible, which is
+ * highly recommended for real device testing and to speed up suites of multiple tests in general.
+ * A new WDA session will be triggered at the default URL (http://localhost:8100) if WDA is not
+ * listening and {@code webDriverAgentUrl} capability is not set. The negative/unset value of {@code useNewWDA}
+ * capability has no effect prior to xcuitest driver version 2.35.0.
  */
  String USE_NEW_WDA = "useNewWDA";
 
  /**
- * Time, in ms, to wait for WebDriverAgewnt to be pingable. Defaults to 60000ms.
+ * Time, in ms, to wait for WebDriverAgent to be pingable. Defaults to 60000ms.
  */
  String WDA_LAUNCH_TIMEOUT = "wdaLaunchTimeout";
 
  /**
- * Timeout, in ms, for waiting for a resonse from WebDriverAgent. Defaults to 240000ms.
+ * Timeout, in ms, for waiting for a response from WebDriverAgent. Defaults to 240000ms.
  */
  String WDA_CONNECTION_TIMEOUT = "wdaConnectionTimeout";
 
@@ -273,7 +294,7 @@ public interface IOSMobileCapabilityType extends CapabilityType {
  /**
  * String representing a signing certificate.
  * Must be used in conjunction with xcodeOrgId.
- * This is usually just iPhone Developer.
+ * This is usually just iPhone Developer, so the default (if not included) is iPhone Developer
  */
  String XCODE_SIGNING_ID = "xcodeSigningId";
 
@@ -288,13 +309,22 @@ public interface IOSMobileCapabilityType extends CapabilityType {
  * Whether to perform reset on test session finish (false) or not (true).
  * Keeping this variable set to true and Simulator running
  * (the default behaviour since version 1.6.4) may significantly shorten the
- * duratiuon of test session initialization.
+ * duration of test session initialization.
  * Defaults to true.
  */
  String RESET_ON_SESSION_START_ONLY = "resetOnSessionStartOnly";
 
  /**
  * Custom timeout(s) in milliseconds for WDA backend commands execution.
+ * This might be useful if WDA backend freezes unexpectedly or requires
+ * too much time to fail and blocks automated test execution.
+ * The value is expected to be of type string and can either contain
+ * max milliseconds to wait for each WDA command to be executed before
+ * terminating the session forcefully or a valid JSON string,
+ * where keys are internal Appium command names (you can find these in logs,
+ * look for "Executing command 'command_name'" records) and values are
+ * timeouts in milliseconds. You can also set the 'default' key to assign
+ * the timeout for all other commands not explicitly enumerated as JSON keys.
  */
  String COMMAND_TIMEOUTS = "commandTimeouts";
 

src/main/java/io/appium/java_client/remote/MobileCapabilityType.java

@@ -19,10 +19,10 @@
 import org.openqa.selenium.remote.CapabilityType;
 
 /**
- * The list of common capabilities.
- * Read:
- * https://github.com/appium/appium/blob/1.5/docs/en/
- * writing-running-appium/caps.md#appium-server-capabilities
+ * The list of common capabilities. <br>
+ * Read: <br>
+ * <a href="https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md#general-capabilities">
+ * https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/caps.md#general-capabilities</a>
  */
 public interface MobileCapabilityType extends CapabilityType {
 
@@ -48,11 +48,15 @@ public interface MobileCapabilityType extends CapabilityType {
  String NEW_COMMAND_TIMEOUT = "newCommandTimeout";
 
  /**
- * The absolute local path or remote http URL to an .ipa or .apk file,
- * or a .zip containing one of these. Appium will attempt to install this app
- * binary on the appropriate device first. Note that this capability is not required for
- * Android if you specify appPackage and appActivity capabilities (see below).
- * Incompatible with browserName.
+ * The absolute local path or remote http URL to a {@code .ipa} file (IOS),
+ * {@code .app} folder (IOS Simulator), {@code .apk} file (Android) or {@code .apks} file (Android App Bundle),
+ * or a {@code .zip} file containing one of these (for .app, the .app folder must be the root of the zip file).
+ * Appium will attempt to install this app binary on the appropriate device first.
+ * Note that this capability is not required for Android if you specify {@code appPackage}
+ * and {@code appActivity} capabilities (see below). Incompatible with {@code browserName}. See
+ * <a href="https://github.com/appium/appium/blob/v1.13.0/docs/en/writing-running-appium/android/android-appbundle.md">
+ * here</a>
+ * about {@code .apks} file.
  */
  String APP = "app";
 
@@ -67,12 +71,13 @@ public interface MobileCapabilityType extends CapabilityType {
  String APPIUM_VERSION = "appiumVersion";
 
  /**
- * (Sim/Emu-only) Language to set for the simulator / emulator.
+ * Language to set for iOS (XCUITest driver only) and Android.
  */
  String LANGUAGE = "language";
 
  /**
- * (Sim/Emu-only) Locale to set for the simulator / emulator.
+ * Locale to set for iOS (XCUITest driver only) and Android.
+ * {@code fr_CA} format for iOS. {@code CA} format (country name abbreviation) for Android
  */
  String LOCALE = "locale";
 
@@ -87,14 +92,18 @@ public interface MobileCapabilityType extends CapabilityType {
  String AUTO_WEBVIEW = "autoWebview";
 
  /**
- * Don't reset app state before this session. Default false.
+ * Don't reset app state before this session. See
+ * <a href="https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/other/reset-strategies.md">
+ * here</a>
+ * for more detail.
  */
  String NO_RESET = "noReset";
 
  /**
- * (iOS) Delete the entire simulator folder.
- * (Android) Reset app state by uninstalling app instead of clearing app data.
- * On Android, this will also remove the app after the session is complete. Default false.
+ * Perform a complete reset. See
+ * <a href="https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/other/reset-strategies.md">
+ * here</a>
+ * for more detail.
  */
  String FULL_RESET = "fullReset";
 
@@ -106,7 +115,11 @@ public interface MobileCapabilityType extends CapabilityType {
 
  /**
  * Enable or disable the reporting of the timings for various Appium-internal events
- * (e.g., the start and end of each command, etc.). Defaults to false.
+ * (e.g., the start and end of each command, etc.). Defaults to {@code false}.
+ * To enable, use {@code true}. The timings are then reported as {@code events} property on response
+ * to querying the current session. See the
+ * <a href="https://github.com/appium/appium/blob/master/docs/en/advanced-concepts/event-timings.md">
+ * event timing docs</a> for the the structure of this response.
  */
  String EVENT_TIMINGS = "eventTimings";
 
@@ -115,4 +128,10 @@ public interface MobileCapabilityType extends CapabilityType {
  * If {@code false} then it is switched to W3C mode.
  */
  String FORCE_MJSONWP = "forceMjsonwp";
+
+ /**
+ * (Web and webview only) Enable ChromeDriver's (on Android)
+ * or Safari's (on iOS) performance logging (default {@code false}).
+ */
+ String ENABLE_PERFORMANCE_LOGGING = "enablePerformanceLogging";
 }