Skip to content

Commit 33b32a6

Browse files
mannodermausmannodermaus
committed
Hook up readme generation to version catalog
1 parent f812302 commit 33b32a6

3 files changed

Lines changed: 150 additions & 197 deletions

File tree

‎README.md‎

Lines changed: 69 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -5,37 +5,41 @@
55
-->
66
# <img src=".images/logo.png" align="right" width="100">android-junit5 [![CircleCI](https://circleci.com/gh/mannodermaus/android-junit5/tree/main.svg?style=svg)][circleci]
77

8-
A Gradle plugin that allows for the execution of [JUnit 5][junit5gh] tests in Android environments using **Android Gradle Plugin 8.2 or later.**
8+
A Gradle plugin that allows for the execution of [JUnit Framework][junit-framework-github] tests in Android environments using **Android Gradle Plugin 8.2 or later.**
99

1010
## How?
1111

12-
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 of JUnit 5 for instrumentation tests.
12+
This plugin configures the unit test tasks for each build variant of a project to run on the JUnit Platform.
13+
Furthermore, it provides additional configuration options for these tests [through a DSL][wiki-dsl]
14+
and facilitates the usage of JUnit Framework for instrumentation tests.
1315

14-
Instructions on how to write tests with the JUnit 5 framework can be found [in their User Guide][junit5ug]. To get a first look at its features, a small showcase project can be found [here][sampletests].
16+
Instructions on how to write tests with the JUnit Framework can be found [in their User Guide][junit-framework-guide].
17+
To get a first look at its features, a small showcase project can be found [here][sampletests].
1518

1619
## Setup
1720

