JarCastingjunit5-system-extensions (J5SE)
This project provides a set of JUnit 5 extension that allow testing behavior related to functions related to java.lang.System (e.g. asserting exit status codes).
Acknowledgments
The extensions in this project were inspired by a set of JUnit4 rules called "System Rules" which were written by Stefan Brikner and licensed under the Common Public License 1.0 (CPL).
Runtime Dependencies
Starting with version 1.2.0 junit5-system-extensions requires Java 11 to compile and at runtime. If your project requires Java 8, please use version 1.1.0.
| Dependency | Purpose | License |
|---|---|---|
| JUnit5 | Unit test framework | Eclipse Public License v2.0 |
Usage
Asserting System.exit(int) Calls
To trap and check calls to System.exit(int) follow these steps:
- Extend the test class with the class
ExitGuard - Use
AssertExit.assertExit(Runnable)orAssertExit.assertExitWithStatus(int, Runnable)to check for exit calls
Example:
import static org.itsallcode.junit.AssertExit.assertExit;
import org.itsallcode.junit.sysextensions.ExitGuard;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
@ExtendWith(ExitGuard.class)
class TestSystemExit
{
@Test
void testSystemExit()
{
assertExit(() -> System.exit(1));
}
}
The ExitGuard temporarily replaces the existing security manager.
From version 1.2.0 on if a security guard existed before, it serves as a delegate for all security checks with the exception of the checkExit.
Asserting Data Sent to System.out
To capture data sent to System.out, follow these steps:
- Extend the test class with
SystemOutGuard - Add a parameter of type
Capturableto the test method (or the before-all-method) - Activate capturing on the stream
- Run code under test
- Check captured data
Example:
import static org.junit.jupiter.api.Assertions.assertEquals;
import org.itsallcode.io.Capturable;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
@ExtendWith(SystemOutGuard.class)
class TestSystemOut
{
@Test
void testCapture(final Capturable stream)
{
stream.capture();
final String expected = "This text must be captured.";
System.out.print(expected);
assertEquals(stream.getCapturedData(), expected);
}
}
To mute the output (i.e. don't forward output to System.out / System.err) call stream.captureMuted() instead of stream.capture(). This can be useful to speed up unit tests.
Asserting Data Sent to System.err
Capturing data sent to System.err works in the exact same way as in the System.out case. The only difference is that you need to extend the test class with the SystemErrGuard.
Contributing, Feature Requests and Error Reporting
Please check our contribution guide to learn how you can help with the project, report errors or request features.
Changelog
Development
Build Time Dependencies
The list below show all build time dependencies in alphabetical order. Note that except the Maven build tool all required modules are downloaded automatically by Maven.
| Dependency | Purpose | License |
|---|---|---|
| Apache Maven | Build tool | Apache License 2.0 |
| License Maven Plugin | Add licenses to source files automatically | GNU Public License 3.0 |
| Maven Compiler Plugin | Maven provided and controlled Java compiler | Apache License 2.0 |
| Maven Source Plugin | Create Source JAR packages | Apache License 2.0 |
| Maven JavaDoc Plugin | Create JavaDoc JAR packages | Apache License 2.0 |
| Mockito | Mocking framework | MIT License |
Essential Build Steps
git clone https://github.com/itsallcode/junit5-system-extensions.git- Run
mvn testto run unit tests. - Run
mvn packageto create the JAR file.
Generate / update license file header
mvn license:update-file-header
Run local sonar analysis
mvn clean org.jacoco:jacoco-maven-plugin:prepare-agent package sonar:sonar \
-Dsonar.host.url=https://sonarcloud.io \
-Dsonar.organization=itsallcode \
-Dsonar.login=[token]
See analysis results at https://sonarcloud.io/dashboard?id=org.itsallcode%3Ajunit5-system-extensions
Check for updated dependencies / plugins
mvn versions:display-dependency-updates
mvn versions:display-plugin-updates
Publishing to MavenCentral
-
Add the following to your
~/.m2/settings.xml:<settings> <servers> <server> <id>ossrh</id> <username>your-jira-id</username> <password>your-jira-pwd</password> </server> </servers> <profiles> <profile> <id>ossrh</id> <activation> <activeByDefault>true</activeByDefault> </activation> <properties> <gpg.executable>gpg</gpg.executable> <gpg.passphrase>the_pass_phrase</gpg.passphrase> </properties> </profile> </profiles> </settings>
-
Checkout the
mainbranch. -
Update version in
pom.xml, commit and push. -
Run command
mvn -DskipSigningArtifacts=false clean deploy
-
Create a release of the
mainbranch on GitHub. -
After some time the release will be available at Maven Central.
