Skip to content

Commit 360d99b

Browse files
mannodermausmannodermaus
committed
Update README, recommending new plugin DSL for declaration over legacy DSL
1 parent 1cf5f0b commit 360d99b

File tree

2 files changed

+138
-120
lines changed

2 files changed

+138
-120
lines changed

‎README.md‎

Lines changed: 102 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -3,90 +3,99 @@
33
To update the content of this README, please apply modifications
44
to `README.md.template` instead, and run the `generateReadme` task from Gradle.
55
-->
6+
67
# <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]
78

89
A Gradle plugin that allows for the execution of [JUnit 5][junit5gh] tests in Android environments using **Android Gradle Plugin 4.0.0 or later.**
910

1011
## How?
1112

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] attached to `android.testOptions`.
13+
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.
14+
15+
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].
1316

14-
Instructions on how to write JUnit 5 tests can be found [in their User Guide][junit5ug].
15-
Furthermore, this repository provides a small showcase of the functionality provided by JUnit 5 [here][sampletests].
17+
## Setup
1618

17-
## Download
19+
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].
1820

1921
<details open>
2022
<summary>Kotlin</summary>
2123

22-
```kotlin
23-
buildscript {
24-
dependencies {
25-
classpath("de.mannodermaus.gradle.plugins:android-junit5:1.8.2.1")
26-
}
27-
}
28-
```
24+
```kotlin
25+
plugins {
26+
id("de.mannodermaus.android-junit5") version "1.8.2.1"
27+
}
28+
29+
dependencies {
30+
// (Required) Writing and executing Unit Tests on the JUnit Platform
31+
testImplementation("org.junit.jupiter:junit-jupiter-api:5.8.2")
32+
testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.8.2")
33+
34+
// (Optional) If you need "Parameterized Tests"
35+
testImplementation("org.junit.jupiter:junit-jupiter-params:5.8.2")
36+
37+
// (Optional) If you also have JUnit 4-based tests
38+
testImplementation("junit:junit:4.13.2")
39+
testRuntimeOnly("org.junit.vintage:junit-vintage-engine:5.8.2")
40+
}
41+
```
42+
2943
</details>
3044

3145
<details>
3246
<summary>Groovy</summary>
33-
34-
```groovy
35-
buildscript {
36-
dependencies {
37-
classpath "de.mannodermaus.gradle.plugins:android-junit5:1.8.2.1"
38-
}
39-
}
40-
```
47+
48+
```groovy
49+
plugins {
50+
id("de.mannodermaus.android-junit5").version("1.8.2.1")
51+
}
52+
53+
dependencies {
54+
// (Required) Writing and executing Unit Tests on the JUnit Platform
55+
testImplementation "org.junit.jupiter:junit-jupiter-api:5.8.2"
56+
testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:5.8.2"
57+
58+
// (Optional) If you need "Parameterized Tests"
59+
testImplementation "org.junit.jupiter:junit-jupiter-params:5.8.2"
60+
61+
// (Optional) If you also have JUnit 4-based tests
62+
testImplementation "junit:junit:4.13.2"
63+
testRuntimeOnly "org.junit.vintage:junit-vintage-engine:5.8.2"
64+
}
65+
```
66+
4167
</details>
4268

4369
<br/>
4470