18-
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].
21+
To get started, declare the plugin in your `app` module's build script alongside the latest version.
22+
Snapshots of the development version are available through [Sonatype's `snapshots` repository][sonatyperepo].
1923

2024
<details open>
2125
<summary>Kotlin</summary>
2226

2327
```kotlin
2428
plugins {
29+
// 1. Apply the plugin
2530
id("de.mannodermaus.android-junit5") version "1.14.0.0"
2631
}
2732

2833
dependencies {
29-
// (Required) Writing and executing Unit Tests on the JUnit Platform
30-
testImplementation("org.junit.jupiter:junit-jupiter-api:5.14.0")
31-
testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.14.0")
34+
// 2. Add JUnit Framework BOM and the required dependencies
35+
testImplementation(platform("org.junit:junit-bom:5.14.1"))
36+
testImplementation("org.junit.jupiter:junit-jupiter-api")
37+
testImplementation("org.junit.jupiter:junit-jupiter-params")
38+
testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine")
3239

33-
// (Optional) If you need "Parameterized Tests"
34-
testImplementation("org.junit.jupiter:junit-jupiter-params:5.14.0")
35-
36-
// (Optional) If you also have JUnit 4-based tests
40+
// 3. Add JUnit Vintage if you also have JUnit 4 tests (e.g. Robolectric)
3741
testImplementation("junit:junit:4.13.2")
38-
testRuntimeOnly("org.junit.vintage:junit-vintage-engine:5.14.0")
42+
testRuntimeOnly("org.junit.vintage:junit-vintage-engine")
3943
}
4044
```
4145
</details>
@@ -45,86 +49,56 @@ To get started, declare the plugin in your `app` module's build script alongside
4549

4650
```groovy
4751
plugins {
52+
// 1. Apply the plugin
4853
id "de.mannodermaus.android-junit5" version "1.14.0.0"
4954
}
5055
5156
dependencies {
52-
// (Required) Writing and executing Unit Tests on the JUnit Platform
53-
testImplementation "org.junit.jupiter:junit-jupiter-api:5.14.0"
54-
testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:5.14.0"
55-
56-
// (Optional) If you need "Parameterized Tests"
57-
testImplementation "org.junit.jupiter:junit-jupiter-params:5.14.0"
57+
// 2. Add JUnit Framework BOM and the required dependencies
58+
testImplementation platform("org.junit:junit-bom:5.14.1")
59+
testImplementation "org.junit.jupiter:junit-jupiter-api"
60+
testImplementation "org.junit.jupiter:junit-jupiter-params"
61+
testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine"
5862
59-
// (Optional) If you also have JUnit 4-based tests
63+
// 3. Add JUnit Vintage if you also have JUnit 4 tests (e.g. Robolectric)
6064
testImplementation "junit:junit:4.13.2"
61-
testRuntimeOnly "org.junit.vintage:junit-vintage-engine:5.14.0"
65+
testRuntimeOnly "org.junit.vintage:junit-vintage-engine"
6266
}
6367
```
6468
</details>
6569

6670
<br/>
6771

68-
### Alternative: Legacy DSL
69-
70-
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:
71-
72-
<details>
73-
<summary>Kotlin</summary>
74-
75-
```kotlin
76-
// In the root project's build.gradle.kts:
77-
buildscript {
78-
dependencies {
79-
classpath("de.mannodermaus.gradle.plugins:android-junit5:1.14.0.0")
80-
}
81-
}
82-
83-
// In the app module's build.gradle.kts:
84-
plugins {
85-
id("de.mannodermaus.android-junit5")
86-
}
87-
```
88-
</details>
89-
90-
<details>
91-
<summary>Groovy</summary>
92-
93-
```groovy
94-
// In the root project's build.gradle:
95-
buildscript {
96-
dependencies {
97-
classpath "de.mannodermaus.gradle.plugins:android-junit5:1.14.0.0"
98-
}
99-
}
100-
101-
// In the app module's build.gradle:
102-
apply plugin: "de.mannodermaus.android-junit5"
103-
```
104-
</details>
105-
106-
<br/>
107-
10872
More information on Getting Started can be found [on the wiki][wiki-gettingstarted].
10973

11074
## Requirements
11175

112-
The latest version of this plugin requires:
113-
* Android Gradle Plugin `8.2` or above
114-
* Gradle `8.2` or above
76+
The latest version of this plugin requires at least:
77+
* Android Gradle Plugin `8.2`
78+
* Gradle `8.2`
11579

11680
## Instrumentation Test Support
11781

118-
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".
82+
You can also write instrumentation tests with new JUnit APIs and execute them on emulators and physical devices.
83+
Depending on the Java requirements of the JUnit Framework version, these instrumentation tests will only run on devices
84+
that meet these requirements, however. These tests are ignored and their execution will be skipped on older devices.
11985

120-
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:
86+
- JUnit 5 requires Java 8 and is only supported by devices running Android 8.0 (API 26) or newer
87+
- JUnit 6 requires Java 17 and is only supported by devices running Android 15 (API 35) or newer
88+
89+
Before you can write instrumentation tests with JUnit Jupiter,
90+
make sure that your module is using the `androidx.test.runner.AndroidJUnitRunner`
91+
(or a subclass of it) as its `testInstrumentationRunner`. Then, simply add a dependency on JUnit Jupiter API
92+
to the `androidTestImplementation` configuration in your build script and the plugin will
93+
automatically configure JUnit 5 tests for you:
12194

12295
<details open>
12396
<summary>Kotlin</summary>
12497

12598
```kotlin
12699
dependencies {
127-
androidTestImplementation("org.junit.jupiter:junit-jupiter-api:5.14.0")
100+
androidTestImplementation(platform("org.junit:junit-bom:5.14.1"))
101+
androidTestImplementation("org.junit.jupiter:junit-jupiter-api")
128102
}
129103
```
130104
</details>
@@ -134,17 +108,18 @@ Before you can write instrumentation tests with JUnit Jupiter, make sure that yo
134108

135109
```groovy
136110
dependencies {
137-
androidTestImplementation "org.junit.jupiter:junit-jupiter-api:5.14.0"
111+
androidTestImplementation platform("org.junit:junit-bom:5.14.1")
112+
androidTestImplementation "org.junit.jupiter:junit-jupiter-api"
138113
}
139114
```
140115
</details>
141116

142-
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][wiki-home] for more info.
117+
By enabling JUnit Framework for instrumentation tests, you will gain access to `ActivityScenarioExtension` among other things,
118+
which helps with the orchestration of `Activity` classes. Check [the wiki][wiki-home] for more info.
143119

144120
### Extensions
145121

146-
An optional artifact with more helper extensions is available for specific use cases.
147-
It contains the following APIs:
122+
An optional artifact with `extensions` is available for specific use cases. It contains the following APIs:
148123

149124
- `GrantPermissionExtension` for granting permissions before each test
150125

@@ -172,15 +147,17 @@ Can you think of more? Let's discuss in the issues section!
172147

173148
### Jetpack Compose
174149

175-
To test `@Composable` functions on device with JUnit 5, first enable support for instrumentation tests as described above.
176-
Then, add the Compose test dependency to your `androidTestImplementation` configuration
177-
and the plugin will autoconfigure JUnit 5 Compose support for you!
150+
To test `@Composable` functions on devices compatible with the JUnit Framework,
151+
enable support for instrumentation tests as described above. Then add the Compose test dependency
152+
to your `androidTestImplementation` configuration and the plugin will autoconfigure JUnit 5 Compose support for you.
178153

179154
<details open>
180155
<summary>Kotlin</summary>
181156

