Package emissary.test.core.junit5

Class RegressionTest

  • public abstract class RegressionTest
extends ExtractionTest

    This test acts similarly to ExtractionTest; however, it compares the entire BDO instead of just what is defined in the XML. In other words, the XML must define exactly the output of the Place, no more and no less. There are methods provided to generate the XML required.

    To implement this for a test, you should:

    1. Extend this class
    2. Either Override generateAnswers() to return true or set the generateAnswers system property to true, which will generate the XML answer files
    3. Optionally, to generate answers file without changing code run mvn clean test -DgenerateAnswers=true
    4. Optionally, override the various provided methods if you want to customise the behaviour of providing the IBDO before/after processing
    5. Run the tests, which should pass - if they don't, you either have incorrect processing which needs fixing, or you need to further customise the initial/final IBDOs.
    6. Once the tests pass, you can remove the overridden method(s) added above.

    • Constructor Detail

      • RegressionTest

        public RegressionTest()

    • Method Detail

      • generateAnswers

        @ForOverride
protected boolean generateAnswers()
        Override this or set the generateAnswers system property to true to generate XML for data files.
        Returns:
        defaults to false if no XML should be generated (i.e. normal case of executing tests) or true to generate automatically

      • getInitialIbdo

        @ForOverride
protected emissary.core.IBaseDataObject getInitialIbdo​(String resource)
        Allow the initial IBDO to be overridden - for example, adding additional previous forms This is used in the simple case to generate an IBDO from the file on disk and override the filename
        Parameters:
        resource - path to the dat file
        Returns:
        the initial IBDO

      • tweakInitialIbdoBeforeSerialisation

        @ForOverride
protected void tweakInitialIbdoBeforeSerialisation​(String resource,
                                                   emissary.core.IBaseDataObject initialIbdo)
        Allow the initial IBDO to be overridden before serialising to XML. In the default case, we null out the data in the BDO which will force the data to be loaded from the .dat file instead.
        Parameters:
        resource - path to the dat file
        initialIbdo - to tweak

      • tweakFinalIbdoBeforeSerialisation

        @ForOverride
protected void tweakFinalIbdoBeforeSerialisation​(String resource,
                                                 emissary.core.IBaseDataObject finalIbdo)
        Allow the generated IBDO to be overridden - for example, adding certain field values. Will modify the provided IBDO. This is used in the simple case to set the current form for the final object to be taken from the file name. If the test worked correctly no change will be made, but if there is a discrepancy this will be highlighted afterwards when the diff takes place.
        Parameters:
        resource - path to the dat file
        finalIbdo - the existing final BDO after it's been processed by a place

      • tweakFinalResultsBeforeSerialisation

        @ForOverride
protected void tweakFinalResultsBeforeSerialisation​(String resource,
                                                    List<emissary.core.IBaseDataObject> children)
        Allow the children generated by the place to be overridden before serialising to XML. In the default case, do nothing.
        Parameters:
        resource - path to the dat file
        children - to tweak

      • tweakFinalLogEventsBeforeSerialisation

        @ForOverride
protected void tweakFinalLogEventsBeforeSerialisation​(String resource,
                                                      List<LogbackTester.SimplifiedLogEvent> simplifiedLogEvents)
        Allows the log events generated by the place to be modified before serialising to XML. In the default case, do nothing.
        Parameters:
        resource - path to the dat file
        simplifiedLogEvents - to tweak

      • getInitialForm

        @ForOverride
protected String getInitialForm​(String resource)
        Description copied from class: ExtractionTest
        Allow overriding the initial form in extensions to this test. By default, get the initial form from the filename in the form INITIAL_FORM@2.dat where INITIAL_FORM will be the initial form.
        Overrides:
        getInitialForm in class ExtractionTest
        Parameters:
        resource - to get the form from
        Returns:
        the initial form

      • getDecoders

        protected IBaseDataObjectXmlCodecs.ElementDecoders getDecoders​(String resource)
        This method returns the XML element decoders.
        Parameters:
        resource - the "resource" currently be tested.
        Returns:
        the XML element decoders.

      • getEncoders

        protected IBaseDataObjectXmlCodecs.ElementEncoders getEncoders​(String resource)
        This method returns the XML element encoders.
        Parameters:
        resource - the "resource" currently be tested.
        Returns:
        the XML element encoders.

      • checkAnswersPreHook

        protected void checkAnswersPreHook​(org.jdom2.Document answers,
                                   emissary.core.IBaseDataObject payload,
                                   List<emissary.core.IBaseDataObject> attachments,
                                   String tname)
        When the data is able to be retrieved from the XML (e.g. when getEncoders() returns the default encoders), then this method should be empty. However, in this case getEncoders() is returning the sha256 encoders which means the original data cannot be retrieved from the XML. Therefore, in order to test equivalence, all of the non-printable data in the IBaseDataObjects needs to be converted to a sha256 hash. The full encoders can be used by overriding the checkAnswersPreHook(...) to be empty and overriding getEncoders() to return the DEFAULT_ELEMENT_ENCODERS.
        Overrides:
        checkAnswersPreHook in class ExtractionTest

      • hashBytesIfNonPrintable

        protected Optional<String> hashBytesIfNonPrintable​(byte[] bytes,
                                                   boolean alwaysHash)
        Generates a SHA 256 hash of the provided bytes if they contain any non-printable characters
        Parameters:
        bytes - the bytes to evaluate
        alwaysHash - overrides the non-printable check and always hashes the bytes.
        Returns:
        a value optionally containing the generated hash

      • generateAnswerFiles

        protected void generateAnswerFiles​(String resource)
                            throws Exception
        Actually generate the answer file for a given resource Takes initial form and final forms from the filename
        Parameters:
        resource - to generate against
        Throws:
        Exception - if an error occurs during processing

      • getAnswerDocumentFor

        protected org.jdom2.Document getAnswerDocumentFor​(String resource)
        Description copied from class: UnitTest
        Get an JDOM XML document corresponding to a test resource
        Overrides:
        getAnswerDocumentFor in class UnitTest

      • setupPayload

        protected void setupPayload​(emissary.core.IBaseDataObject payload,
                            org.jdom2.Document answers)
        Overrides:
        setupPayload in class ExtractionTest

      • checkAnswers

        protected void checkAnswers​(org.jdom2.Document answers,
                            emissary.core.IBaseDataObject payload,
                            List<emissary.core.IBaseDataObject> attachments,
                            String tname)
        Overrides:
        checkAnswers in class ExtractionTest

      • fixDisposeRunnables

        protected void fixDisposeRunnables​(emissary.core.IBaseDataObject ibdo)
        Default behavior to fix dispose runnables to change "variant" to "invariant"
        Parameters:
        ibdo - the base data object containing dispose runnables