com.github.stefanbirkner.systemlambda

Class SystemLambda

java.lang.Object

com.github.stefanbirkner.systemlambda.SystemLambda

public class SystemLambda
extends Object

SystemLambda is a collection of functions for testing code that uses java.lang.System.

System.exit

Command-line applications terminate by calling System.exit with some status code. If you test such an application then the JVM that runs the test exits when the application under test calls System.exit. You can avoid this with the method catchSystemExit which also returns the status code of the System.exit call.

 @Test
 void application_exits_with_status_42(
 ) throws Exception {
   int statusCode = catchSystemExit(() -> {
     System.exit(42);
   });
   assertEquals(42, statusCode);
 }
 

The method catchSystemExit throws an AssertionError if the code under test does not call System.exit. Therefore your test fails with the failure message "System.exit has not been called."

Environment Variables

The method withEnvironmentVariable allows you to set environment variables within your test code that are removed after your code under test is executed.

 @Test
 void execute_code_with_environment_variables(
 ) throws Exception {
   List<String> values = withEnvironmentVariable("first", "first value")
     .and("second", "second value")
     .execute(() -> asList(
       System.getenv("first"),
       System.getenv("second")
     ));
   assertEquals(
     asList("first value", "second value"),
     values
   );
 }

System Properties

The function restoreSystemProperties guarantees that after executing the test code each System property has the same value like before. Therefore you can modify System properties inside of the test code without having an impact on other tests.

 @Test
 void execute_code_that_manipulates_system_properties(
 ) throws Exception {
   restoreSystemProperties(() -> {
     System.setProperty("some.property", "some value");
     //code under test that reads properties (e.g. "some.property") or
     //modifies them.
   });
 }
 

System.out and System.err

Command-line applications usually write to the console. If you write such applications you need to test the output of these applications. The methods tapSystemErr, tapSystemErrNormalized, tapSystemOut and tapSystemOutNormalized allow you to tap the text that is written to System.err/System.out. The methods with the suffix Normalized normalize line breaks to \n so that you can run tests with the same assertions on different operating systems.

 @Test
 void application_writes_text_to_System_err(
 ) throws Exception {
   String text = tapSystemErr(() -> {
     System.err.print("some text");
   });
   assertEquals(text, "some text");
 }

 @Test
 void application_writes_mutliple_lines_to_System_err(
 ) throws Exception {
   String text = tapSystemErrNormalized(() -> {
     System.err.println("first line");
     System.err.println("second line");
   });
   assertEquals(text, "first line\nsecond line\n");
 }

 @Test
 void application_writes_text_to_System_out(
 ) throws Exception {
   String text = tapSystemOut(() -> {
     System.out.print("some text");
   });
   assertEquals(text, "some text");
 }

 @Test
 void application_writes_mutliple_lines_to_System_out(
 ) throws Exception {
   String text = tapSystemOutNormalized(() -> {
     System.out.println("first line");
     System.out.println("second line");
   });
   assertEquals(text, "first line\nsecond line\n");
 }

You can assert that nothing is written to System.err/System.out by wrapping code with the function assertNothingWrittenToSystemErr/assertNothingWrittenToSystemOut. E.g. the following tests fail:

 @Test
 void fails_because_something_is_written_to_System_err(
 ) throws Exception {
   assertNothingWrittenToSystemErr(() -> {
     System.err.println("some text");
   });
 }

 @Test
 void fails_because_something_is_written_to_System_out(
 ) throws Exception {
   assertNothingWrittenToSystemOut(() -> {
     System.out.println("some text");
   });
 }
 

If the code under test writes text to System.err/System.out then it is intermixed with the output of your build tool. Therefore you may want to avoid that the code under test writes to System.err/System.out. You can achieve this with the function muteSystemErr/muteSystemOut. E.g. the following tests don't write anything to System.err/System.out:

 @Test
 void nothing_is_written_to_System_err(
 ) throws Exception {
   muteSystemErr(() -> {
     System.err.println("some text");
   });
 }

 @Test
 void nothing_is_written_to_System_out(
 ) throws Exception {
   muteSystemOut(() -> {
     System.out.println("some text");
   });
 }
 

System.in

Interactive command-line applications read from System.in. If you write such applications you need to provide input to these applications. You can specify the lines that are available from System.in with the method withTextFromSystemIn

 @Test
 void Scanner_reads_text_from_System_in(
 ) throws Exception {
   withTextFromSystemIn("first line", "second line")
     .execute(() -> {
       Scanner scanner = new Scanner(System.in);
       scanner.nextLine();
       assertEquals("first line", scanner.nextLine());
     });
 }
 