182157
```kotlin
183158
dependencies {
159+
// Setup from the previous section for enabling instrumentation tests...
160+
184161
// Compose test framework
185162
androidTestImplementation("androidx.compose.ui:ui-test-android:$compose_version")
186163

@@ -195,6 +172,8 @@ and the plugin will autoconfigure JUnit 5 Compose support for you!
195172

196173
```groovy
197174
dependencies {
175+
// Setup from the previous section for enabling instrumentation tests...
176+
198177
// Compose test framework
199178
androidTestImplementation "androidx.compose.ui:ui-test-android:$compose_version"
200179
@@ -204,7 +183,7 @@ and the plugin will autoconfigure JUnit 5 Compose support for you!
204183
```
205184
</details>
206185

207-
[The wiki][wiki-home] includes a section on how to test your Composables with JUnit 5.
186+
[The wiki][wiki-home] includes a section on how to test your Composables.
208187

209188
### Override the version of instrumentation test libraries
210189

@@ -233,15 +212,17 @@ when it sets up the artifacts automatically. However, it is possible to choose a
233212

234213
## Official Support
235214

236-
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:
215+
At this time, Google hasn't shared any immediate plans to bring first-party support for anything beyond JUnit 4 to Android.
216+
The following list is an aggregation of pending feature requests:
237217

238218
- [InstantTaskExecutorRule uses @RestrictTo(RestrictTo.Scope.LIBRARY_GROUP) -- why? (issuetracker.google.com)](https://issuetracker.google.com/u/0/issues/79189568)
239219
- [Add support for JUnit 5 (issuetracker.google.com)](https://issuetracker.google.com/issues/127100532)
240220
- [JUnit 5 support (github.com/android/android-test)](https://github.com/android/android-test/issues/224)
241221

242222
## Support for @Rules
243223

244-
Since JUnit 5 has replaced the `@Rule` mechanism with Extensions, the following artifacts help bridge the gap until Android officially transitions to JUnit 5.
224+
Since the JUnit Framework has replaced the `@Rule` mechanism with the concept of an `Extension`,
225+
the following artifacts help bridge the gap until Android officially transitions, if ever.
245226

246227
### InstantExecutorExtension
247228

@@ -252,7 +233,7 @@ Replaces `InstantTaskExecutorRule` in JUnit 5.
252233

253234
```kotlin
254235
dependencies {
255-
testImplementation("io.github.neboskreb:instant-task-executor-extension:1.0.0")
236+
testImplementation("io.github.neboskreb:instant-task-executor-extension:1.0.0")
256237
}
257238
```
258239
</details>
@@ -262,7 +243,7 @@ Replaces `InstantTaskExecutorRule` in JUnit 5.
262243

263244
```groovy
264245
dependencies {
265-
testImplementation 'io.github.neboskreb:instant-task-executor-extension:1.0.0'
246+
testImplementation 'io.github.neboskreb:instant-task-executor-extension:1.0.0'
266247
}
267248
```
268249
</details>
@@ -271,19 +252,20 @@ For more details see [instant-task-executor-extension](https://github.com/nebosk
271252

272253
## Building Locally
273254

274-
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.
255+
This repository contains multiple modules, divided into two sub-projects.
256+
The repository's root directory contains build logic shared across the sub-projects,
257+
which in turn use symlinks to connect to the common build scripts in their parent folder.
275258

276-
- `instrumentation`: The root folder for Android-based modules, namely the instrumentation libraries & a sample application. After cloning, open this project in Android Studio.
277-
- `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.
259+
- `instrumentation`: The root folder for the instrumentation libraries & a sample. Open this folder in Android Studio.
260+
- `plugin`: The root folder for the Gradle plugin. Open this folder in IntelliJ IDEA.
278261

279262
## Plugin Compatibility Map
280263

281264
For users that cannot match the current minimum version requirement of the Android Gradle Plugin requested by this plugin,
282-
refer to the table below to find a suitable alternative version. Note that **no active development will go into these
283-
legacy versions**, so please consider upgrading to at least Android Gradle Plugin 8.2
284-
before filing an issue with the latest one.
265+
refer to the table below to find a suitable alternative version. Note that **no active development will go into legacy versions**,
266+
so please consider upgrading to at least AGP 8.2 before filing an issue with the latest one.
285267

286-
|Your AGP Version|Suggested JUnit5 Plugin Version|
268+
|Your AGP Version|Suggested Plugin Version|
287269
|---|---|
288270
|`>= 8.2.0`|`1.14.0.0`|
289271
|`8.0.0` - `8.1.4`|`1.12.2.0`|
@@ -312,8 +294,8 @@ limitations under the License.
312294

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

315-
[junit5gh]: https://github.com/junit-team/junit5
316-
[junit5ug]: https://junit.org/junit5/docs/current/user-guide
297+
[junit-framework-github]: https://github.com/junit-team/junit-framework
298+
[junit-framework-guide]: https://docs.junit.org
317299
[circleci]: https://circleci.com/gh/mannodermaus/android-junit5
318300
[sonatyperepo]: https://central.sonatype.com/repository/maven-snapshots
319301
[sampletests]: instrumentation/sample

0 commit comments

Comments
 (0)