New features in Android Studio Preview

This page lists the new features introduced in Android Studio preview releases. The preview builds provide early access to the latest features and improvements in Android Studio. You can download these preview versions here. If you encounter any problems using a preview version of Android Studio, please let us know. Your bug reports help to make Android Studio better.

For the latest news on Android Studio preview releases, including a list of notable fixes in each preview release, see the Release Updates in the Android Studio blog.

Current versions of Android Studio

The following table lists the current versions of Android Studio and their respective channels.

Version Channel
Android Studio Giraffe | 2022.3.1 Stable
Android Gradle plugin 8.1.0 Stable
Android Studio Hedgehog | 2023.1.1 Beta
Android Studio Iguana | 2023.2.1 Canary

Compatibility with Android Gradle plugin previews

Each preview version of Android Studio is published alongside a corresponding version of the Android Gradle plugin (AGP). Preview versions of Studio should work with any compatible stable version of AGP. However, if you're using a preview version of AGP, you must use the corresponding preview version of Studio (for example, Android Studio Chipmunk Canary 7 with AGP 7.2.0-alpha07). Attempts to use divergent versions (for example, Android Studio Chipmunk Beta 1 with AGP 7.2.0-alpha07) will cause a Sync failure, which results in a prompt to update to the corresponding version of AGP.

For a detailed log of Android Gradle plugin API deprecations and removals, see the Android Gradle plugin API updates.

Android Studio Hedgehog | 2023.1.1

The following are new features in Android Studio Hedgehog.

Compose Multipreview templates

androidx.compose.ui:ui-tooling-preview 1.6.0-alpha01+ introduces new Multipreview API templates: @PreviewScreenSizes, @PreviewFontScales, @PreviewLightDark, and @PreviewDynamicColors, so that with one single annotation, you can preview your Compose UI in common scenarios.

New macro to specify JDK path

Android Studio Hedgehog Canary 10 introduces a new macro, #GRADLE_LOCAL_JAVA_HOME, to specify the JDK path. This makes it safer and easier to specify the Java home path used for the Gradle daemon (background process) execution for your project. The path selection is stored in the java.home field in the .gradle/config.properties file. Set this field through Gradle JDK settings in Android Studio (File or Android Studio > Settings > Build, Execution, Deployment > Build Tools > Gradle).

New projects will use #GRADLE_LOCAL_JAVA_HOME by default. Existing projects will automatically be migrated to the new macro after a successful sync, unless you're already using a macro like #JAVA_HOME.

The main benefits of the new macro are as follows:

  • You can manually modify the JDK path to trigger sync without opening your project first.
  • Fewer errors related to incompatible Gradle and project JDK versions, since there is a single source of truth for your Gradle JDK selection.

Analyze Android vitals in App Quality Insights

App Quality Insights now includes Android vitals data, so you can more easily access core metrics collected by Google Play and improve your user experience. Use Android vitals to address issues related to app stability to help improve the quality of your app on Google Play.

You can view Android vitals issues, filter them, and jump from stack trace to code all from the App Quality Insights tool window. To get started, follow these steps:

  1. Sign in to your developer account in Android Studio using the profile icon at the end of the toolbar.
  2. Open App Quality Insights by clicking the tool window in Android Studio or clicking View > Tool Windows > App Quality Insights.
  3. Click the Android vitals tab within App Quality Insights.

Different numbers between Android vitals and Crashlytics

Note that Android vitals and Crashlytics might report different values for the numbers of users and events associated with the same crash. These discrepancies happen because Play and Crashlytics can catch crashes at different times and for different users. Here are a couple reasons for why the Play and Crashlytics counts might differ:

  • Play catches crashes starting at boot time, whereas Crashlytics catches crashes that happen after the Crashlytics SDK initializes.
  • If a user opts out of crash reporting when they get a new phone, those crashes aren't reported to Play; however, Crashlytics catches crashes based on an app's own privacy policy.

Device mirroring

You can now mirror your physical device in the Running Devices window in Android Studio. By streaming your device's display directly to Android Studio, you can execute common actions such as starting apps and interacting with them, rotating the screen, folding and unfolding the phone, changing the volume, and more right from the Studio IDE itself.

