From 075428c0d6823f0f44964a3ee81e1be7b4d869fe Mon Sep 17 00:00:00 2001 From: eugene yokota Date: Mon, 29 Jul 2024 16:21:01 -0400 Subject: [PATCH] Update README (#90) --- README.md | 91 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 48 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index 4f5b5a9..8f62790 100644 --- a/README.md +++ b/README.md @@ -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 , whose underlying host has migrated from Bintray to Scala Center Artifactory instance. ## Framework Options @@ -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).