Setting up Accessibility Insights for Android

The following steps will prepare you to use Accessibility Insights for Android to run automated checks (on a Windows, Mac, or Linux computer) on an Android app running on a hardware device or Android Virtual Device.

Getting Started with Accessibility Insights for Android

Prepare your test environment

1. You'll need Android Debug Bridge (adb) or a similar tool to communicate with your hardware or virtual device. The following instructions assume you're using adb.
2. If you're testing on a hardware device, you'll need to enable developer options and debugging on your device.

Note: We do not recommend using a personal Android device for testing and development; we recommend using a test device or emulator. Software under development may not yet be fully secure, and many development tools require permissions that could present a potential risk to your device and data.

Install Accessibility Insights for Android

Windows

Using the setup wizard

1. Go to Accessibility Insights Downloads.
2. Under For Android, select Download on Windows.
3. When the installer file finishes downloading, open it.
4. Follow the instructions in the setup wizard.

Using a command prompt

This method is an alternative to using the setup wizard.

1. Go to Accessibility Insights Downloads.
2. Under For Android, select Download on Windows.
3. When the installer file finishes downloading, open a command prompt.
4. Run the installer in silent mode. For example, enter the following command (including the quotes): "%HOMEPATH%\Downloads\Accessibility Insights for Android setup.exe" /S

Mac

1. Go to Accessibility Insights Downloads.
2. Under For Android, select Download on MacOS.
3. When the installer file finishes downloading, open it.
4. In the window that appears, drag the app icon to the Applications folder.

Linux

1. Go to Accessibility Insights Downloads.

2. Under For Android, select Download on Linux.

3. When the installer file finishes downloading, open a Terminal session and navigate to the folder where the application is stored.

4. Make the file executable by entering the following command:

   chmod +x Accessibility_Insights_for_Android.AppImage

5. Open the application by entering the following command:

   ./Accessibility_Insights_for_Android.AppImage

Connect to your device

If you're testing on a hardware device:

1. Connect your device to your computer via USB.

   A confirmation message will ask, "Allow access to phone (or tablet) data?"

2. Select Allow.

   

If you're testing on a virtual device:

1. In Android Studio or the Android Virtual Device Manager, select a virtual device.
2. Select Run.

Open Accessibility Insights for Android

Accessibility Insights for Android will check your configuration and walk you through completion of your setup. Depending on your setup, the tool will display one or more of these messages.

We need your help

This message will appear the first time you open Accessibility Insights for Android.

What to do

1. Choose an option to enable or opt out of telemetry.
2. Select OK.

Loading

This message will appear while the app checks your configuration.

What to do

Wait for the app to check your configuration.

Locate Android Device Bridge (adb)

This message will appear if the app can't find adb on your computer.

What to do

1. Enter the path to (or browse to) the folder on your computer that contains the adb.exe file. The folder is usually called platform-tools.
2. Select Next.

Connect to your Android device

This message will appear if the app can't detect any connected devices.

What to do

1. Make sure your device is connected to your computer and you have enabled developer options and debugging in the device.
2. On your device, allow your computer to access the device's data.
3. Select Detect my device.

Choose which device to use

This message will appear if the app detects more than one connected device.

What to do

1. Choose the device you want to use with Accessibility Insights for Android.
2. Select Continue.

Let us install the latest version on your device

This message will appear if the Accessibility Insights for Android service on your device is missing or out of date.

What to do

1. Select Install.
2. Wait while the service installs on your device.

Installation attempt failed

This message will appear if the app can't install the latest Accessibility Insights for Android service on your device.

What to do

1. Install the service manually.
2. Select Try again.

Grant permissions on your device

This message will appear if you need to turn on or grant permissions to the Accessibility Insights for Android service on your device.

What to do

1. On your device, go to Settings > Accessibility > Installed services > Accessibility Insights Service and turn on the service.

   Note: Depending on your Android version, the path may include Downloaded services instead of Installed services.

   

2. When the first permissions dialog appears, select OK.

3. When the second permissions dialog appears, select Start now.

   Note: Android manages the content of the permissions dialogs. Exact wording depends on the Android version you are running.

Establishing connection failed

This message will appear if we cannot communicate with the Accessibility Insights for Android service on the device.

What to do

Try each of the following steps (in order) to see if it resolves the problem.

1. Select the Try again button to restart the setup process.
2. On your computer, close and re-open Accessibility Insights for Android.
3. Disconnect and reconnect your device, then select Try again.
4. On your device, under Settings > Accessibility > Installed services Accessibility Insights for Android Service, turn the service off and back on, then select Try again.
5. On your device, uninstall the Accessibility Insights for Android Service, then select Try again.
6. Restart your device, then select Try again.