Device mirroring is always available when there are devices connected to the computer that have USB or wireless debugging enabled. You can start and stop mirroring using the Running Devices window or the Device Manager (View > Tool Windows > Device Manager). You can also customize when device mirroring is activated in its settings (Settings > Tools > Device Mirroring).

Running Devices UI

Known issue: Some device may not be capable of encoding at a bitrate sufficient to support device mirroring. In these situations, you might see an error in the Running Devices window as well as logs similar to what's shown below.

2023-06-01 15:32:22,675 [  56094]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - Too many video encoder errors:
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - encoder: c2.android.vp8.encoder
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - mime type: video/x-vnd.on2.vp8
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max resolution: 640x640
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - min resolution: 2x2
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - alignment: 2x2
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max frame rate: 960
2023-06-01 15:32:22,676 [  56095]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max frame rate for 288x640: 960
2023-06-01 15:32:22,870 [  56289]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - max bitrate: 20000000
2023-06-01 15:32:22,871 [  56290]   WARN - ScreenSharingAgent Samsung SM-A045F API 33 - terminated with code 1

Privacy notice

If device mirroring is enabled, Android Studio automatically starts device mirroring for any connected and paired device. This might result in information disclosure for devices connected with the adb tcpip command because the mirroring information and commands are passed over a non-encrypted channel. In addition, Android Studio uses a non-encrypted channel to communicate with the adb server, so mirroring information can be intercepted by other users on your host machine.

Manage devices directly from the Running Devices window

You can now start an Android Virtual Device (AVD), or start mirroring a physical device, directly from the Running Devices window by clicking the + icon and selecting a device. To stop the AVD or mirroring of a physical device, close the device tab.

Device drop-down from Running Devices

Compose state information in debugger

When parts of your Compose UI recompose unexpectedly, it's sometimes difficult to understand why. Now, when setting a breakpoint on a composable function, the debugger lists the parameters of the composable and their state, so you can more easily identify what changes might have caused the recomposition. For example, when you pause on a composable, the debugger can tell you exactly which parameters have "Changed" or have remained "Unchanged", so you can more efficiently investigate the cause of the recomposition.

Launch Android Studio in Safe Mode

Android Studio Hedgehog introduces the ability to launch Android Studio in Safe Mode. This mode can be useful if you run into a situation where certain features don't work or the entire IDE fails to launch, which can sometimes be caused by custom configurations, environment variables, or plugins that are incompatible with Android Studio.

Using Safe Mode temporarily returns the IDE to a set of default configurations that might allow it to launch, so that you can troubleshoot from there to identify the issue and restore functionality. Safe Mode attempts to open Android Studio with limited functionality by taking actions including the following:

  • Disables third-party plugins
  • Restores bundled Kotlin plugin to the version originally included with Studio
  • Temporarily resets configurations, for example in the studio.vmoptions file
  • Validates environment variables that can prevent startup, such as JRE_HOME and TMP
  • Reverts the JRE to a compatible version if needed

To launch Android Studio in Safe Mode, follow these steps:

  1. Find the Safe Mode script.
    • On Windows, navigate to AndroidStudio/bin and find the studio_safe.bat script.
    • On macOS, navigate to Android Studio/Contents/bin and find the studio_safe.sh script.
    • On Linux, navigate to android-studio/bin and find the studio_safe.sh script.
  2. Run the script: open the command line and type studio_safe.bat (studio_safe.sh for macOS or Linux), and press Enter.

Embedded Layout Inspector

Starting with Android Studio Hedgehog Canary 2, you can run the Layout Inspector directly in the Running Devices tool window. This experimental feature conserves screen real estate and helps organize your UI debugging workflow in a single tool window. In embedded mode you can show a view hierarchy, inspect the properties of each view, and access other common Layout Inspector features. To access the full set of options, you still need to run the Layout Inspector in a standalone window (File > Settings > Experimental > Layout Inspector on Windows or Android Studio > Settings > Experimental > Layout Inspector on macOS).

A limitation of the embedded Layout Inspector is that 3D mode is only available in snapshots.

To help us improve the embedded Layout Inspector, please send us feedback.

Use Firebase Test Lab devices with Gradle Managed Devices

