Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mannodermaus/android-junit-framework

Modern testing with JUnit for Android.
https://github.com/mannodermaus/android-junit-framework

android gradle-plugin junit junit5 unittesting

Last synced: 16 days ago
JSON representation

Modern testing with JUnit for Android.

Awesome Lists containing this project

README 

          




  

    

    

    Android JUnit

  




[![CircleCI](https://circleci.com/gh/mannodermaus/android-junit-framework/tree/main.svg?style=svg)][circleci]



A Gradle plugin that allows for the execution of [JUnit][junit-github] 5+ tests in Android environments using **Android Gradle Plugin 8.2 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][wiki-dsl]

and facilitates the usage JUnit for instrumentation tests.



Instructions on how to write tests with modern JUnit can be found [in their User Guide][junit-guide].

To get a first look at its features, a small showcase project can be found [here][sampletests].



## 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][sonatyperepo].



```kotlin

plugins {

    // 1. Apply the plugin

    id("de.mannodermaus.android-junit") version "2.0.0"

}



dependencies {

    // 2. Add JUnit BOM and the required dependencies

    testImplementation(platform("org.junit:junit-bom:5.14.1"))

    testImplementation("org.junit.jupiter:junit-jupiter-api")

    testImplementation("org.junit.jupiter:junit-jupiter-params")

    testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine")



    // 3. Add JUnit Vintage if you also have JUnit 4 tests (e.g. for Robolectric)

    testImplementation("junit:junit:4.13.2")

    testRuntimeOnly("org.junit.vintage:junit-vintage-engine")

}

```



More information on Getting Started can be found [on the wiki][wiki-gettingstarted].



## Requirements



The latest version of this plugin requires at least:

* Android Gradle Plugin `8.2`

* Gradle `8.2`



## Instrumentation Test Support



You can also write instrumentation tests with new JUnit APIs and execute them on emulators and physical devices.

Depending on the Java requirements of the JUnit version, these instrumentation tests will only run on devices

that meet these requirements, however. On older devices, an exception will be raised at runtime.



- JUnit 5 requires Java 8; devices require at least Android 8.0 (API 26)

- JUnit 6 requires Java 17; devices require at least Android 15 (API 35)



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

dependencies {

    androidTestImplementation(platform("org.junit:junit-bom:5.14.1"))

    androidTestImplementation("org.junit.jupiter:junit-jupiter-api")

}

```



By enabling JUnit for instrumentation tests, you will gain access to `ActivityScenarioExtension` among other things,

which helps with the orchestration of `Activity` classes. Check [the wiki][wiki-home] for more info.



### Ignoring older devices



Historically, tests were ignored if the Android device running them did not meet the requirements of JUnit.

This was changed in the 2.0.0 of the plugin & library, but if you want to restore the previous behavior,

you can do so via the `junitPlatform` DSL.



```kotlin

junitPlatform {

    instrumentationTests.behaviorForUnsupportedDevices = UnsupportedDeviceBehavior.Skip

}

```



### Extensions



An optional artifact with `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

junitPlatform {

    instrumentationTests.includeExtensions = true

}

```



### Jetpack Compose



To test `@Composable` functions on devices compatible with modern JUnit,

enable support for instrumentation tests as described above. Then add the Compose test dependency

to your `androidTestImplementation` configuration and the plugin will autoconfigure JUnit 5 Compose support for you.



```kotlin

dependencies {

    // Setup from the previous section for enabling instrumentation tests...



    // Compose test framework

    androidTestImplementation("androidx.compose.ui:ui-test-android:$compose_version")



    // Needed for createComposeExtension() and createAndroidComposeExtension()

    debugImplementation("androidx.compose.ui:ui-test-manifest:$compose_version")

}

```



[The wiki][wiki-home] includes a section on how to test your Composables.



### Override the version of instrumentation test libraries



By default, the plugin will make sure to use a compatible version of the instrumentation test libraries

when it sets up the artifacts automatically. However, it is possible to choose a custom version instead via its DSL:



```kotlin

junitPlatform {

    instrumentationTests.version = "2.0.0"

}

```



## Official Support



At this time, Google hasn't shared any immediate plans to bring first-party support for anything beyond JUnit 4 to Android.

The following list is an aggregation of pending feature requests:



- [InstantTaskExecutorRule uses @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) -- why? (issuetracker.google.com)](https://issuetracker.google.com/u/0/issues/79189568)

- [Add support for JUnit 5 (issuetracker.google.com)](https://issuetracker.google.com/issues/127100532)

- [JUnit 5 support (github.com/android/android-test)](https://github.com/android/android-test/issues/224)



## Support for @Rules



Since JUnit has replaced the `@Rule` mechanism with the concept of an `Extension` in version 5,

the following artifacts help bridge the gap until Android officially transitions, if ever.



### InstantExecutorExtension



Replaces `InstantTaskExecutorRule` in JUnit 5.



```kotlin

dependencies {

    testImplementation("io.github.neboskreb:instant-task-executor-extension:1.0.0")

}

```



For more details see [instant-task-executor-extension](https://github.com/neboskreb/instant-task-executor-extension) on GitHub.



## 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 the instrumentation libraries & a sample. Open this folder in Android Studio.

- `plugin`: The root folder for the Gradle plugin. Open this folder in IntelliJ IDEA.



## Plugin Compatibility Map



For users that cannot match the current minimum version requirement of the Android Gradle Plugin requested by this plugin,

refer to the table below to find a suitable alternative version. Note that **no active development will go into legacy versions**,

so please consider upgrading to at least AGP 8.2 before filing an issue with the latest one.



|Your AGP Version|Suggested Plugin Version|

|---|---|

|`>= 8.2.0`|`2.0.0`|

|`8.0.0` - `8.1.4`|`1.12.2.0`|

|`7.0.0` - `7.4.2`|`1.10.0.0`|

|`4.0.0` - `4.2.2`|`1.8.2.1`|

|`3.5.0` - `3.6.4`|`1.7.1.1`|

|`< 3.5.0`|none; you should **really** update your build env, bro|



## License



```

Copyright 2017-2026 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.

```



See also the [full License text](LICENSE).



 [junit-github]: https://github.com/junit-team/junit-framework

 [junit-guide]: https://docs.junit.org

 [circleci]: https://circleci.com/gh/mannodermaus/android-junit-framework

 [sonatyperepo]: https://central.sonatype.com/repository/maven-snapshots

 [sampletests]: instrumentation/sample

 [wiki-home]: https://github.com/mannodermaus/android-junit-framework/wiki

 [wiki-dsl]: https://github.com/mannodermaus/android-junit-framework/wiki/Configuration

 [wiki-gettingstarted]: https://github.com/mannodermaus/android-junit-framework/wiki/Getting-Started