...

Once you have prepared some test data, you can either add it to the Translator subdirectory, or the multifile subdirectory, or create a new sub directory, maybe with your package name (like I did when I made the Translator subdirectory). If you want to add it to Translator or multifile, please contact me (davidsch) as these files have specific naming conventions and there are unit tests in the psana_test package that access them. Creating a new subdirectory requires less coordination, however if you think the test data is going to be useful to others, we should work together on it. One of the benefits of using the psana_test package, is I have a mechanism for checking in the md5 checksums of the test data into svn. This allows the unit tests to verify that the test data has not changed.

Using the psana_test package

Here I'll go through an example of using the psana_test package to prepare a new test file to test a new pdsdata type. Of general interest will preparing be preparation of the test file, and functionality in the python library code in psana_test.

Preparing a small sample test file

Suppose we don't have unit tests to see how psana handles Epix100aConfig version1 and EpixElement verion 2. I , and we have identified an experiment xtc file with this typethese types, namely

/reg/d/psdm/xcs/xcsi0314/xtc/e524-r0213-s03-c00.xtc

One of the tools in psana_test will let me see which datagrams have epix. I can string together a unix command to see:

...

In [9]: import psana_test.psanaTestLib as ptl
In [10]: ptl.copyBytes('/reg/d/psdm/xcs/xcsi0314/xtc/e524-r0213-s03-c00.xtc', [[0,0x00266284],[0x5C499EA0, 1548329088]], '/reg/g/psdm/data_test/Translator/test_089_xcs_xcsi0314_e524-r0213-s03-c00.xtc')
copying 2 sets of bytes:  [0,2515588)  [1548328608,1548329088)  from src=/reg/d/psdm/xcs/xcsi0314/xtc/e524-r0213-s03-c00.xtc to dest=/reg/g/psdm/data_test/Translator/test_089_xcs_xcsi0314_e524-r0213-s03-c00.xtc

To create the test file.

...

.

After creating it, I take a look at it in the data_test directory and make sure the permissions look good for psrel, basically that it is world readable. I also remove my write permission to make it read only.

Make a Unit Test to Process Output

Sometimes we are testing the output of Psana modules. It can be awkward to get that output into a testable form. One thing I do is run psana on test data using the Python subprocess package. I gather the stdout and stderr, looking for errors from psana as well as checking the module output. Other things you might want to do before running the test is check if the xtc file has changed, and check that the output is the same as the last time you tested it.

A useful psana module in the psana_test package is psana_test.dump. This dumps information on all the types and data psana sees. We first run it on the above file and inspect the output. After satisfying ourselves that it is correct, we make a unit test as follows. We run the original xtc and the dump output through md5sum. We record these, and then write a unit test that does both md5 checks and compares them.

The commands we do to prepare our test are

psana1302:~/rel/unitTestTutorial $ md5sum  /reg/g/psdm/data_test/Translator/test_089_xcs_xcsi0314_e524-r0213-s03-c00.xtc     
58357b0bf7b6d630c4c2e9633d5b4ca2  /reg/g/psdm/data_test/Translator/test_089_xcs_xcsi0314_e524-r0213-s03-c00.xtc

psana1302:~/rel/unitTestTutorial $ psana -m psana_test.dump /reg/g/psdm/data_test/Translator/test_089_xcs_xcsi0314_e524-r0213-s03-c00.xtc
# this has a lot of output that we inspect

psana1302:~/rel/unitTestTutorial $ psana -m psana_test.dump /reg/g/psdm/data_test/Translator/test_089_xcs_xcsi0314_e524-r0213-s03-c00.xtc | md5sum
cc830e794d292eb6cd1414fdad1e2b10  -

Our unit test looks like:

    def test_dump_on_test89(self):
        import os
        import psana_test.psanaTestLib as ptl
        
        test_data = '/reg/g/psdm/data_test/Translator/test_089_xcs_xcsi0314_e524-r0213-s03-c00.xtc'
        assert os.path.exists(test_data), "Test data: %s not found" % test_data
        md5sumXtc = '58357b0bf7b6d630c4c2e9633d5b4ca2' # from running md5sum on file
        md5sum = ptl.get_md5sum(test_data)    # demonstrate ptl function to run md5sum on file
        self.assertEqual(md5sum, md5sumXtc, msg="md5sum of xtc file has changed.\nold=%s\nnew=%s" % (md5sumXtc, md5sum))
        cmd = 'psana -m psana_test.dump %s | md5sum' % test_data  # pipe dump through md5sum, compare to previous
        md5sumOnDump = 'cc830e794d292eb6cd1414fdad1e2b10'  # from previous testing
        md5out,stderr = ptl.cmdTimeOut(cmd)   # demonstrate ptl function to capture input/output
        md5out = md5out.split(' -')[0].strip()  # the output of md5sum ends with -, discard it
        self.assertEqual(stderr,'',msg="There were errors in cmd=%s\nstderr: %s" % (cmd,stderr))
        self.assertEqual(md5out.strip(), 
                         md5sumOnDump, 
                         msg="md5sum for psana_dump is wrong.\nold='%s'\nnew='%s'\nRun cmd=%s and investigate" % (md5sumOnDump, md5out, cmd))