For complete test coverage you may also want to simulate System.in throwing exceptions when the application reads from it. You can specify such an exception (either RuntimeException or IOException) after specifying the text. The exception will be thrown by the next read after the text has been consumed.

 @Test
 void System_in_throws_IOException(
 ) throws Exception {
   withTextFromSystemIn("first line", "second line")
     .andExceptionThrownOnInputEnd(new IOException())
     .execute(() -> {
       Scanner scanner = new Scanner(System.in);
       scanner.nextLine();
       scanner.nextLine();
       assertThrownBy(
         IOException.class,
         () -> scanner.readLine()
       );
   });
 }

 @Test
 void System_in_throws_RuntimeException(
 ) throws Exception {
   withTextFromSystemIn("first line", "second line")
     .andExceptionThrownOnInputEnd(new RuntimeException())
     .execute(() -> {
       Scanner scanner = new Scanner(System.in);
       scanner.nextLine();
       scanner.nextLine();
       assertThrownBy(
                RuntimeException.class,
          () -> scanner.readLine()
       );
           });
 }
 

You can write a test that throws an exception immediately by not providing any text.

 withTextFromSystemIn()
   .andExceptionThrownOnInputEnd(...)
   .execute(() -> {
     Scanner scanner = new Scanner(System.in);
     assertThrownBy(
       ...,
       () -> scanner.readLine()
     );
   });
 

Security Manager

The function withSecurityManager lets you specify the SecurityManager that is returned by System.getSecurityManger() while your code under test is executed.

 @Test
 void execute_code_with_specific_SecurityManager(
 ) throws Exception {
   SecurityManager securityManager = new ASecurityManager();
   withSecurityManager(
     securityManager,
     () -> {
       //code under test
       //e.g. the following assertion is met
       assertSame(
         securityManager,
         System.getSecurityManager()
       );
     }
   );
 }
 

After withSecurityManager(...) is executed System.getSecurityManager() returns the original security manager again.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SystemLambda.SystemInStub A stub that defines the text provided by System.in.
static class	SystemLambda.WithEnvironmentVariables A collection of values for environment variables.

Constructor Summary

Constructors

Constructor and Description
SystemLambda()

Method Summary

Modifier and Type	Method and Description
static void	assertNothingWrittenToSystemErr(Statement statement) Executes the statement and fails (throws an AssertionError) if the statement tries to write to System.err.
static void	assertNothingWrittenToSystemOut(Statement statement) Executes the statement and fails (throws an AssertionError) if the statement tries to write to System.out.
static int	catchSystemExit(Statement statement) Executes the statement and returns the status code that is provided to System.exit(int) within the statement.
static void	muteSystemErr(Statement statement) Executes the statement and suppresses the output of the statement to System.err.
static void	muteSystemOut(Statement statement) Executes the statement and suppresses the output of the statement to System.out.
static void	restoreSystemProperties(Statement statement) Executes the statement and restores the system properties after the statement has been executed.
static String	tapSystemErr(Statement statement) Executes the statement and returns the text that was written to System.err by the statement.
static String	tapSystemErrNormalized(Statement statement) Executes the statement and returns the text that was written to System.err by the statement.
static String	tapSystemOut(Statement statement) Executes the statement and returns the text that was written to System.out by the statement.
static String	tapSystemOutNormalized(Statement statement) Executes the statement and returns the text that was written to System.out by the statement.
static SystemLambda.WithEnvironmentVariables	withEnvironmentVariable(String name, String value) Executes the statement with the specified environment variables.
static void	withSecurityManager(SecurityManager securityManager, Statement statement) Executes the statement with the provided security manager.
static SystemLambda.SystemInStub	withTextFromSystemIn(String... lines) Executes the statement and lets System.in provide the specified text during the execution.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SystemLambda

public SystemLambda()

Method Detail

assertNothingWrittenToSystemErr

public static void assertNothingWrittenToSystemErr(Statement statement)
                                            throws Exception

Executes the statement and fails (throws an AssertionError) if the statement tries to write to System.err.

The following test fails

 @Test
 void fails_because_something_is_written_to_System_err(
 ) throws Exception {
   assertNothingWrittenToSystemErr(() -> {
     System.err.println("some text");
   });
 }
 

The test fails with the failure "Tried to write 's' to System.err although this is not allowed."

Parameters:

statement - an arbitrary piece of code.

Throws:

AssertionError - if the statements tries to write to System.err.

Exception - any exception thrown by the statement.

Since:

1.0.0

See Also:

assertNothingWrittenToSystemOut(Statement)

assertNothingWrittenToSystemOut

public static void assertNothingWrittenToSystemOut(Statement statement)
                                            throws Exception

Executes the statement and fails (throws an AssertionError) if the statement tries to write to System.out.

The following test fails

 @Test
 void fails_because_something_is_written_to_System_out(
 ) throws Exception {
   assertNothingWrittenToSystemOut(() -> {
     System.out.println("some text");
   });
 }
 