When using AGP 8.2.0-alpha03 or higher, you can run your automated instrumented tests at scale on Firebase Test Lab devices when using Gradle Managed Devices. Test Lab lets you run your tests simultaneously on a wide range of Android devices, both physical and virtual. These tests run in remote Google data centers. With support from Gradle Managed Devices (GMD), the build system can now fully manage running tests against these Test Lab devices based on the configurations in your project's Gradle files.

Get started with Gradle managed Firebase Test Lab devices

The following steps describe how to start using Firebase Test Lab devices with GMD. Note that these steps use the gcloud CLI to provide user credentials, which might not apply to all development environments. For more information about what authentication process to use for your needs, see How Application Default Credentials works.

  1. To create a Firebase project, go to the Firebase console. Click Add project and follow the on-screen prompts to create a project. Remember your project ID.

  2. To install the Google Cloud CLI, follow the steps at Install the gcloud CLI.

  3. Configure your local environment.

    1. Link to your Firebase project in gcloud:

      gcloud config set project FIREBASE_PROJECT_ID

    2. Authorize the use of your user credentials for API access. We recommend authorizing by passing a service account JSON file to Gradle using the DSL in the module-level build script:

      Kotlin

      firebaseTestLab {
  ...
  serviceAccountCredentials.set(file(SERVICE_ACCOUNT_JSON_FILE))
}

      Groovy

      firebaseTestLab {
  ...
  serviceAccountCredentials = file(SERVICE_ACCOUNT_JSON_FILE)
}

      Alternatively, you can authorize manually by using the following terminal command:

      gcloud auth application-default login

    3. Optional: Add your Firebase project as the quota project. This step is only needed if you exceed the no-cost quota for Test Lab.

      gcloud auth application-default set-quota-project FIREBASE_PROJECT_ID

  4. Enable required APIs.

    In the Google Developers Console API Library page, enable the Cloud Testing API and Cloud Tool Results API by typing these API names into the search box at the top of the console, and then clicking Enable API on the overview page for each API.

  5. Configure your Android project.

    1. Add the Firebase Test Lab plugin in the top-level build script:

      Kotlin

      plugins {
  ...
  id("com.google.firebase.testlab") version "0.0.1-alpha03" apply false
}

      Groovy

      plugins {
  ...
  id 'com.google.firebase.testlab' version '0.0.1-alpha03' apply false
}

    2. Enable custom device types in the gradle.properties file:

      android.experimental.testOptions.managedDevices.customDevice=true

    3. Add the Firebase Test Lab plugin in the module-level build script:

      Kotlin

      plugins {
 ...
 id "com.google.firebase.testlab"
}

      Groovy

      plugins {
 ...
 id 'com.google.firebase.testlab'
}

Create and run tests on a Gradle managed Firebase Test Lab device

You can specify a Firebase Test Lab device for Gradle to use for testing your app in the module-level build script. The following code sample creates a Pixel 3 running API level 30 as a Gradle managed Test Lab device called ftlDevice. The firebaseTestLab {} block is available when you apply the com.google.firebase.testlab plugin to your module. The minimum supported Android Gradle Plugin version is 8.2.0-alpha01.

Kotlin

firebaseTestLab {
  managedDevices {
    create("ftlDevice") {
      device = "Pixel3"
      apiLevel = 30
    }
  }
  ...
}

Groovy

firebaseTestLab {
  managedDevices {
    create("ftlDevice") {
      device = "Pixel3"
      apiLevel = 30
    }
  }
  ...
}

To run your tests using the Gradle managed Test Lab devices you configured, use the following command. device-name is the name of the device you configured in your Gradle build script, such as ftlDevice, and BuildVariant is the build variant of your app you want to test. Note that Gradle doesn't run tests in parallel or support other Google Cloud CLI configurations for Test Lab devices.

On Windows:

gradlew device-nameBuildVariantAndroidTest

On Linux or macOS:

./gradlew device-nameBuildVariantAndroidTest

The test output includes a path to an HTML file that has the test report. You can also import test results into Android Studio for further analysis by clicking Run > Test History in the IDE.

Create and run tests on a device group

To scale your testing, add multiple Gradle managed Firebase Test Lab devices to a device group and then run tests on all of them with a single command. Say you have multiple devices set up as follows:

