Class OutputTester


  • public class OutputTester
    extends Object
    A very simple class to facilitate testing of outputs produced by test cases.
    Author:
    uniVocity Software Pty Ltd - dev@univocity.com
    • Constructor Summary

      Constructors 
      Constructor Description
      OutputTester​(Class<?> testRoot, String expectedOutputsDirPath)
      Creates an output tester to validate outputs produced by test methods of a given class.
      OutputTester​(Class<?> testRoot, String expectedOutputsDirPath, String expectedOutputEncoding)
      Creates an output tester to validate outputs produced by test methods of a given class.
      OutputTester​(String expectedOutputsDirPath)
      Creates an output tester to validate outputs produced by test methods of a subclass
      OutputTester​(String expectedOutputsDirPath, 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
      void clear()
      Discards any output stored in the internal buffer.
      File getResourceDir()
      Returns the project's actual resource directory, where the expected output files are located.
      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.
      void print​(Object contents)
      Appends some content to the output.
      void print​(StringBuilder out, Object contents)
      Appends some content to the output.
      void printAndDontValidate​(CharSequence output, Object... methodArgs)
      Prints the result to the standard output without validating its contents
      void printAndDontValidate​(Object... methodArgs)
      Prints the result to the standard output without validating its contents
      void printAndValidate​(CharSequence output, 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​(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 println()
      Appends a newline to the output
      void println​(Object contents)
      Appends some content to the output and adds a newline at the end.
      void println​(StringBuilder out)
      Appends a newline to the output
      void println​(StringBuilder out, 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​(File resourceDir)
      Defines the project's actual resource directory, where the expected output files are located.
      void setTestResourcesFolder​(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​(CharSequence output, Object... methodArgs)
      Updates or creates the expected output file under the given expected output directory.
      void updateExpectedOutput​(Object... methodArgs)
      Updates or creates the expected output file under the given expected output directory.
      void validate​(CharSequence output, Object... methodArgs)
      Validates the result against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
      void validate​(Object... methodArgs)
      Validates the result against the expected output stored in {expectedOutputsDirPath}/{test_class_name}/{test_method_name}
    • Constructor Detail

      • OutputTester

        public OutputTester​(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​(String expectedOutputsDirPath,
                            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​(Class<?> testRoot,
                            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​(Class<?> testRoot,
                            String expectedOutputsDirPath,
                            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​(CharSequence output,
                                         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​(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​(CharSequence output,
                                     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​(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​(CharSequence output,
                             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​(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 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​(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 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​(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​(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​(CharSequence output,
                                         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
      • println

        public void println​(StringBuilder out,
                            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​(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​(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​(StringBuilder out,
                          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​(Object contents)
        Appends some content to the output.
        Parameters:
        contents - the contents to be appended
      • clear

        public void clear()
        Discards any output stored in the internal buffer.
      • 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.