The test fails with the failure "Tried to write 's' to System.out although this is not allowed."

Parameters:

statement - an arbitrary piece of code.

Throws:

AssertionError - if the statements tries to write to System.out.

Exception - any exception thrown by the statement.

Since:

1.0.0

See Also:

assertNothingWrittenToSystemErr(Statement)

catchSystemExit

public static int catchSystemExit(Statement statement)
                           throws Exception

Executes the statement and returns the status code that is provided to System.exit(int) within the statement. Additionally it avoids that the JVM is shut down because of a call to System.exit(int).

 @Test
 void application_exits_with_status_42(
 ) throws Exception {
   int statusCode = catchSystemExit(() -> {
     System.exit(42);
   });
   assertEquals(42, statusCode);
 }
 

Parameters:

statement - an arbitrary piece of code.

Returns:

the status code provided to System.exit(int).

Throws:

AssertionError - if the statement does not call System.exit(int).

Exception - any exception thrown by the statement.

Since:

1.0.0

muteSystemErr

public static void muteSystemErr(Statement statement)
                          throws Exception

Executes the statement and suppresses the output of the statement to System.err. Use this to avoid that the output of your build tool gets mixed with the output of the code under test.

 @Test
 void nothing_is_written_to_System_err(
 ) throws Exception {
   muteSystemErr(() -> {
       System.err.println("some text");
     }
   );
 }
 

Parameters:

statement - an arbitrary piece of code.

Throws:

Exception - any exception thrown by the statement.

Since:

1.0.0

See Also:

muteSystemOut(Statement)

muteSystemOut

public static void muteSystemOut(Statement statement)
                          throws Exception

Executes the statement and suppresses the output of the statement to System.out. Use this to avoid that the output of your build tool gets mixed with the output of the code under test.

 @Test
 void nothing_is_written_to_System_out(
 ) throws Exception {
   muteSystemOut(() -> {
     System.out.println("some text");
   });
 }
 

Parameters:

statement - an arbitrary piece of code.

Throws:

Exception - any exception thrown by the statement.

Since:

1.0.0

See Also:

muteSystemErr(Statement)

restoreSystemProperties

public static void restoreSystemProperties(Statement statement)
                                    throws Exception

Executes the statement and restores the system properties after the statement has been executed. This allows you to set or clear system properties within the statement without affecting other tests.

 @Test
 void execute_code_that_manipulates_system_properties(
 ) throws Exception {
   System.clearProperty("some property");
   System.setProperty("another property", "value before test");

   restoreSystemProperties(() -> {
     System.setProperty("some property", "some value");
     assertEquals(
       "some value",
       System.getProperty("some property")
     );

     System.clearProperty("another property");
     assertNull(
       System.getProperty("another property")
     );
   });

   //values are restored after test
   assertNull(
     System.getProperty("some property")
   );
   assertEquals(
     "value before test",
     System.getProperty("another property")
   );
 }
 

Parameters:

statement - an arbitrary piece of code.

Throws:

Exception - any exception thrown by the statement.

Since:

1.0.0

tapSystemErr

public static String tapSystemErr(Statement statement)
                           throws Exception

Executes the statement and returns the text that was written to System.err by the statement.

 @Test
 void application_writes_text_to_System_err(
 ) throws Exception {
   String textWrittenToSystemErr = tapSystemErr(() -> {
     System.err.print("some text");
   });
   assertEquals("some text", textWrittenToSystemErr);
 }
 

Parameters:

statement - an arbitrary piece of code.

Returns:

text that is written to System.err by the statement.

Throws:

Exception - any exception thrown by the statement.

Since:

1.0.0

See Also:

tapSystemOut(Statement)

tapSystemErrNormalized

public static String tapSystemErrNormalized(Statement statement)
                                     throws Exception

Executes the statement and returns the text that was written to System.err by the statement. New line characters are replaced with a single \n.

 @Test
 void application_writes_mutliple_lines_to_System_err(
 ) throws Exception {
   String textWrittenToSystemErr = tapSystemErrNormalized(() -> {
     System.err.println("some text");
   });
   assertEquals("some text\n", textWrittenToSystemErr);
 }
 

Parameters:

statement - an arbitrary piece of code.

Returns:

text that is written to System.err by the statement.

Throws:

Exception - any exception thrown by the statement.

Since:

1.0.0

See Also:

tapSystemOut(Statement)

tapSystemOut

public static String tapSystemOut(Statement statement)
                           throws Exception

Executes the statement and returns the text that was written to System.out by the statement.

 @Test
 void application_writes_text_to_System_out(
 ) throws Exception {
   String textWrittenToSystemOut = tapSystemOut(() -> {
     System.out.print("some text");
   });
   assertEquals("some text", textWrittenToSystemOut);
 }
 

Parameters:

