Unit 2: Appium Project - Subjective Questions

Desired Capabilities are key-value pairs sent by an Appium client to the Appium server when requesting a new automation session. They describe the device, platform, automation engine, application, and other conditions required for the test.

Main roles:

• Select the target platform, such as Android or iOS.
• Select the automation driver, such as UiAutomator2 or XCUITest.
• Identify a real device, emulator, or simulator.
• Specify the application to install or launch.
• Control session behavior, timeouts, permissions, and application state.

Examples:

• platformName: identifies the platform, for example Android.
• appium:automationName: selects an automation engine such as UiAutomator2.
• appium:deviceName: provides a device name.
• appium:app: specifies the path or URL of an application file.
• appium:appPackage and appium:appActivity: identify an installed Android application.

When the client calls the new-session endpoint, Appium validates these capabilities, selects the appropriate driver, prepares the target device, and returns a session identifier. Subsequent commands are associated with this session until quit() is called.

During session creation, the Appium client sends a W3C WebDriver new-session request containing capabilities.

• alwaysMatch: Contains requirements that must apply to every possible capability combination.
• firstMatch: Contains one or more alternative capability sets. The server combines alwaysMatch with each firstMatch entry and selects the first valid combination it can support.

A simplified request is:

{
  "capabilities": {
    "alwaysMatch": {
      "platformName": "Android",
      "appium:automationName": "UiAutomator2"
    },
    "firstMatch": [
      { "appium:deviceName": "Pixel_6_API_33" }
    ]
  }
}

Appium then performs the following steps:

1. Validates standard and extension capability names.
2. Determines the platform and installed Appium driver.
3. Locates or starts the requested device.
4. Installs or launches the specified application when required.
5. Creates a session and returns a unique session ID.

If a capability is invalid, unsupported, or contradictory, session creation normally fails with an explanatory server error.

A vendor prefix is a namespace added to a non-standard WebDriver capability. The W3C WebDriver specification requires extension capabilities to contain a colon so that browser or automation vendors can add features without conflicting with standard capability names.

Appium uses the prefix appium: for capabilities defined by Appium. Examples include:

• appium:automationName
• appium:deviceName
• appium:appPackage
• appium:appActivity
• appium:noReset

Standard W3C capabilities, such as platformName, do not require this prefix.

The prefix is important because it:

• Distinguishes Appium extensions from W3C standard capabilities.
• Prevents naming conflicts with capabilities introduced by other vendors.
• Allows strict W3C-compliant servers to validate requests correctly.
• Makes the owner and purpose of an extension clear.

Appium client Options classes usually add or serialize the prefix automatically, so Java code can often call methods such as setDeviceName() without manually constructing appium:deviceName.

Standard W3C capabilities are defined by the WebDriver specification and can be understood by conforming WebDriver implementations. Examples include platformName, browserName, and acceptInsecureCerts.

Appium extension capabilities provide mobile-specific behavior not defined by W3C WebDriver. Examples include appium:automationName, appium:udid, appium:appPackage, and appium:avd.

Key differences:

• Standard capabilities do not need a vendor prefix.
• Appium-specific capabilities require the appium: namespace in raw W3C requests.
• Standard capabilities describe general WebDriver behavior, while Appium capabilities configure devices, applications, and mobile automation drivers.

If the prefix is omitted from a raw request, a strict server may:

• Reject the capability as an illegal non-standard capability.
• Ignore it, resulting in unintended default behavior.
• Fail to select the expected automation driver or device.
• Produce a session-creation error such as an unrecognized capability message.

Using a current Appium Java client and an appropriate Options class reduces these errors because the client serializes mobile-specific options into the correct W3C format.

A Java Appium project can be created with Maven as follows:

1. Install prerequisites:

   • Install a supported JDK.
   • Install Maven and verify it with mvn -version.
   • Install Node.js, Appium, and the required Appium platform driver.
   • Configure the Android SDK for Android testing.

2. Create the Maven project:

   • Use an IDE's Maven project wizard, or run a Maven archetype command.
   • Choose suitable values for groupId, artifactId, and package name.

