Class OutputTester


  • public class OutputTester
    extends java.lang.Object
    A very simple class to facilitate testing of outputs produced by test cases.
    • Constructor Summary

      Constructors 
      Constructor Description
      OutputTester​(java.lang.Class<?> testRoot, java.lang.String expectedOutputsDirPath)
      Creates an output tester to validate outputs produced by test methods of a given class.
      OutputTester​(java.lang.Class<?> testRoot, java.lang.String expectedOutputsDirPath, java.lang.String expectedOutputEncoding)
      Creates an output tester to validate outputs produced by test methods of a given class.
      OutputTester​(java.lang.String expectedOutputsDirPath)
      Creates an output tester to validate outputs produced by test methods of a subclass
      OutputTester​(java.lang.String expectedOutputsDirPath, java.lang.String expectedOutputEncoding)
      Creates an output tester to validate outputs produced by test methods of a subclass
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      private java.lang.String cleanup​(java.lang.String content)  
      void clear()
      Discards any output stored in the internal buffer.
      private java.io.File getExpectedOutputDir()  
      private java.lang.String getOutputAndClear()  
      java.io.File getResourceDir()
      Returns the project's actual resource directory, where the expected output files are located.
      private java.io.InputStream getResultData​(java.lang.String className, java.lang.String testMethod)  
      java.lang.String getTestResourcesFolder()
      Returns the project's test resources folder (relative to the project root), where the expected output files are located.
      boolean getUpdateExpectedOutputs()
      Returns a flag indicating whether all tests of the test class should have their outputs updated.
      boolean isDumpMismatchedOutputToFile()
      Indicates whether the output produced by a given test method should be written into a temporary file.
      boolean isNormalizeLineSeparators()
      Indicates whether line separators in both produced and expected outputs will be normalized (i.e.
      private boolean isTestMethod​(java.lang.String className, java.lang.String methodName)  
      private void performValidation​(boolean validate, boolean print, java.lang.String className, java.lang.String method, java.lang.Object[] methodArgs, java.lang.String producedOutput, java.io.File expectedOutputDir)  
      void print​(java.lang.Object contents)
      Appends some content to the output.
      void print​(java.lang.StringBuilder out, java.lang.Object contents)
      Appends some content to the output.
      private void print​(java.lang.String output, java.lang.String className, java.lang.String method)  
      void printAndDontValidate​(java.lang.CharSequence output, java.lang.Object... methodArgs)
      Prints the result to the standard output without validating its contents
      void printAndDontValidate​(java.lang.Object... methodArgs)
      Prints the result to the standard output without validating its contents
      void printAndValidate​(java.lang.CharSequence output, java.lang.Object... methodArgs)
      Prints the result to the standard output and validates it against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
      void printAndValidate​(java.lang.Object... methodArgs)
      Prints the result to the standard output and validates it against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
      private void printAndValidateOutput​(boolean validate, boolean print, java.lang.String producedOutput, java.io.File expectedOutputDir, java.lang.Object[] methodArgs)
      Finds out the test method being executed and compares the output against the expected output in expectedOutputsDirPath.
      private void printAndValidateOutput​(boolean validate, boolean print, java.lang.String producedOutput, java.lang.Object[] methodArgs)
      Finds out the test method being executed and compares the output against the expected output in expectedOutputsDirPath.
      void println()
      Appends a newline to the output
      void println​(java.lang.Object contents)
      Appends some content to the output and adds a newline at the end.
      void println​(java.lang.StringBuilder out)
      Appends a newline to the output
      void println​(java.lang.StringBuilder out, java.lang.Object contents)
      Appends some content to the output and adds a newline at the end.
      void setDumpMismatchedOutputToFile​(boolean dumpMismatchedOutputToFile)
      Defines whether the output produced by a given test method should be written into a temporary file.
      void setNormalizeLineSeparators​(boolean normalizeLineSeparators)
      Enables/disables normalization of line separators.
      void setResourceDir​(java.io.File resourceDir)
      Defines the project's actual resource directory, where the expected output files are located.
      void setTestResourcesFolder​(java.lang.String testResourcesFolder)
      Defines the project's test resources folder (relative to the project root), where the expected output files are located.
      void setUpdateExpectedOutputs​(boolean updateExpectedOutputs)
      Used to indicate when all tests of the test class should have their outputs updated.
      void updateExpectedOutput​(java.lang.CharSequence output, java.lang.Object... methodArgs)
      Updates or creates the expected output file under the given expected output directory.
      void updateExpectedOutput​(java.lang.Object... methodArgs)
      Updates or creates the expected output file under the given expected output directory.
      private void updateExpectedOutput​(java.lang.String className, java.lang.String testMethod, java.lang.String producedOutput, java.io.File expectedOutputDir)  
      void validate​(java.lang.CharSequence output, java.lang.Object... methodArgs)
      Validates the result against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
      void validate​(java.lang.Object... methodArgs)
      Validates the result against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
      private void validateExampleOutput​(java.lang.String className, java.lang.String testMethod, java.lang.String producedOutput, java.io.File expectedOutputDir)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • out

        private java.lang.StringBuilder out
      • testRoot

        private final java.lang.Class<?> testRoot
      • packageName

        private final java.lang.String packageName
      • expectedOutputsDirPath

        private final java.lang.String expectedOutputsDirPath
      • expectedOutputEncoding

        private final java.lang.String expectedOutputEncoding
      • normalizeLineSeparators

        private boolean normalizeLineSeparators
      • dumpMismatchedOutputToFile

        private boolean dumpMismatchedOutputToFile
      • resourceDir

        private java.io.File resourceDir
      • testResourcesFolder

        private java.lang.String testResourcesFolder
      • updateExpectedOutputs

        private boolean updateExpectedOutputs
      • classResourceReader

        private final ResourceReader classResourceReader
    • Constructor Detail

      • OutputTester

        public OutputTester​(java.lang.String expectedOutputsDirPath)
        Creates an output tester to validate outputs produced by test methods of a subclass
        Parameters:
        expectedOutputsDirPath - the path to a file or classpath resource that contains the expected outputs
      • OutputTester

        public OutputTester​(java.lang.String expectedOutputsDirPath,
                            java.lang.String expectedOutputEncoding)
        Creates an output tester to validate outputs produced by test methods of a subclass
        Parameters:
        expectedOutputsDirPath - the path to a file or classpath resource that contains the expected outputs
        expectedOutputEncoding - the encoding of the files stored in the given path
      • OutputTester

        public OutputTester​(java.lang.Class<?> testRoot,
                            java.lang.String expectedOutputsDirPath)
        Creates an output tester to validate outputs produced by test methods of a given class.
        Parameters:
        testRoot - the test class whose test methods' outputs will be validated
        expectedOutputsDirPath - the path to a file or classpath resource that contains the expected outputs
      • OutputTester

        public OutputTester​(java.lang.Class<?> testRoot,
                            java.lang.String expectedOutputsDirPath,
                            java.lang.String expectedOutputEncoding)
        Creates an output tester to validate outputs produced by test methods of a given class.
        Parameters:
        testRoot - the test class whose test methods' outputs will be validated
        expectedOutputsDirPath - the path to a file or classpath resource that contains the expected outputs
        expectedOutputEncoding - the encoding of the files stored in the given path
    • Method Detail

      • setUpdateExpectedOutputs

        public void setUpdateExpectedOutputs​(boolean updateExpectedOutputs)
        Used to indicate when all tests of the test class should have their outputs updated. If the getUpdateExpectedOutputs() method evaluates to true, all calls to validate(Object...) or printAndValidate(Object...) will trigger the updateExpectedOutput(Object...) method internally. No tests will fail but error messages will be printed out to the standard output to remind users that the outputs are not being validated.
        Parameters:
        updateExpectedOutputs - flag to indicate whether all expected outputs of a test case should be updated.
      • getUpdateExpectedOutputs

        public boolean getUpdateExpectedOutputs()
        Returns a flag indicating whether all tests of the test class should have their outputs updated. If true, all calls to validate(Object...) or printAndValidate(Object...) will trigger the updateExpectedOutput(Object...) method internally. No tests will fail but error messages will be printed out to the standard output to remind users that the outputs are not being validated.
        Returns:
        true to indicate whether all expected outputs of a test case should be updated, or false if the test case outputs will be validated.
      • printAndDontValidate

        public void printAndDontValidate​(java.lang.CharSequence output,
                                         java.lang.Object... methodArgs)
        Prints the result to the standard output without validating its contents
        Parameters:
        output - the result of the test case.
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • printAndDontValidate

        public void printAndDontValidate​(java.lang.Object... methodArgs)
        Prints the result to the standard output without validating its contents
        Parameters:
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • printAndValidate

        public void printAndValidate​(java.lang.CharSequence output,
                                     java.lang.Object... methodArgs)
        Prints the result to the standard output and validates it against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
        Parameters:
        output - the result of the test case to be validated against the expected output.
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • printAndValidate

        public void printAndValidate​(java.lang.Object... methodArgs)
        Prints the result to the standard output and validates it against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
        Parameters:
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • validate

        public void validate​(java.lang.CharSequence output,
                             java.lang.Object... methodArgs)
        Validates the result against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
        Parameters:
        output - the result of the test case to be validated against the expected output.
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • validate

        public void validate​(java.lang.Object... methodArgs)
        Validates the result against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
        Parameters:
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • getResourceDir

        public java.io.File getResourceDir()
        Returns the project's actual resource directory, where the expected output files are located. Used when updateExpectedOutput(Object...) is called to determine where to update/create expected output files.
        Returns:
        the project's resource directory.
      • setResourceDir

        public void setResourceDir​(java.io.File resourceDir)
        Defines the project's actual resource directory, where the expected output files are located. Used when updateExpectedOutput(Object...) is called to determine where to update/create expected output files.
        Parameters:
        resourceDir - project's resource directory.
      • getTestResourcesFolder

        public java.lang.String getTestResourcesFolder()
        Returns the project's test resources folder (relative to the project root), where the expected output files are located. Used when updateExpectedOutput(Object...) is called to determine where to update/create expected output files, and getResourceDir() evaluates to null Defaults to "src/test/resources"
        Returns:
        the test resources folder.
      • setTestResourcesFolder

        public void setTestResourcesFolder​(java.lang.String testResourcesFolder)
        Defines the project's test resources folder (relative to the project root), where the expected output files are located. Used when updateExpectedOutput(Object...) is called to determine where to update/create expected output files, and getResourceDir() evaluates to null; Defaults to "src/test/resources"
        Parameters:
        testResourcesFolder - the test resources folder.
      • updateExpectedOutput

        public void updateExpectedOutput​(java.lang.Object... methodArgs)
        Updates or creates the expected output file under the given expected output directory. This method will always trigger a validation and will always fail. It prints out the different expected and actual results if they are different, or fails if the expected output is already updated and the results match.
        Parameters:
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • updateExpectedOutput

        public void updateExpectedOutput​(java.lang.CharSequence output,
                                         java.lang.Object... methodArgs)
        Updates or creates the expected output file under the given expected output directory. This method will always trigger a validation and will always fail. It prints out the different expected and actual results if they are different, or fails if the expected output is already updated and the results match.
        Parameters:
        output - the actual output whose contents will be used to generate/update the expected output file.
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • getExpectedOutputDir

        private java.io.File getExpectedOutputDir()
      • println

        public void println​(java.lang.StringBuilder out,
                            java.lang.Object contents)
        Appends some content to the output and adds a newline at the end.
        Parameters:
        out - the output to have content appended to.
        contents - the contents to be appended
      • println

        public void println​(java.lang.Object contents)
        Appends some content to the output and adds a newline at the end.
        Parameters:
        contents - the contents to be appended
      • println

        public void println​(java.lang.StringBuilder out)
        Appends a newline to the output
        Parameters:
        out - the output to have a newline appended
      • println

        public void println()
        Appends a newline to the output
      • print

        public void print​(java.lang.StringBuilder out,
                          java.lang.Object contents)
        Appends some content to the output.
        Parameters:
        out - the output to have content appended to.
        contents - the contents to be appended
      • print

        public void print​(java.lang.Object contents)
        Appends some content to the output.
        Parameters:
        contents - the contents to be appended
      • printAndValidateOutput

        private void printAndValidateOutput​(boolean validate,
                                            boolean print,
                                            java.lang.String producedOutput,
                                            java.lang.Object[] methodArgs)
        Finds out the test method being executed and compares the output against the expected output in expectedOutputsDirPath.
        Parameters:
        validate - flag to indicate whether the output should be validated
        print - flag that indicates whether or not to print the output
        producedOutput - the output produced by an example
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • printAndValidateOutput

        private void printAndValidateOutput​(boolean validate,
                                            boolean print,
                                            java.lang.String producedOutput,
                                            java.io.File expectedOutputDir,
                                            java.lang.Object[] methodArgs)
        Finds out the test method being executed and compares the output against the expected output in expectedOutputsDirPath. If expectedOutputToUpdate is not null, the expected output file will be generated/updated to store the expected output, and the the test method will fail.
        Parameters:
        validate - flag to indicate whether the output should be validated
        print - flag that indicates whether or not to print the output
        producedOutput - the output produced by an example
        expectedOutputDir - directory of the expected output file to generate/update
        methodArgs - arguments passed to the test method. Used when testing with data providers
      • performValidation

        private void performValidation​(boolean validate,
                                       boolean print,
                                       java.lang.String className,
                                       java.lang.String method,
                                       java.lang.Object[] methodArgs,
                                       java.lang.String producedOutput,
                                       java.io.File expectedOutputDir)
      • isTestMethod

        private boolean isTestMethod​(java.lang.String className,
                                     java.lang.String methodName)
      • print

        private void print​(java.lang.String output,
                           java.lang.String className,
                           java.lang.String method)
      • getResultData

        private java.io.InputStream getResultData​(java.lang.String className,
                                                  java.lang.String testMethod)
      • validateExampleOutput

        private void validateExampleOutput​(java.lang.String className,
                                           java.lang.String testMethod,
                                           java.lang.String producedOutput,
                                           java.io.File expectedOutputDir)
      • updateExpectedOutput

        private void updateExpectedOutput​(java.lang.String className,
                                          java.lang.String testMethod,
                                          java.lang.String producedOutput,
                                          java.io.File expectedOutputDir)
      • cleanup

        private java.lang.String cleanup​(java.lang.String content)
      • clear

        public void clear()
        Discards any output stored in the internal buffer.
      • getOutputAndClear

        private java.lang.String getOutputAndClear()
      • isNormalizeLineSeparators

        public boolean isNormalizeLineSeparators()
        Indicates whether line separators in both produced and expected outputs will be normalized (i.e. set to '\n').
        Returns:
        a flag indicating whether normalization of line separators is enabled
      • setNormalizeLineSeparators

        public void setNormalizeLineSeparators​(boolean normalizeLineSeparators)
        Enables/disables normalization of line separators. If enabled, the line separators in both produced and expected outputs will be set to '\n'.
        Parameters:
        normalizeLineSeparators - flag to enable or disable normalization of line separators
      • isDumpMismatchedOutputToFile

        public boolean isDumpMismatchedOutputToFile()
        Indicates whether the output produced by a given test method should be written into a temporary file. This is useful for updating an expected output file, or obtain the initial output file. If enabled (the default), the message ">> Output dumped into temporary file: <tmp_dir>/<method_name>_<random_number>.txt" will be produced before the assertion error is thrown.
        Returns:
        a flag indicating whether the output produced by failing test methods should be saved into a temporary file.
      • setDumpMismatchedOutputToFile

        public void setDumpMismatchedOutputToFile​(boolean dumpMismatchedOutputToFile)
        Defines whether the output produced by a given test method should be written into a temporary file. This is useful for updating an expected output file, or obtain the initial output file. If enabled (the default), the message ">> Output dumped into temporary file: <tmp_dir>/<method_name>_<random_number>.txt" will be produced before the assertion error is thrown.
        Parameters:
        dumpMismatchedOutputToFile - a flag indicating whether the output produced by failing test methods should be saved into a temporary file.