statement - an arbitrary piece of code.

Returns:

text that is written to System.out by the statement.

Throws:

Exception - any exception thrown by the statement.

Since:

1.0.0

See Also:

tapSystemErr(Statement)

tapSystemOutNormalized

public static String tapSystemOutNormalized(Statement statement)
                                     throws Exception

Executes the statement and returns the text that was written to System.out by the statement. New line characters are replaced with a single \n.

 @Test
 void application_writes_mutliple_lines_to_System_out(
 ) throws Exception {
   String textWrittenToSystemOut = tapSystemOutNormalized(() -> {
     System.out.println("some text");
   });
   assertEquals("some text\n", textWrittenToSystemOut);
 }
 

Parameters:

statement - an arbitrary piece of code.

Returns:

text that is written to System.out by the statement.

Throws:

Exception - any exception thrown by the statement.

Since:

1.0.0

See Also:

tapSystemErr(Statement)

withEnvironmentVariable

public static SystemLambda.WithEnvironmentVariables withEnvironmentVariable(String name,
                                                                            String value)

Executes the statement with the specified environment variables. All changes to environment variables are reverted after the statement has been executed.

 @Test
 void execute_code_with_environment_variables(
 ) throws Exception {
    List<String> values = withEnvironmentVariable("first", "first value")
     .and("second", "second value")
     .and("third", null)
     .execute(() -> asList(
         System.getenv("first"),
         System.getenv("second"),
         System.getenv("third")
     ));
   assertEquals(
     asList("first value", "second value", null),
     values
   );
 }
 

You cannot specify the value of an an environment variable twice. An IllegalArgumentException is thrown when you try.

Warning: This method uses reflection for modifying internals of the environment variables map. It fails if your SecurityManager forbids such modifications.

Parameters:

name - the name of the environment variable.

value - the value of the environment variable.

Returns:

an SystemLambda.WithEnvironmentVariables instance that can be used to set more variables and run a statement with the specified environment variables.

Since:

1.0.0

See Also:

SystemLambda.WithEnvironmentVariables.and(String, String), SystemLambda.WithEnvironmentVariables.execute(Callable), SystemLambda.WithEnvironmentVariables.execute(Statement)

withSecurityManager

public static void withSecurityManager(SecurityManager securityManager,
                                       Statement statement)
                                throws Exception

Executes the statement with the provided security manager.

 @Test
 void execute_code_with_specific_SecurityManager(
 ) throws Exception {
   SecurityManager securityManager = new ASecurityManager();
   withSecurityManager(
     securityManager,
     () -> {
       //code under test
       //e.g. the following assertion is met
       assertSame(securityManager, System.getSecurityManager())
     }
   );
 }
 

The specified security manager is only present during the test.

Parameters:

securityManager - the security manager that is used while the statement is executed.

statement - an arbitrary piece of code.

Throws:

Exception - any exception thrown by the statement.

Since:

1.0.0

withTextFromSystemIn

public static SystemLambda.SystemInStub withTextFromSystemIn(String... lines)

Executes the statement and lets System.in provide the specified text during the execution. In addition several Exceptions can be specified that are thrown when System.in#read is called.

 @Test
 void Scanner_reads_text_from_System_in(
 ) throws Exception {
   withTextFromSystemIn("first line", "second line")
     .execute(() -> {
       Scanner scanner = new Scanner(System.in);
       scanner.nextLine();
       assertEquals("first line", scanner.nextLine());
     });
 }
 

Throwing Exceptions

You can also simulate a System.in that throws an IOException or RuntimeException. Use

 @Test
 void System_in_throws_IOException(
 ) throws Exception {
   withTextFromSystemIn()
     .andExceptionThrownOnInputEnd(new IOException())
     .execute(() -> {
       assertThrownBy(
         IOException.class,
         () -> new Scanner(System.in).readLine())
       );
     )};
 }

 @Test
 void System_in_throws_RuntimeException(
 ) throws Exception {
   withTextFromSystemIn()
    .andExceptionThrownOnInputEnd(new RuntimeException())
    .execute(() -> {
       assertThrownBy(
         RuntimeException.class,
         () -> new Scanner(System.in).readLine())
       );
     )};
 }
 

If you provide text as parameters of withTextFromSystemIn(...) in addition then the exception is thrown after the text has been read from System.in.

Parameters:

lines - the lines that are available from System.in.

Returns:

an SystemLambda.SystemInStub instance that is used to execute a statement with its execute method. In addition it can be used to specify an exception that is thrown after the text is read.

Since:

1.0.0

See Also:

SystemLambda.SystemInStub.execute(Statement), SystemLambda.SystemInStub.andExceptionThrownOnInputEnd(IOException), SystemLambda.SystemInStub.andExceptionThrownOnInputEnd(RuntimeException)