3. Use Maven's standard directory structure:

   • src/main/java for reusable framework code.
   • src/test/java for test classes.
   • src/test/resources for configuration files and test data.

4. Configure pom.xml:

   • Add the Appium Java client dependency.
   • Add JUnit or TestNG.
   • Configure the compiler and test execution plugin if required.

5. Create the driver setup class:

   • Construct an Options object.
   • Pass it and the Appium server URL to AndroidDriver or IOSDriver.

6. Compile and run:

   • Start the Appium server.
   • Ensure a device is connected or configure an emulator.
   • Execute mvn test and examine both Maven and Appium logs.

A Maven configuration should define Java compatibility, the Appium client, a test framework, and a test execution plugin. An illustrative configuration is:

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example.mobile</groupId>
  <artifactId>appium-tests</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>17</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <appium.version>9.2.3</appium.version>
    <junit.version>5.10.2</junit.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>io.appium</groupId>
      <artifactId>java-client</artifactId>
      <version>${appium.version}</version>
    </dependency>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-surefire-plugin</artifactId>
        <version>3.2.5</version>
      </plugin>
    </plugins>
  </build>
</project>

Explanation:

• Project coordinates uniquely identify the Maven artifact.
• Properties centralize dependency versions and Java settings.
• java-client supplies Appium drivers, Options classes, and mobile commands.
• JUnit supplies annotations and assertions.
• The test scope prevents test libraries from becoming production dependencies.
• Surefire discovers and executes unit or automation test classes during mvn test.

Versions should be selected for mutual compatibility rather than copied without checking the current release documentation.

A basic program using UiAutomator2Options is:

import io.appium.java_client.android.AndroidDriver;
import io.appium.java_client.android.options.UiAutomator2Options;
import java.net.URL;

public class StartSession {
    public static void main(String[] args) throws Exception {
        AndroidDriver driver = null;

        try {
            UiAutomator2Options options = new UiAutomator2Options()
                    .setPlatformName("Android")
                    .setDeviceName("Android Emulator")
                    .setAppPackage("com.example.myapp")
                    .setAppActivity("com.example.myapp.MainActivity");

            URL serverUrl = new URL("http://127.0.0.1:4723");
            driver = new AndroidDriver(serverUrl, options);

            System.out.println("Session: " + driver.getSessionId());
        } finally {
            if (driver != null) {
                driver.quit();
            }
        }
    }
}

Requirements:

• The Appium server must be running at the specified URL.
• The UiAutomator2 driver must be installed on the Appium server.
• The target device must be available through ADB.
• The package and activity must exist on the device.

new AndroidDriver(...) sends the new-session request. quit() terminates the session and releases server and device resources. In modern Appium installations, the default base path is commonly /; /wd/hub should be used only when the server has been configured for that path.

Creating an AndroidDriver triggers a sequence of client-server operations:

1. Option serialization: The Java client converts the Options object into W3C capabilities.
2. HTTP request: The client sends a new-session request to the Appium server URL.
3. Capability validation: Appium checks the capability names, values, and vendor prefixes.
4. Driver selection: Appium uses values such as platformName and appium:automationName to select an installed driver, typically UiAutomator2 for Android.
5. Device selection: Appium uses udid, deviceName, or emulator-related options to select or start a device.
6. Device preparation: The selected driver may install helper packages, configure ports, grant permissions, or install the application.
7. Application launch: Appium launches the app specified by app, or by appPackage and appActivity.
8. Session response: The server returns a session ID and the negotiated capabilities.
9. Command execution: Find-element, click, typing, and other commands include the session ID.
10. Termination: driver.quit() sends a delete-session request and allows Appium to clean up resources.

Failures at any stage should be investigated using the Java exception, Appium server log, ADB output, and the effective capabilities shown in the session log.

An Appium Options class is a typed Java object used to configure a driver session. Platform-driver-specific classes include UiAutomator2Options for Android and XCUITestOptions for iOS.

Advantages of Options classes:

