Skip to content
main
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 

junit5-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).

Build Quality Gate Status Coverage Maven Central

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:

  1. Extend the test class with the class ExitGuard
  2. Use AssertExit.assertExit(Runnable) or AssertExit.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:

  1. Extend the test class with SystemOutGuard
  2. Add a parameter of type Capturable to the test method (or the before-all-method)
  3. Activate capturing on the stream
  4. Run code under test
  5. 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

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 test to run unit tests.
  • Run mvn package to 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

  1. 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>
  2. Checkout the main branch.

  3. Update version in pom.xml, commit and push.

  4. Run command

    mvn -DskipSigningArtifacts=false clean deploy
  5. Create a release of the main branch on GitHub.

  6. After some time the release will be available at Maven Central.