45-
Snapshots of the development version are available through [Sonatype's `snapshots` repository][sonatyperepo].
71+
### Alternative: Legacy DSL
4672

47-
## Setup
48-
<details open>
49-
<summary>Kotlin</summary>
73+
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:
5074

51-
```kotlin
52-
plugins {
53-
id("de.mannodermaus.android-junit5")
54-
}
75+
<details>
76+
<summary>Kotlin</summary>
5577

78+
```kotlin
79+
buildscript {
5680
dependencies {
57-
// (Required) Writing and executing Unit Tests on the JUnit Platform
58-
testImplementation("org.junit.jupiter:junit-jupiter-api:5.8.2")
59-
testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.8.2")
60-
61-
// (Optional) If you need "Parameterized Tests"
62-
testImplementation("org.junit.jupiter:junit-jupiter-params:5.8.2")
63-
64-
// (Optional) If you also have JUnit 4-based tests
65-
testImplementation("junit:junit:4.13.2")
66-
testRuntimeOnly("org.junit.vintage:junit-vintage-engine:5.8.2")
81+
classpath("de.mannodermaus.gradle.plugins:android-junit5:1.8.2.1")
6782
}
68-
```
83+
}
84+
```
85+
6986
</details>
7087

7188
<details>
7289
<summary>Groovy</summary>
7390

74-
```groovy
75-
apply plugin: "de.mannodermaus.android-junit5"
76-
91+
```kotlin
92+
buildscript {
7793
dependencies {
78-
// (Required) Writing and executing Unit Tests on the JUnit Platform
79-
testImplementation "org.junit.jupiter:junit-jupiter-api:5.8.2"
80-
testRuntimeOnly "org.junit.jupiter:junit-jupiter-engine:5.8.2"
81-
82-
// (Optional) If you need "Parameterized Tests"
83-
testImplementation "org.junit.jupiter:junit-jupiter-params:5.8.2"
84-
85-
// (Optional) If you also have JUnit 4-based tests
86-
testImplementation "junit:junit:4.13.2"
87-
testRuntimeOnly "org.junit.vintage:junit-vintage-engine:5.8.2"
94+
classpath "de.mannodermaus.gradle.plugins:android-junit5:1.8.2.1"
8895
}
89-
```
96+
}
97+
```
98+
9099
</details>
91100

92101
<br/>
@@ -96,8 +105,9 @@ More information on Getting Started can be found [on the wiki][wiki-gettingstart
96105
## Requirements
97106

98107
The latest version of this plugin requires:
99-
* Android Gradle Plugin `4.0.0` or above
100-
* Gradle `6.1.1` or above
108+
109+
- Android Gradle Plugin `4.0.0` or above
110+
- Gradle `6.1.1` or above
101111

102112
## Instrumentation Test Support
103113

@@ -122,48 +132,51 @@ To start writing instrumentation tests with JUnit Jupiter, make the following ch
122132
setSourceCompatibility(JavaVersion.VERSION_1_8)
123133
setTargetCompatibility(JavaVersion.VERSION_1_8)
124134
}
125-
}
126-
dependencies {
135+
}
136+
137+
dependencies {
127138
// 4) Jupiter API & Test Runner, if you don't have it already
128139
androidTestImplementation("androidx.test:runner:1.4.0")
129140
androidTestImplementation("org.junit.jupiter:junit-jupiter-api:5.8.2")
130141

131142
// 5) The instrumentation test companion libraries
132143
androidTestImplementation("de.mannodermaus.junit5:android-test-core:1.3.0")
133144
androidTestRuntimeOnly("de.mannodermaus.junit5:android-test-runner:1.3.0")
134-
}
135-
```
145+
}
146+
```
147+
136148
</details>
137149

138150
<details>
139-
<summary>Groovy</summary>
140-
141-
```groovy
142-
android {
143-
defaultConfig {
144-
// 1) Make sure to use the AndroidJUnitRunner, or a subclass of it. This requires a dependency on androidx.test:runner, too!
145-
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
146-
// 2) Connect JUnit 5 to the runner
147-
testInstrumentationRunnerArgument "runnerBuilder", "de.mannodermaus.junit5.AndroidJUnit5Builder"
148-
}
151+
<summary>Groovy</summary>
152+
153+
```groovy
154+
android {
155+
defaultConfig {
156+
// 1) Make sure to use the AndroidJUnitRunner, or a subclass of it. This requires a dependency on androidx.test:runner, too!
157+
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
158+
// 2) Connect JUnit 5 to the runner
159+
testInstrumentationRunnerArgument "runnerBuilder", "de.mannodermaus.junit5.AndroidJUnit5Builder"
160+
}
149161
150-
// 3) Java 8 is required
151-
compileOptions {
152-
sourceCompatibility JavaVersion.VERSION_1_8
153-
targetCompatibility JavaVersion.VERSION_1_8
154-
}
162+
// 3) Java 8 is required
163+
compileOptions {
164+
sourceCompatibility JavaVersion.VERSION_1_8
165+
targetCompatibility JavaVersion.VERSION_1_8
155166
}
167+
}
156168
157-
dependencies {
158-
// 4) Jupiter API & Test Runner, if you don't have it already
159-
androidTestImplementation "androidx.test:runner:1.4.0"
160-
androidTestImplementation "org.junit.jupiter:junit-jupiter-api:5.8.2"
169+
dependencies {
170+
// 4) Jupiter API & Test Runner, if you don't have it already
171+
androidTestImplementation "androidx.test:runner:1.4.0"
172+
androidTestImplementation "org.junit.jupiter:junit-jupiter-api:5.8.2"
173+
174+
// 5) The instrumentation test companion libraries
175+
androidTestImplementation "de.mannodermaus.junit5:android-test-core:1.3.0"
176+
androidTestRuntimeOnly "de.mannodermaus.junit5:android-test-runner:1.3.0"
177+
}
178+
````
161179
162-
// 5) The instrumentation test companion libraries
163-
androidTestImplementation "de.mannodermaus.junit5:android-test-core:1.3.0"
164-
androidTestRuntimeOnly "de.mannodermaus.junit5:android-test-runner:1.3.0"
165-
}
166-
```
167180
</details>
168181
169182
The `android-test-core` artifact includes an extension point for the `ActivityScenario` API; more information on that can be found in the wiki.
@@ -203,10 +216,10 @@ limitations under the License.
203216
204217
See also the [full License text](LICENSE).
205218
206-
[junit5gh]: https://github.com/junit-team/junit5
207-
[junit5ug]: https://junit.org/junit5/docs/current/user-guide
208-
[circleci]: https://circleci.com/gh/mannodermaus/android-junit5
209-
[sonatyperepo]: https://oss.sonatype.org/content/repositories/snapshots
210-
[sampletests]: instrumentation/sample
211-
[wiki-dsl]: https://github.com/mannodermaus/android-junit5/wiki/Configuration-DSL
212-
[wiki-gettingstarted]: https://github.com/mannodermaus/android-junit5/wiki/Getting-Started
219+
[junit5gh]: https://github.com/junit-team/junit5
220+
[junit5ug]: https://junit.org/junit5/docs/current/user-guide
221+
[circleci]: https://circleci.com/gh/mannodermaus/android-junit5
222+
[sonatyperepo]: https://oss.sonatype.org/content/repositories/snapshots
223+
[sampletests]: instrumentation/sample
224+
[wiki-dsl]: https://github.com/mannodermaus/android-junit5/wiki/Configuration-DSL
225+
[wiki-gettingstarted]: https://github.com/mannodermaus/android-junit5/wiki/Getting-Started

‎README.md.template‎

Lines changed: 36 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -8,43 +8,16 @@ This plugin configures the unit test tasks for each build variant of a project t
88

99
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].
1010

11-
## Download
12-
13-
<details open>
14-
<summary>Kotlin</summary>
15-
16-
```kotlin
17-
buildscript {
18-
dependencies {
19-
classpath("de.mannodermaus.gradle.plugins:android-junit5:${pluginVersion}")
20-
}
21-
}
22-
```
23-
</details>
24-
25-
<details>
26-
<summary>Groovy</summary>
27-
28-
```groovy
29-
buildscript {
30-
dependencies {
31-
classpath "de.mannodermaus.gradle.plugins:android-junit5:${pluginVersion}"
32-
}
33-
}
34-
```
35-
</details>
36-
37-
<br/>
11+
## Setup
3812

39-
Snapshots of the development version are available through [Sonatype's `snapshots` repository][sonatyperepo].
13+
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].
4014

41-
## Setup
4215
<details open>
4316
<summary>Kotlin</summary>
4417

4518
```kotlin
4619
plugins {
47-
id("de.mannodermaus.android-junit5")
20+
id("de.mannodermaus.android-junit5") version "${pluginVersion}"
4821
}
4922

5023
dependencies {
@@ -66,7 +39,9 @@ Snapshots of the development version are available through [Sonatype's `snapshot
6639
<summary>Groovy</summary>
6740

6841
```groovy
69-
apply plugin: "de.mannodermaus.android-junit5"
42+
plugins {
43+
id("de.mannodermaus.android-junit5").version("${pluginVersion}")
44+
}
7045

7146
dependencies {
7247
// (Required) Writing and executing Unit Tests on the JUnit Platform
@@ -85,6 +60,36 @@ Snapshots of the development version are available through [Sonatype's `snapshot
8560

8661
<br/>
8762

63+
### Alternative: Legacy DSL
64+
65+
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:
66+
67+
<details>
68+
<summary>Kotlin</summary>
69+
70+
```kotlin
71+
buildscript {
72+
dependencies {
73+
classpath("de.mannodermaus.gradle.plugins:android-junit5:${pluginVersion}")
74+
}
75+
}
76+
```
77+
</details>
78+
79+
<details>
80+
<summary>Groovy</summary>
81+
82+
```kotlin
83+
buildscript {
84+
dependencies {
85+
classpath "de.mannodermaus.gradle.plugins:android-junit5:${pluginVersion}"
86+
}
87+
}
88+
```
89+
</details>
90+
91+
<br/>
92+
8893
More information on Getting Started can be found [on the wiki][wiki-gettingstarted].
8994

9095
## Requirements

0 commit comments

Comments
 (0)