• Type safety: Methods accept expected Java types, reducing invalid values.
• Discoverability: IDE auto-completion displays available configuration methods.
• Correct serialization: Appium-specific settings are represented with the required appium: vendor prefix.
• Driver specificity: The methods correspond to features supported by a particular platform driver.
• Readability: Calls such as setAppPackage() are clearer than manually maintaining string keys.
• Maintainability: Compiler feedback can reveal API changes more easily than untyped maps.

For example:

UiAutomator2Options options = new UiAutomator2Options()
        .setDeviceName("Pixel_6_API_33")
        .setAppPackage("com.example.shop")
        .setAppActivity(".MainActivity")
        .setNoReset(true);

Options classes do not eliminate server-side validation. The configured values must still be supported by the installed Appium driver and must match the target device and application.

An APK-based configuration can be written as follows:

import io.appium.java_client.android.options.UiAutomator2Options;
import java.time.Duration;

UiAutomator2Options options = new UiAutomator2Options()
        .setPlatformName("Android")
        .setAutomationName("UiAutomator2")
        .setDeviceName("Pixel_6_API_33")
        .setApp("/absolute/path/apps/shop-debug.apk")
        .setNoReset(false)
        .setNewCommandTimeout(Duration.ofSeconds(120));

Purpose of the options:

• setPlatformName("Android"): requests the Android platform.
• setAutomationName("UiAutomator2"): selects the UiAutomator2 Appium driver.
• setDeviceName(...): supplies a device description; a udid is normally more reliable when several devices are connected.
• setApp(...): identifies the APK that Appium should install and launch.
• setNoReset(false): permits normal reset or installation behavior instead of always preserving the previous app state.
• setNewCommandTimeout(...): specifies how long Appium may wait between commands before ending an inactive session.

An absolute path or accessible URL should be used for the APK. If the emulator must also be started automatically, setAvd(...) and suitable AVD timeout options can be added.

DesiredCapabilities is a general-purpose Selenium capability container, whereas UiAutomator2Options is designed specifically for Appium's Android UiAutomator2 driver.

DesiredCapabilities:

• Stores capability names and values in a relatively generic form.
• Often requires the developer to remember exact string keys.
• Makes typographical errors easier.
• May require explicit handling of W3C vendor-prefixed names.
• Is common in older Appium examples and legacy frameworks.

UiAutomator2Options:

• Provides typed methods such as setAppPackage() and setAppActivity().
• Improves IDE auto-completion and readability.
• Serializes Appium extension capabilities correctly.
• Represents options supported by the UiAutomator2 driver.
• Is generally preferred in current Java projects.

For example, a manual capability might be written conceptually as appium:appPackage = com.example, while an Options object uses setAppPackage("com.example"). Both ultimately produce capabilities for the new-session request, but the Options approach is less error-prone and easier to maintain.

appPackage is the Android application identifier of the target app, such as com.example.shopping. It distinguishes the application from other installed packages.

appActivity is the Android activity that Appium should launch, such as com.example.shopping.MainActivity or the relative form .MainActivity.

Both are often needed because:

• The package identifies the application process and installation.
• The activity identifies the specific user-interface entry point to start.
• An application may contain many activities, but not all are launchable or exported.
• Appium must construct an Android launch command that resolves to a valid activity component.

Example:

UiAutomator2Options options = new UiAutomator2Options()
        .setAppPackage("com.example.shopping")
        .setAppActivity(".MainActivity");

The activity can be written as a fully qualified name or, where supported, as a relative name beginning with a period. A wrong package generally causes an unknown-package error, while a wrong, non-exported, or non-launchable activity may produce an activity-not-started or permission error.

The application should first be opened and brought to the screen whose activity is required. The connected devices can be checked with:

adb devices

On many Android versions, the resumed or focused activity can be inspected with commands such as:

adb shell dumpsys activity activities | grep mResumedActivity

or:

adb shell dumpsys window | grep -E 'mCurrentFocus|mFocusedApp'

On Windows, findstr can be used instead of grep:

adb shell dumpsys window | findstr mCurrentFocus

