Skip to content

Commit

Permalink
Update README (#90)
Browse files Browse the repository at this point in the history
  • Loading branch information
@eed3si9n
eed3si9n authored Jul 29, 2024
1 parent c7bb69f commit 075428c
Showing 1 changed file with 48 additions and 43 deletions.
91 changes: 48 additions & 43 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,60 +5,56 @@ Jupiter Interface
[![License](https://img.shields.io/hexpm/l/plug.svg)](https://raw.githubusercontent.com/sbt/sbt-jupiter-interface/main/LICENSE)
![Sonatype Nexus (Releases)](https://img.shields.io/nexus/r/com.github.sbt.junit/jupiter-interface?server=https%3A%2F%2Foss.sonatype.org)

An implementation of [SBT's test interface](https://github.com/sbt/test-interface) for [JUnit Jupiter](http://junit.org/junit5). This allows you to run JUnit 5 tests from [SBT](http://www.scala-sbt.org/).
An implementation of [sbt's test interface](https://github.com/sbt/test-interface) for [JUnit Jupiter](http://junit.org/junit5). This allows you to run JUnit 5 tests from [sbt](http://www.scala-sbt.org/).

The code is split into a runtime library `jupiter-interface` and an SBT plugin `sbt-jupiter-interface`. The runtime library is written in pure Java and does all the heavy lifting like collecting and running tests. The SBT plugin makes the runtime library available to the SBT build by adding it to `sbt.Keys.testFrameworks`. It also overwrites `sbt.Keys.detectTests` with a custom task that uses JUnits discovery mechanism to collect available tests. This step is necessary since SBT is currently not capable of detecting package private test classes.
The code is split into:

## Usage
* `jupiter-interface`: a pure Java runtime library. The runtime library is written in pure Java and does all the heavy lifting like collecting and running tests.
* `sbt-jupiter-interface`: sbt plugin. The sbt plugin makes the runtime library available to the sbt build by adding it to `sbt.Keys.testFrameworks`. It also overwrites `sbt.Keys.detectTests` with a custom task that uses JUnits discovery mechanism to collect available tests. This step is necessary since sbt is currently not capable of detecting package private test classes.

Add the following line to `./project/plugins.sbt`. See the section [Using Plugins](http://www.scala-sbt.org/release/docs/Using-Plugins.html) in the sbt wiki for more information.
## Usage

addSbtPlugin("com.github.sbt.junit" % "sbt-jupiter-interface" % "0.11.1")
![Sonatype Nexus (Releases)](https://img.shields.io/nexus/r/com.github.sbt.junit/jupiter-interface?server=https%3A%2F%2Foss.sonatype.org)

Additionally a test dependency to this plugins runtime library `jupiter-interface` is required for every module which wants to run `JUnit 5` tests:
Add the following line to `./project/plugins.sbt`:

libraryDependencies ++= Seq(
"com.github.sbt.junit" % "jupiter-interface" % JupiterKeys.jupiterVersion.value % Test
)
```scala
addSbtPlugin("com.github.sbt.junit" % "sbt-jupiter-interface" % "x.y.z")
```

Note that if you want to restore default behaviour like in versions before `0.8.0` you can globally activate this plugin by adding the runtime dependency to `ThisScope` of the root project.
**Note**: We changed the organization from `"net.aichler"` to `"com.github.sbt.junit"` starting 0.11.3.

ThisBuild / libraryDependencies += "com.github.sbt.junit" % "jupiter-interface" % "0.11.1" % Test
Additionally a `Test` dependency to the runtime library `jupiter-interface` is required for every module which wants to run JUnit 5 tests:

### Integration Testing
```scala
libraryDependencies ++= Seq(
"com.github.sbt.junit" % "jupiter-interface" % JupiterKeys.jupiterVersion.value % Test
)
```

Basic configuration of a project to have `it:test` is [documented in SBT](https://www.scala-sbt.org/0.13/docs/Testing.html#Integration+Tests). For `Jupiter Interface` to work, you will also need to install plugin specific settings and tasks to the `it` configuration, as follows:
Note: If you want to restore default behaviour like in versions before `0.8.0` you can globally activate this plugin by adding the runtime dependency to `ThisBuild / libraryDependencies`:

```scala
ThisBuild / libraryDependencies += "com.github.sbt.junit" % "jupiter-interface" % JupiterKeys.jupiterVersion.value % Test
```
lazy val root = project.in(file("."))
.configs(IntegrationTest)
.settings(Defaults.itSettings: _*)
.settings(inConfig(IntegrationTest)(JupiterPlugin.scopedSettings): _*)
...
```
Don’t forget to mark test dependencies as `test,it` if you have both unit and integration tests.

## Releases

**Note** that unfortunately artifacts which were hosted at `Bintray` are no longer available since
the service has been discontinued. This includes releases up to and including `0.8.4`. Starting with
`0.9.0` artifacts are published on `Maven Central` through `Sonatype`.

Since version `0.6.0` this plugin is cross built for `scala_2.10/sbt_0.13` and `scala_2.12/sbt_1.0`.

SBT Plugin | JUnit Platform | JUnit Engine
sbt Plugin | JUnit Platform | JUnit Engine
:----------------|:---------------|:-------------
0.1.x | 1.0.0-M4 | 5.0.0-M4
0.2.x | 1.0.0-M5 | 5.0.0-M5
0.3.x | 1.0.0-M6 | 5.0.0-M6
0.4.x | 1.0.0-RC2 | 5.0.0-RC2
0.5.x | 1.0.0 | 5.0.0
0.6.x | 1.0.0 | 5.0.0
0.7.x | 1.1.0 | 5.1.0
0.8.x | 1.1.x | 5.1.x
0.9.x | 1.7.x | 5.7.x
0.10.x | 1.8.x | 5.8.x
0.11.x | 1.9.x | 5.9.x
0.10.x | 1.8.x | 5.8.x
0.9.x | 1.7.x | 5.7.x
0.8.x | 1.1.x | 5.1.x
0.7.x | 1.1.0 | 5.1.0
0.6.x | 1.0.0 | 5.0.0
0.5.x | 1.0.0 | 5.0.0
0.4.x | 1.0.0-RC2 | 5.0.0-RC2
0.3.x | 1.0.0-M6 | 5.0.0-M6
0.2.x | 1.0.0-M5 | 5.0.0-M5
0.1.x | 1.0.0-M4 | 5.0.0-M4

**Note** `0.9.0`+ artifacts are published on Maven Central via Sonatype OSS. Previous versions were available via <https://repo.scala-sbt.org/scalasbt/sbt-plugin-releases/net.aichler/sbt-jupiter-interface/scala_2.10/sbt_0.13/>, whose underlying host has migrated from Bintray to Scala Center Artifactory instance.

## Framework Options

Expand Down Expand Up @@ -91,24 +87,33 @@ Any parameter not starting with `-` or `+` is treated as a glob pattern for matc

You can set default options in your build.sbt file:

testOptions += Tests.Argument(jupiterTestFramework, "-q", "-v")
```scala
testOptions += Tests.Argument(jupiterTestFramework, "-q", "-v")
```

Or use them with the test-quick and test-only commands:
Or use them with the `testQuick` and `testOnly` commands:

test-only -- +q +v *Sequence*h2mem*
```scala
testOnly -- +q +v *Sequence*h2mem*
```

### Tag Expressions

Tag expressions can be used with `--include-tags` and `exclude-tags` respectively.

testOnly -- --include-tags=(micro&product),(micro&shipping)
```scala
testOnly -- --include-tags=(micro&product),(micro&shipping)
```

Special care has to be taken if any expression contains white-space. In that case the entire parameter needs to be enclosed by double quotes.

testOnly -- "include-tags=(micro & product),(micro & shipping)"
```scala
testOnly -- "include-tags=(micro & product),(micro & shipping)"
```

Please see the corresponding chapter in [JUnit Documentation](https://junit.org/junit5/docs/current/user-guide/#running-tests-tag-expressions) for a detailed description on how to build tag expressions.

## Credits

This plugin is heavily inspired by [JUnit Interface](https://github.com/sbt/junit-interface) and the console launcher from [JUnit Team](https://github.com/junit-team/junit5). Parts of the output capturing is based on code from [Apache Geronimo GShell](http://geronimo.apache.org/gshell/index.html).
* Jupiter Interface was originally developed by Michael Aichler in 2017.
* This plugin is heavily inspired by [JUnit Interface](https://github.com/sbt/junit-interface) and the console launcher from [JUnit Team](https://github.com/junit-team/junit5). Parts of the output capturing is based on code from [Apache Geronimo GShell](http://geronimo.apache.org/gshell/index.html).

0 comments on commit 075428c

Please sign in to comment.