android-junit5

Project Url: mannodermaus/android-junit5

Introduction: Testing with JUnit 5 for Android.

Tags:

A Gradle plugin that allows for the execution of JUnit 5 tests in Android environments using Android Gradle Plugin 7.0.0 or later.

How?

This plugin configures the unit test tasks for each build variant of a project to run on the JUnit Platform. Furthermore, it provides additional configuration options for these tests through a DSL and facilitates the usage of JUnit 5 for instrumentation tests.

Instructions on how to write tests with the JUnit 5 framework can be found in their User Guide. To get a first look at its features, a small showcase project can be found here.

Setup

To get started, declare the plugin in your app module's build script alongside the latest version. Snapshots of the development version are available through Sonatype's snapshots repository.

Kotlin

kotlin
  plugins {
    id("de.mannodermaus.android-junit5") version "1.10.0.0"
  }

  dependencies {
    // (Required) Writing and executing Unit Tests on the JUnit Platform
    testImplementation("org.junit.jupiter:junit-jupiter-api:5.10.0")
    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.10.0")

    // (Optional) If you need "Parameterized Tests"
    testImplementation("org.junit.jupiter:junit-jupiter-params:5.10.0")

    // (Optional) If you also have JUnit 4-based tests
    testImplementation("junit:junit:4.13.2")
    testRuntimeOnly("org.junit.vintage:junit-vintage-engine:5.10.0")
  }

Groovy

groovy
  plugins {
    id "de.mannodermaus.android-junit5" version "1.10.0.0"
  }

  dependencies {
    // (Required) Writing and executing Unit Tests on the JUnit Platform
    testImplementation "org.junit.jupiter:junit-jupiter-api:5.10.0"
    testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:5.10.0"

    // (Optional) If you need "Parameterized Tests"
    testImplementation "org.junit.jupiter:junit-jupiter-params:5.10.0"

    // (Optional) If you also have JUnit 4-based tests
    testImplementation "junit:junit:4.13.2"
    testRuntimeOnly "org.junit.vintage:junit-vintage-engine:5.10.0"
  }

Alternative: Legacy DSL

If you prefer to use the legacy way to declare the dependency instead, remove the version() block from above and declare the plugin in your root project's build script like so:

Kotlin

kotlin
  // In the root project's build.gradle.kts:
  buildscript {
    dependencies {
      classpath("de.mannodermaus.gradle.plugins:android-junit5:1.10.0.0")
    }
  }

  // In the app module's build.gradle.kts:
  plugins {
    id("de.mannodermaus.android-junit5")
  }

Groovy

groovy
  // In the root project's build.gradle:
  buildscript {
    dependencies {
      classpath "de.mannodermaus.gradle.plugins:android-junit5:1.10.0.0"
    }
  }

  // In the app module's build.gradle:
  apply plugin: "de.mannodermaus.android-junit5"

More information on Getting Started can be found on the wiki.

Requirements

The latest version of this plugin requires:

Android Gradle Plugin 7.0.0 or above
Gradle 7.0 or above

Instrumentation Test Support

You can use JUnit 5 to run instrumentation tests on emulators and physical devices, too. Because the framework is built on Java 8 from the ground up, these instrumentation tests will only run on devices running Android 8.0 (API 26) or newer – older phones will skip the execution of these tests completely, marking them as "ignored".

Before you can write instrumentation tests with JUnit Jupiter, make sure that your module is using the androidx.test.runner.AndroidJUnitRunner (or a subclass of it) as its testInstrumentationRunner. Then, simply add a dependency on junit-jupiter-api to the androidTestImplementation configuration in your build script and the plugin will automatically configure JUnit 5 tests for you:

Kotlin

kotlin
  dependencies {
    androidTestImplementation("org.junit.jupiter:junit-jupiter-api:5.10.0")
  }

Groovy

groovy
  dependencies {
    androidTestImplementation "org.junit.jupiter:junit-jupiter-api:5.10.0"
  }

By enabling JUnit 5 for instrumentation tests, you will gain access to ActivityScenarioExtension (among other things), which helps with the orchestration of Activity classes. Check the wiki for more info.

Extensions

An optional artifact with more helper extensions is available for specific use cases. It contains the following APIs:

GrantPermissionExtension for granting permissions before each test

Can you think of more? Let's discuss in the issues section!

Kotlin

kotlin
  dependencies {
    androidTestImplementation("de.mannodermaus.junit5:android-test-extensions:1.4.0")
  }

Groovy

groovy
  dependencies {
    androidTestImplementation "de.mannodermaus.junit5:android-test-extensions:1.4.0"
  }

Jetpack Compose

To test @Composable functions on device with JUnit 5, first enable support for instrumentation tests as described above. Then, add the integration library for Jetpack Compose to the androidTestImplementation configuration:

Kotlin

kotlin
  dependencies {
    // Test extension & transitive dependencies
    androidTestImplementation("de.mannodermaus.junit5:android-test-compose:1.4.0")

    // Needed for createComposeExtension() and createAndroidComposeExtension()
    debugImplementation("androidx.compose.ui:ui-test-manifest:$compose_version")
  }

Groovy

groovy
  dependencies {
    // Test extension & transitive dependencies
    androidTestImplementation "de.mannodermaus.junit5:android-test-compose:1.4.0"

    // Needed for createComposeExtension() and createAndroidComposeExtension()
    debugImplementation "androidx.compose.ui:ui-test-manifest:$compose_version"
  }

The wiki includes a section on how to test your Composables with JUnit 5.

Official Support

At this time, Google hasn't shared any immediate plans to bring first-party support for JUnit 5 to Android. The following list is an aggregation of pending feature requests:

Building Locally

This repository contains multiple modules, divided into two sub-projects. The repository's root directory contains build logic shared across the sub-projects, which in turn use symlinks to connect to the common build scripts in their parent folder.

instrumentation: The root folder for Android-based modules, namely the instrumentation libraries & a sample application. After cloning, open this project in Android Studio.
plugin: The root folder for Java-based modules, namely the Gradle plugin for JUnit 5 on Android, as well as its test module. After cloning, open this project in IntelliJ IDEA.

License

Copyright 2017-2024 Marcel Schnelle

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.