Connected and ready

This message appears when your setup is complete. You'll see this message each time you use Accessibility Insights for Android.

What to do

• To run tests on the current device and app:
  • Select Start testing.
• To run tests on a different app:
  1. On your device, open the app you want to test and navigate to the screen where you want to start testing.
  2. Select Rescan devices.
  3. Select Start testing.
• To run tests on a different device:
  1. Connect the device you want to use.
  2. On the device, open the app you want to test and navigate to the screen where you want to start testing.
  3. Select Rescan devices.
  4. Follow any instructions that appear.
  5. When the device is visible in the Connected and ready screen, select Start testing.

Troubleshooting

Manual installation

Problem

Accessibility Insights for Android was unable to install the service on your device.

Solution

Install the service manually.

1. Download the AccessibilityInsightsforAndroidService.apk file to your computer.

2. Install the service:

   1. On your computer, open a Command Prompt (Windows) or Terminal (Mac or Linux) session.

   2. Navigate to the directory where the .apk file is stored.

   3. Enter the following command:

      adb install AccessibilityInsightsforAndroidService.apk

      When installation starts, the system will report, Performing Streamed Install.

      When installation is complete, the system will report, Success.

      

3. Turn on the service:

   1. On your device, go to Settings > Accessibility > Installed services > Accessibility Insights for Android Service and turn on the service.

      Note: Depending on your Android version, the path may include Downloaded services instead of Installed services.

      

   2. When the first permissions dialog appears, select OK.

   3. When the second permissions dialog appears, select Start now.

   Note: Android manages the content of the permissions dialogs. Exact wording depends on the Android version you are running.

Screenshot is broken

Problem

When you run automated checks, the screenshot of your target app is broken.

Solution

On your device, make sure you have turned on the Accessibility Insights for Android Service and granted the requested permissions.

Accessibility Insights for Android can't be opened

Problem

When you attempt to install Accessibility Insights for Android on a Mac, you get this error message: "Accessibility Insights for Android" cannot be opened because Apple cannot check it for malicious software.

This is a known issue for our tool running in macOS Catalina (10.15) and later. For details, refer to issue #2154.

Solution

1. In the error message, select Show in Finder.
2. In the Applications folder, right-click or Control+Click the Accessibility Insights for Android file.
3. In the context menu, select Open.
4. In the dialog, select Open.

OR

1. Go to System Preferences > Security & Privacy. You'll see a message: "Accessibility Insights for Android" was blocked from use because it is not from an identified developer." (The application name might be truncated.)
2. Select Open Anyway.
3. In dialog, select Open.

It might be necessary to repeat these steps once each time a new version is installed.

Application isn't updating to the latest version

Problem

Accessibility Insights for Android updates automatically. When you open the app, it starts downloading the latest version. When you close the app, it starts the installation. If the app is closed before the latest version has finished downloading, the update will fail.

Solution

1. Launch Accessibility Insights for Android.
2. Leave the application open a few minutes, then close it.
3. Wait a few minutes, then launch the application again.

Uninstalling Accessibility Insights for Android

Uninstall the app

Windows

Uninstall using Apps & features

1. Go to Apps & features, select Accessibility Insights for Android, and then select Uninstall.
2. Optional: Delete the following folder: C:\Users\username\AppData\Local\accessibility insights for android-updater

Uninstall using a command prompt

This method is an alternative to using the setup wizard.

1. Open a command prompt.

2. Navigate to the directory where the application is installed. For example, enter the following command (including the quotes):

   cd "%LOCALAPPDATA%\Programs\Accessibility Insights for Android"

3. Run the uninstaller with the /S flag. For example, enter the following command (including the quotes):

   "Uninstall Accessibility Insights for Android.exe" /S

Mac

1. Select Finder > Go > Applications and delete the Accessibility Insights for Android app.
2. Select Finder > Go > Go to Folder… and go to ~/Library/Application Support.
3. Delete the Accessibility Insights for Android folder.

Linux

1. Delete the Accessibility Insights for Android.AppImage file.
2. Delete this folder: ~/.config/Accessibility Insights for Android

Uninstall the service

Uninstall using ADB

1. Open a Command Prompt (Windows) or Terminal (Mac or Linux) session.

2. Enter the following command:

   adb uninstall com.microsoft.accessibilityinsightsforandroidservice

3. The system will report, Success.

Uninstall from your device

1. On your device, go to Settings > Apps > Accessibility Insights Service.

2. Select Uninstall.

   A confirmation message will ask, "Do you want to uninstall this app?"

3. Select OK.