firebaseTestLab {
  managedDevices {
    create("GalaxyS23Ultra") { ... }
    create("GalaxyZFlip3") { ... }
    create("GalaxyZFold3") { ... }
    create("GalaxyTabS2") { ... }
  }
}

To add them to a device group called samsungGalaxy, use the groups {} block:

firebaseTestLab {
  managedDevices {...}
}

android {
  ...
  testOptions {
    managedDevices {
      groups {
        create("samsungGalaxy") {
          targetDevices.add(devices["GalaxyS23Ultra"])
          targetDevices.add(devices["GalaxyZFlip3"])
          targetDevices.add(devices["GalaxyZFold3"])
          targetDevices.add(devices["GalaxyTabS3"])
        }
      }
    }
  }
}

To run tests on all the devices in the device group, use the following command:

On Windows:

gradlew group-nameGroupBuildVariantAndroidTest

On Linux or macOS:

./gradlew group-nameGroupBuildVariantAndroidTest

Optimize test runs with smart sharding

Testing on Gradle managed Test Lab devices now supports smart sharding. Smart sharding automatically distributes your tests across shards such that each shard runs for approximately the same time, reducing manual allocation efforts and overall test run duration. Smart sharding uses your test history, or information about how long your tests have taken to run previously, to distribute tests in an optimal way. Note that you need version 0.0.1-alpha03 of the Gradle plugin for Firebase Test Lab to use smart sharding.

To enable smart sharding, specify the amount of time tests within each shard should take. You should set the target shard time duration to at least five minutes less than timeoutMinutes to avoid the situation where shards are canceled before tests can finish.

firebaseTestLab {
  ...
  testOptions {
    targetedShardDurationMinutes = 2
  }
}

To learn more, read about the new DSL options.

Updated DSL for Gradle managed Firebase Test Lab devices

There are more DSL options you can configure to help customize your test runs or migrate from other solutions you may already be using. See some of these options as described in the following code snippet.

firebaseTestLab {
  ...

  /**
   * A path to a JSON file that contains service account credentials to access to
   * a Firebase Test Lab project.
   */
  serviceAccountCredentials.set(file("your_service_account_credentials.json"))


  testOptions {
    fixture {
      /**
       * Whether to grant permissions on the device before tests begin.
       * Available options are "all" or "none".
       *
       * Default value is "all".
       */
      grantedPermissions = "all"

      /**
       * Map of files to push to the device before starting the test.
       *
       * The key is the location on the device.
       * The value is the location of the file, either local or in Google Cloud.
       */
      extraDeviceFiles["/sdcard/dir1/file1.txt"] = "local/file.txt"
      extraDeviceFiles["/sdcard/dir2/file2.txt"] = "gs://bucket/file.jpg"

      /**
       * The name of the network traffic profile.
       *
       * Specifies network conditions to emulate when running tests.
       *
       * Default value is empty.
       */
      networkProfile = "LTE"
    }

    execution {
      /**
       * The maximum time to run the test execution before cancellation,
       * measured in minutes. Does not include the setup or teardown of device,
       * and is handled server-side.
       *
       * The maximum possible testing time is 45 minutes on physical devices
       * and 60 minutes on virtual devices.
       *
       * Defaults to 15 minutes.
       */
       timeoutMinutes = 30

      /**
       * Number of times the test should be rerun if tests fail.
       * The number of times a test execution should be retried if one
       * or more of its test cases fail.
       *
       * The max number of times is 10.
       *
       * The default number of times is 0.
       */
      maxTestReruns = 2

      /**
       * Ensures only a single attempt is made for each execution if
       * an infrastructure issue occurs. This doesn't affect `maxTestReruns`.
       * Normally, two or more attempts are made by Firebase Test Lab if a
       * potential infrastructure issue is detected. This is best enabled for
       * latency sensitive workloads. The number of execution failures might be
       * significantly greater with `failFast` enabled.
       *
       * Defaults to false.
       */
      failFast = false

      /**
       * The number of shards to split the tests across.
       * 
       * Default to 0 for no sharding.
       */
      numUniformShards = 20
    }

    /**
     * For smart sharding, the target length of time each shard should takes in
     * minutes. Maxes out at 50 shards for physical devices and 100 shards for
     * virtual devices.
     *
     * Only one of numUniformShards or targetedShardDurationMinutes can be set.
     *
     * Defaults to 0 for no smart sharding.
     */
     targetedShardDurationMinutes = 15
    }

    results {
      /**
       * The name of the Google storage bucket to store the test results in.
       *
       * If left unspecified, the default bucket is used.
       *
       * Please refer to Firebase Test Lab permissions for required permissions
       * for using the bucket.
       */
      cloudStorageBucket = "bucketLocationName"

      /**
       * Name of test results for the Firebase console history list.
       * All tests results with the same history name are grouped
       * together in the Firebase console in a time-ordered test history list.
       *
       * Defaults to the application label in the APK manifest in Flank/Fladle.
       */
      resultsHistoryName = "application-history"

      /**
       * List of paths to copy from the test device's storage to the test
       * results folder. These must be absolute paths under /sdcard or
       * /data/local/tmp.
       */
      directoriesToPull.addAll(
        "/sdcard/path/to/something"
      )

      /**
       * Whether to enable video recording during the test.
       *
       * Disabled by default.
       */
      recordVideo = false

      /**
       * Whether to enable performance metrics. If enabled, monitors and records
       * performance metrics such as CPU, memory, and network usage.
       *
       * Defaults to false.
       */
      performanceMetrics = true
    }
  }
}