A typical component in the output is:

com.example.shopping/com.example.shopping.MainActivity

The part before / is the app package, and the part after / is the activity. An abbreviated output such as com.example.shopping/.MainActivity means that the full activity is com.example.shopping.MainActivity.

If multiple devices are connected, select one explicitly:

adb -s emulator-5554 shell dumpsys activity activities

Command output varies by Android version, so examining both activity and window service output is often useful.

dumpsys prints diagnostic information from Android system services. A focused or resumed activity is commonly represented as an Android component:

package.name/activity.name

For example:

com.demo.bank/.ui.LoginActivity

This gives:

• Package: com.demo.bank
• Relative activity: .ui.LoginActivity
• Fully qualified activity: com.demo.bank.ui.LoginActivity

Limitations and precautions:

• Output labels differ among Android releases; mCurrentFocus, mFocusedApp, or mResumedActivity may be present.
• A permission dialog, system launcher, browser, or keyboard may be focused instead of the target app.
• Splash screens can briefly expose a different activity from the stable main screen.
• Hybrid apps may show a native container activity rather than the current web page.
• Multiple connected devices require the adb -s <serial> option.
• A focused activity is not automatically guaranteed to be exported or directly launchable by Appium.

The tester should wait until the required screen is stable, confirm the package using adb shell pm list packages, and validate the component by attempting to start it with adb shell am start -n.

Android SDK tools can inspect an APK without first relying on the currently focused application.

Using Android Asset Packaging Tool:

aapt dump badging app-debug.apk

Relevant output commonly includes:

package: name='com.example.notes'
launchable-activity: name='com.example.notes.MainActivity'

Therefore:

• com.example.notes is the package name.
• com.example.notes.MainActivity is the launchable activity.

Depending on the installed build tools, apkanalyzer can also be used to inspect the manifest, for example:

apkanalyzer manifest application-id app-debug.apk
apkanalyzer manifest print app-debug.apk

The printed manifest can be examined for an activity containing an intent filter with the MAIN action and LAUNCHER category.

Points to remember:

• The APK's application ID can differ between build variants, such as debug and production.
• Activity aliases may serve as the launcher component.
• Split APKs or app bundles may require additional analysis tools or an installed application.
• The launchable activity discovered from the manifest should still be verified on the intended Android version and build.

The component can be verified with Android's Activity Manager command:

adb shell am start -W -n com.example.shopping/.MainActivity

Here:

• -n supplies the explicit package/activity component.
• -W waits for the launch result and reports timing and status information.

A successful result should indicate that the activity was started or brought to the foreground. The tester can then confirm the current activity with dumpsys.

Additional checks include:

• Confirm installation with adb shell pm list packages | grep com.example.shopping.
• Clear an existing state, if appropriate, with adb shell pm clear com.example.shopping.
• Check whether the activity is exported and launchable in the application manifest.
• Use adb -s <serial> when multiple devices are attached.
• Review Logcat if the application starts and immediately crashes.

If Android reports that the activity class does not exist, the activity name may be misspelled or incorrectly expanded. A security exception can indicate that the activity is not exported. A package-not-found error indicates that the expected application build is not installed.

Appium's UiAutomator2 driver can start an existing Android Virtual Device when the AVD name is supplied as a session option.

UiAutomator2Options options = new UiAutomator2Options()
        .setPlatformName("Android")
        .setAutomationName("UiAutomator2")
        .setDeviceName("Android Emulator")
        .setAvd("Pixel_6_API_33")
        .setAvdLaunchTimeout(Duration.ofSeconds(180))
        .setAvdReadyTimeout(Duration.ofSeconds(180))
        .setAppPackage("com.example.shopping")
        .setAppActivity(".MainActivity");

Important options:

• avd: exact name of an AVD already created on the machine.
• avdLaunchTimeout: maximum time allowed for the emulator process to start and become visible to ADB.
• avdReadyTimeout: maximum time allowed for Android to finish booting and become ready for automation.

The sequence is:

