Java Appium with Evinced

Sample project for running Evinced accessibility tests against Android and iOS apps with Appium and the Evinced Appium Java SDK.

Test parameters (test-params.properties)

Tests read configuration from a properties file so you can keep credentials and device settings in one place. The application only reads test-params.properties; it does not read the sample file.

1. Copy the sample file to create your local config:

   cp src/test/resources/test-params.properties.sample src/test/resources/test-params.properties

2. Edit src/test/resources/test-params.properties and set:

   Property	Description
   EVINCED_SERVICE_ID	Your Evinced service account ID.
   EVINCED_OFFLINE_TOKEN	Your Evinced offline access token. Obtain from your Evinced account or, if outbound internet is not available, contact support@evinced.com for an offline token.
   ANDROID_DEVICE	Name of the Android device or emulator to use (see How to get the device name below). Required for Android tests.
   IOS_DEVICE	UDID of the iOS Simulator to use (see Starting an iOS Simulator below). Required for iOS tests; the iOS test MUST run on a simulator.
   APPIUM_SERVER_URL	(Optional) Appium server URL. Default: http://127.0.0.1:4723/. Set this if Appium runs on another host or port.

3. Do not commit test-params.properties. It is listed in .gitignore. Only test-params.properties.sample is checked into git as a template.

Starting an Android emulator

You need a running Android device or emulator before running the tests.

Using Android Studio (AVD Manager)

1. Open Android Studio and go to Tools → Device Manager (or AVD Manager).
2. Click Create Device to add a new virtual device, or select an existing one.
3. Click the Play (▶) button next to the device to start the emulator.
4. Wait until the emulator boot is complete and the home screen is visible.

Using the command line (avdmanager + emulator)

1. List available AVDs:

   $ANDROID_HOME/emulator/emulator -list-avds

   Example output: Pixel_9_Pro_XL_API_35, Pixel_4_API_30, etc.

2. Start an AVD by name:

   $ANDROID_HOME/emulator/emulator -avd Pixel_3a_API_35

   Use one of the names from the list. Leave this terminal open while running tests.

ANDROID_HOME is usually set by Android Studio or the SDK installer (e.g. ~/Library/Android/sdk on macOS).

How to get the device name

The value you put in ANDROID_DEVICE in test-params.properties depends on how you run the tests.

• Emulator (AVD): Use the AVD name from emulator -list-avds (e.g. Pixel_9_Pro_XL_API_35). Appium often accepts this as the device name when the emulator is the only device.
• Connected device or when multiple devices exist: Use the device ID from adb devices:

  adb devices

  Example output:

  List of devices attached
  emulator-5554   device
  

  Use the first column as ANDROID_DEVICE (e.g. emulator-5554).

If you use a generic name like Android Emulator, Appium will target the first available device/emulator. For a specific device when several are connected, use the adb devices ID.

Starting an iOS Simulator

The iOS test MUST be run on an iOS Simulator (not a physical device). You need Xcode and the Xcode Command Line Tools installed.

Prerequisites

• Xcode installed (from the Mac App Store or Apple Developer).
• Command Line Tools: In Xcode, go to Xcode → Settings → Locations and ensure Command Line Tools is set to your Xcode version. You can also run xcode-select --install to install the standalone command line tools.

Boot a simulator before running the iOS test

1. List available simulators (find the UDID, which is the GUID for each device):

   xcrun simctl list devices

   Choose an iPhone simulator that is fairly recent (e.g. iPhone 16 with iOS 18.0). The UDID is the long hexadecimal string in parentheses or in the device list.

2. Boot the simulator (replace UDID with the UDID from step 1):

   xcrun simctl boot UDID

   Example: This was tested on iPhone 17 (iOS 26.2). Use the UDID shown for that device in xcrun simctl list devices.

3. (Optional) Show the Simulator app so you can see the device on screen:

   open -a Simulator

4. Set IOS_DEVICE in test-params.properties to that UDID. The iOS test uses this to connect Appium to the booted simulator.

5. (Optional) Shut down the simulator when finished:

   xcrun simctl shutdown UDID

Appium server

The test starts the Appium server automatically before running and stops it after. You do not need to run Appium in a separate terminal.

Requirement: The appium command must be installed and on your PATH. Install it with:

npm install -g appium

If Appium runs on a different host or port, set APPIUM_SERVER_URL in test-params.properties. The test will start the server on the port from that URL (default: http://127.0.0.1:4723/).

Other requirements

• Android app under test: Place your Android APK at src/test/resources/app-debug.apk. The Android test installs and launches this app on the device/emulator.
• iOS app under test: The iOS test uses src/test/resources/SmallButtonSampleApp.app. No extra setup needed if the project already includes this app bundle.

Run the tests

Android (requires a running Android device or emulator and ANDROID_DEVICE in test-params.properties):

./gradlew test --tests "org.evinced.EvincedAndroidAppTest.testDemoEvincedAndroidApp"

The test installs the app, opens it, runs an Evinced accessibility report, and asserts that at least one issue is found.

iOS (requires a booted iOS Simulator and IOS_DEVICE set to the simulator UDID in test-params.properties; see Starting an iOS Simulator):

./gradlew test --tests "org.evinced.EvincedIosAppTest.testDemoEvincedIosApp"

The test launches SmallButtonSampleApp.app on the simulator, runs an Evinced accessibility report, and asserts that at least one issue is found.