Support for Gradle Version Catalogs

Android Studio Giraffe introduces support for TOML-based Gradle Version Catalogs, a feature that lets you manage dependencies in one central location and share dependencies across modules or projects. Android Studio now makes it easier to configure version catalogs through editor suggestions and integration with the Project Structure dialog. To learn how to update to Gradle Version Catalogs, see Migrate your build to version catalogs.

Code completion and navigation

Android Studio offers code completion when you're editing a version catalog in the TOML file format or adding a dependency from a version catalog to a build file. To use code completion, press Ctrl+Space (Command+Space on macOS). In addition, quickly navigate from a dependency reference in your app's build.gradle file to where it's declared in the version catalog by pressing Ctrl+b (Command+b on macOS).

Code completion when adding a dependency

Integration with the Project Structure dialog

If your project uses a version catalog defined in the TOML file format, you can edit variables you've defined there through the Project Structure dialog Variables view (File > Project Structure > Variables) in Android Studio. For each version catalog, there is a drop-down that lists the variables from that catalog. To edit a variable, click on its value and overwrite it. When you save these changes, the TOML file is updated accordingly.

Variables from a version catalog in the Project Structure dialog

You can also update dependencies in the Project Structure dialog Dependencies view (File > Project Structure > Dependencies). To update versions using the Project Structure dialog, navigate to the module and dependency you want to edit, and then update the Requested Version field. When you save these changes, the TOML file is updated accordingly. Note that if the dependency version was defined using a variable, updating the version directly this way replaces the variable with a hardcoded value. Also be aware that removing a dependency from a build file, whether you use the Project Structure dialog or not, doesn't remove the dependency from the version catalog.

Dependencies from a version catalog in the Project Structure dialog

Known issues and limitations

The following are known issues or limitations with Gradle Version Catalogs support in Android Studio.

Error highlighting plugin alias declarations in Kotlin script files

When you add a plugin declaration of the form alias(libs.plugins.example), the editor adds a red underline under the libs part. This is a known issue in Gradle versions 8.0 and lower and will be resolved in a future release of Gradle.

Android Studio support only for version catalogs in TOML format

Currently the Android Studio code completion, navigation, and Project Structure dialog support is only available for version catalogs defined in the TOML file format. However, you can still add a version catalog directly in the settings.gradle file and use its dependencies in your project.

Navigating to a dependency definition in a version catalog by using Control+click (Command+click on macOS) isn't yet supported for build files written using Kotlin script.

Firebase Assistant adds dependencies directly in build scripts

The Firebase Assistant adds dependencies directly to your build scripts instead of through version catalogs.

"Find usages" functionality not supported

Finding usages of a version catalog variable in other build files isn't yet supported, whether the build file is in KTS or Groovy. That is, using Control+click (Command+click on macOS) on a variable definition in a version catalog doesn't lead to the build files where the variable is used.

Project Structure dialog doesn't show catalogs from composite builds