1. Appium checks whether a suitable emulator is already running.
2. It invokes the Android emulator executable for the named AVD when necessary.
3. It waits for the virtual device to become available through ADB.
4. It initializes UiAutomator2 and launches the target application.

Appium generally starts an existing AVD; the AVD itself must first be created with Android Studio's Device Manager or Android command-line tools.

Prerequisites:

• Android SDK and platform tools must be installed.
• The environment must allow Appium to locate tools such as adb and emulator.
• A valid AVD must already exist and can be listed with emulator -list-avds.
• The AVD name supplied to Appium must match exactly.
• Hardware virtualization or an appropriate acceleration mechanism should be enabled.
• The Appium UiAutomator2 driver must be installed.
• Required system images and licenses must be available.
• Sufficient memory, disk space, and permissions must be provided.

Timeout options:

• AVD launch timeout: Controls how long Appium waits for the emulator process to launch and appear as an ADB device.
• AVD ready timeout: Controls how long Appium waits for the virtual Android system to finish booting and become usable.

These timeouts are separate because an emulator may be visible in adb devices before Android has completed startup. Slow continuous-integration machines often require larger values.

If launch fails, the tester should run the AVD manually, check adb devices, review Appium logs, confirm the SDK environment, check port conflicts, and inspect whether another emulator with the same configuration is already running.

An end-to-end setup consists of project configuration, session creation, test execution, and cleanup.

Project setup:

• Create a Maven project with src/test/java and src/test/resources.
• Add the Appium Java client and JUnit or TestNG to pom.xml.
• Install Appium and the UiAutomator2 driver.
• Create an AVD and verify its name with emulator -list-avds.

Illustrative JUnit setup:

import io.appium.java_client.android.AndroidDriver;
import io.appium.java_client.android.options.UiAutomator2Options;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import java.net.URL;
import java.time.Duration;

class MobileTest {
    private AndroidDriver driver;

    @BeforeEach
    void setUp() throws Exception {
        UiAutomator2Options options = new UiAutomator2Options()
                .setPlatformName("Android")
                .setAutomationName("UiAutomator2")
                .setDeviceName("Android Emulator")
                .setAvd("Pixel_6_API_33")
                .setAvdLaunchTimeout(Duration.ofSeconds(180))
                .setAvdReadyTimeout(Duration.ofSeconds(180))
                .setAppPackage("com.example.shopping")
                .setAppActivity(".MainActivity");

        driver = new AndroidDriver(
                new URL("http://127.0.0.1:4723"), options);
    }

    @Test
    void applicationStarts() {
        System.out.println(driver.getSessionId());
    }

    @AfterEach
    void tearDown() {
        if (driver != null) {
            driver.quit();
        }
    }
}

The Appium server must be started before the test unless the framework also manages a local server process. quit() closes the Appium session, although emulator shutdown is a separate policy decision and may require an explicit ADB command or framework-level cleanup.

Common session-start failures include:

• Appium server is not running or the URL and base path are incorrect.
• The required Appium platform driver is not installed.
• Capability names are invalid or lack required vendor prefixes in a raw request.
• automationName does not match an installed driver.
• No device is connected, the selected udid is wrong, or the device is unauthorized.
• The AVD name is incorrect or the emulator does not finish booting.
• The APK path is invalid.
• appPackage or appActivity is incorrect.
• A system port is already in use.
• Java client, Selenium, Appium server, or driver versions are incompatible.

Systematic procedure:

1. Confirm the server URL by examining the Appium startup log.
2. List installed Appium drivers and verify UiAutomator2 is available.
3. Run adb devices and resolve offline or unauthorized states.
4. Start the emulator manually to separate emulator problems from Appium problems.
5. Verify the package and activity using adb shell am start -W -n.
6. Reduce the session to the minimum required options.
7. Inspect the server's serialized capabilities and full stack trace.
8. Add optional settings back one at a time.
9. Check dependency compatibility with mvn dependency:tree.
10. Always call quit() for partially successful sessions to avoid stale resources.

This layered method identifies whether the fault belongs to the Java client, network, Appium server, platform driver, ADB, emulator, or application.