Journeys for Android Studio

Creating journeys for Android Studio helps make end-to-end tests straightforward to write and maintain by allowing you to use natural language to describe the steps and assertions for each test—called a journey. By leveraging Gemini's vision and reasoning capabilities, steps written in natural language are converted into actions that Gemini executes on your app, making your journeys straightforward to write and understand. Additionally, you can write and describe more complex assertions, which Gemini evaluates based on what it sees on the device in order to determine whether your journeys pass or fail.

And because Gemini determines which actions to perform to satisfy the goals, journeys are more resilient to subtle changes to your app's layout or behavior, resulting in fewer flaky tests when running against different versions of your app and different device configurations.

Write and run journeys right from Android Studio against any local or remote Android powered device. The IDE provides a new editor experience for crafting journeys as well as rich results that help you better understand Gemini's reasoning and execution of your journey.

Write a journey

Android Studio provides a file template and new editor experience that simplifies creating and editing journeys. Journeys are written using Extensible Markup Language (XML) syntax to organize your journey description and steps.

To create and start editing a journey, do the following:

1. From the Project panel in Android Studio, right-click on the app module for which you want to write a journey.
2. Select New > Test > Journey File.
3. In the dialog that appears, provide the name and description of your journey.
4. Click OK. Android Studio creates an XML file for your journey with the name you chose. You can use either the Code view to edit the XML directly, or the Design view for an improved editing experience.
5. When viewing your journey in the Design view, use the text field to describe each step of your journey. Each step can include descriptive actions you want Gemini to perform or assertions that you want Gemini to evaluate.
6. Press Enter on your keyboard to start a new prompt in the same journey. You can repeat this as needed for each step of the journey you want to define.

Tips for writing journeys

Writing your journeys in a detailed and organized way can increase the likelihood of Gemini accurately running your intended journeys in a more deterministic way. Here are some tips to help you write your journeys more effectively:

• Separate assertions from actions: Gemini constantly evaluates the state of your app to determine if it's in a "correct" state to continue the journey. However, you might need to define more complex assertions as a separate step. Additionally, start each prompt using key phrases such as "Verify that," "Assert that," or "Check that" to indicate to Gemini that this step is meant to be an assertion.
• Direct Gemini with swipes: In addition to basic interactions, such as tapping or keyboard inputs, Gemini supports actions that require it to swipe the screen in certain directions. For example, to scroll through content or dismiss some UI describe the direction and intent of your swipe action. By default, Gemini swipes from the center of the screen, but you can specify that it should swipe on a different part of the device screen.
• Avoid complex interactions and configuration changes: Gemini doesn't support all interactions and configuration changes, such as multi-finger gestures, screen rotations, or folding actions. The team is working to improve Gemini capabilities.

Run your journey

You can run your journey on any available local or remote device, similar to any other instrumented test, and Android Studio generates rich results that help you understand the execution of your journey.

To test a journey, do the following:

1. Select a target device from the main toolbar, like you would when running an instrumented test.
2. Navigate to the journey XML file that you would like to test and open it in the editor.
3. In the editor, do one of the following:
   1. If you're in the Design view, click Run Journey.
   2. If you're in the Code view, click Run test in the gutter next to where the name of the journey is defined in the XML.

Android Studio creates a Journeys Test configuration for you and runs it on the target device. During execution, Android Studio builds and deploys your app, and connects to Gemini to determine the actions to take for each step of your journey.

Hover over the thumbnail in the editor to see more information. This can be helpful when iterating on the prompts in your journey.

View results

When Android Studio completes testing your journey, the test results panel appears automatically to show you the results.

Compared to other instrumented tests you might run in Android Studio, there are some differences in how results for journeys are displayed.

• The Tests panel breaks down the journey into the discrete steps. You can click on each step to find out more information about how Gemini executed it.
• The Results panel shows rich information to help you understand Gemini's interpretation and reasoning about your journey, and how it was executed by Gemini.
• The screenshots that were sent to Gemini are shown for visual aid at each action in the step.
• Each action taken and Gemini's reasoning for that action is described next to each screenshot.
• Each action in the step is numbered.

Known issues

• When testing a journey, all permissions for your app are granted by default.
• When testing a journey on a device running Android 15 (API level 35), you might see a warning on the device that says "Unsafe App Blocked" for "AndroidX Crawler". You can click Install anyway to bypass this check. Alternatively, you can Configure on-device developer options and disable the option to Verify apps over USB.
• Journey files do not currently appear in the Android view in the Projects panel. To see journey files in your project, use the Project view.
• If multiple actions within a journey share the exact same prompt, the test results displayed in the journey editor may be incorrect. Specifically, all actions with the duplicate prompt will show the test results associated with the most recently updated instance of that prompt. To work around this, ensure each action has a unique prompt—for example, by adding a distinct prefix or suffix.
• A stylus popup appears the second time the keyboard is loaded on a fresh emulator. This popup usually causes tests that interact with text fields to fail. When this occurs, dismiss the popup and rerun the journey.
• App crawler artifacts might occasionally appear in agent rationale.
• Journey execution occasionally fails with an IllegalStateException. When this happens, you can click on Test Results to see the full error.

• If the Android Gradle Plugin (com.android.application) isn't defined in the top-level build.gradle file, you may see the following error when running a journey:

  Failed to apply plugin class 'com.android.tools.journeys.JourneysGradlePlugin'
  

  To resolve this, ensure that the plugin is defined in the top-level build.gradle file. See Configure the Android build system for more information.