The Project Structure dialog in Android Studio shows multiple catalog files if they're in the root gradle folder, but doesn't show catalogs for a composite build. For example if you have two catalog files, one for your app and one for a composite build, the Project Structure dialog only shows the app catalog file. You can use a composite build, but you have to edit its TOML file directly.

Disable build optimization for target API level only

Starting with Android Studio Giraffe Canary 6, you can disable IDE optimization for the target device API level. By default, Android Studio reduces overall build time by tailoring the dexing process for the API level of the target device you're deploying to. To turn this feature off, go to File > Settings > Experimental (Android Studio > Settings > Experimental on macOS) and uncheck Optimize build for target device API level only. Note that turning off this build optimization might increase build time.

[Windows-only] Minimize the impact of antivirus software on build speed

Build Analyzer informs you if antivirus software might be impacting your build performance. This can happen if antivirus software, such as Windows Defender, is doing real-time scanning of directories used by Gradle. Build Analyzer recommends a list of directories to exclude from active scanning and, if possible, it offers a link to add them to the Windows Defender folder exclusion list.

Eclipse Android Development Tool projects are no longer supported

Android Studio Hedgehog and higher don't support importing Eclipse ADT projects. You can still open these projects, but they are no longer recognized as Android projects. If you need to import this type of project you can use an earlier version of Android Studio. If a given version of Android Studio is unable to import your project, you can try with an even earlier version. Once the project is converted into an Android project using an earlier version of Android Studio, you can use the AGP Upgrade Assistant to work on that project using the latest Android Studio version.

Android Studio Iguana | 2023.2.1

The following are new features in Android Studio Iguana.

Compose UI Check

To help developers build more adaptive and accessible UI in Jetpack Compose, Android Studio Iguana Canary 5 introduced a new UI Check mode in Compose Preview. This feature works similar to Visual linting and Accessibility checks integrations for views. Activate Compose UI check mode for Android Studio to automatically audit your Compose UI and check for adaptive and accessibility issues across different screen sizes, such as text stretched on large screens or low color contrast. The mode highlights issues found in different preview configurations and list them in the problems panel.

Try out this feature today by clicking on the UI Check icon on Compose Preview and send your feedback:

Known issues of UI Check Mode:

  • Selection of issue in the problem panel may lose focus
  • 'Suppress rule' does not work

Progressive Rendering for Compose Preview

Android Studio Iguana Canary 3 introduces Progressive Rendering in Compose Preview. As part of a continual effort to make previews more performant, now for any preview that is out of view, we purposely decrease their render quality to save memory used.

This feature is developed with the goal to further improve the usability of Previews by being able to handle more previews at the same time in a file-try it out today and submit your feedback.

Introducing Studio Bot

Studio Bot is your coding companion for Android development. It's an AI-powered conversational experience in Android Studio that helps you be more productive by answering Android development queries. To learn more, see Meet Studio Bot.

Version control system integration in App Quality Insights

App Quality Insights now lets you navigate from a Crashlytics stack trace to the relevant code—at the point in time when the crash happened. AGP attaches git commit hash data to crash reports to help Android Studio navigate to your code and show how it was in the version where the issue occurred. When you view a crash report in App Quality Insights, you can choose to navigate to the line of code in your current git checkout or view a diff between the current checkout and the version of your codebase that generated the crash.

To integrate your version control system with App Quality Insights, you need the following minimum requirements:

To use version control integration, enable the android.enableVcsInfo flag in the gradle.properties file:

android.enableVcsInfo=true

Now, when you build your app and publish to Google Play, crash reports include the data necessary for the IDE to link to previous versions of your app from the stack trace.

Test against configuration changes with the Espresso Device API

Use the Espresso Device API to test your app when the device undergoes common configuration changes, such as rotation and screen unfolding. The Espresso Device API lets you simulate these configuration changes on a virtual device and executes your tests synchronously, so only one UI action or assertion happens at a time and your test results are more reliable. If you're new to writing UI tests with Espresso, see its documentation.

To use the Espresso Device API, you need the following:

  • Latest Canary version of Android Studio Iguana
  • Latest Alpha version of Android Gradle Plugin 8.3
  • Android Emulator 33.1.10 or higher
  • Android virtual device that runs API level 24 or higher

Set up your project for the Espresso Device API

