Skip to content

Commit

Permalink
Update javadoc of capabilities to follow latest Appium documents (#1204)
Browse files Browse the repository at this point in the history 
* update General capabilities

* update Android capabilities

* update iOS capabilities

* fix headlines

* fix reviewed code.

* edit Android appWaitActivity docs
  • Loading branch information
@takeyaqa @SrinivasanTarget
takeyaqa authored and SrinivasanTarget committed Aug 17, 2019
1 parent 960caf4 commit 8e04783
Show file tree
Hide file tree
Showing 3 changed files with 114 additions and 42 deletions.
49 changes: 36 additions & 13 deletions src/main/java/io/appium/java_client/remote/AndroidMobileCapabilityType.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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";

Expand All @@ -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";

/**
Expand Down Expand Up @@ -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";

Expand Down Expand Up @@ -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";

Expand Down Expand Up @@ -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";
}
56 changes: 43 additions & 13 deletions src/main/java/io/appium/java_client/remote/IOSMobileCapabilityType.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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";

Expand All @@ -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";

Expand Down Expand Up @@ -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";

/**
Expand All @@ -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";

Expand All @@ -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";

Expand All @@ -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";

Expand Down
51 changes: 35 additions & 16 deletions src/main/java/io/appium/java_client/remote/MobileCapabilityType.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand All @@ -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";

Expand All @@ -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";

Expand All @@ -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";

Expand All @@ -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";

Expand All @@ -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";
}

0 comments on commit 8e04783

Please sign in to comment.