To set up your project so it supports the Espresso Device API, do the following:

  • To let the test pass commands to the test device, add the INTERNET and ACCESS_NETWORK_STATE permissions to the manifest file in the androidTest source set:

      <uses-permission android:name="android.permission.INTERNET" />
  <uses-permission android:name="android.permissions.ACCESS_NETWORK_STATE" />

  • Enable the enableEmulatorControl experimental flag in the gradle.properties file:

      android.experimental.androidTest.enableEmulatorControl=true

  • Enable the emulatorAccess option in the module-level build script:

    Kotlin

      testOptions {
    emulatorAccess {
      isEnabled = true
    }
  }

    Groovy

      testOptions {
    emulatorAccess {
      enabled true
    }
  }

  • In the module-level build script, import the Espresso Device library into your project:

    Kotlin

      dependencies {
    androidTestImplementation("androidx.test.espresso:espresso-device:1.0.0-alpha05")
  }

    Groovy

      dependencies {
    androidTestImplementation 'androidx.test.espresso:espresso-device:1.0.0-alpha05'
  }

Test against common configuration changes

The Espresso Device API has multiple screen orientation and foldable states that you can use to simulate device configuration changes.

Test against screen rotation

Here's an example of how to test what happens to your app when the device screen rotates:

  1. First, for a consistent starting state set the device to portrait mode:

      import androidx.test.espresso.device.action.ScreenOrientation
  import androidx.test.espresso.device.rules.ScreenOrientationRule
  ...
  @get:Rule
  val screenOrientationRule: ScreenOrientationRule = ScreenOrientationRule(ScreenOrientation.PORTRAIT)

  2. Create a test that sets the device to landscape orientation during test execution:

      @Test
  fun myRotationTest() {
    ...
    // Sets the device to landscape orientation during test execution.
    onDevice().setScreenOrientation(ScreenOrientation.LANDSCAPE)
    ...
  }

  3. After the screen rotates, check that the UI adapts to the new layout as expected.

      @Test
  fun myRotationTest() {
    ...
    // Sets the device to landscape orientation during test execution.
    onDevice().setScreenOrientation(ScreenOrientation.LANDSCAPE)
    composeTestRule.onNodeWithTag("NavRail").assertIsDisplayed()
    composeTestRule.onNodeWithTag("BottomBar").assertDoesNotExist()
  }
Test against screen unfolding

Here's an example of how to test what happens to your app if it's on a foldable device and the screen unfolds:

  1. First, test with the device in the folded state by calling onDevice().setClosedMode(). Make sure that your app's layout adapts to the compact screen width.

      @Test
  fun myUnfoldedTest() {
    onDevice().setClosedMode()
    composeTestRule.onNodeWithTag("BottomBar").assetIsDisplayed()
    composeTestRule.onNodeWithTag("NavRail").assetDoesNotExist()
    ...
  }

  2. To transition to a fully unfolded state, call onDevice().setFlatMode(). Check that the app’s layout adapts to the expanded size class.

      @Test
  fun myUnfoldedTest() {
    onDevice().setClosedMode()
    ...
    onDevice().setFlatMode()
    composeTestRule.onNodeWithTag("NavRail").assertIsDisplayed()
    composeTestRule.onNodeWithTag("BottomBar").assetDoesNotExist()
  }

Specify what devices your tests need

If you're running a test that performs folding actions on a device that isn't foldable, the test will likely fail. To execute only the tests that are relevant to the running device, use the @RequiresDeviceMode annotation. The test runner automatically skips running tests on devices that don't support the configuration being tested. You can add the device requirement rule to each test or an entire test class.

For example, to specify that a test should only be run on devices that support unfolding to a flat configuration, add the following @RequiresDeviceMode code to your test:

@Test
@RequiresDeviceMode(mode = FLAT)
fun myUnfoldedTest() {
  ...
}

Baseline Profiles module wizard

Starting with Android Studio Iguana, you can generate Baseline Profiles for your app using the Baseline Profile Generator template in the new module wizard (File > New > New Module).

This template sets up your project so that it can support Baseline Profiles. It uses the new Baseline Profiles Gradle plugin, which automates the process of setting up your project in the required way with one Gradle task.

The template also creates a run configuration that lets you generate a Baseline Profile with one click from the Select Run/Debug Configuration drop-down list.