While funded by JISC via Mimas, Hedtek has recently providing assistance to Jorum, the UK’s Open Educational Resources repository; this varies from architectural to development assistance that is aimed at transforming the Jorum user experience.
Jorum is built on the DSpace repository, and part of our work involves building a new front end to Jorum. For this we need an API to DSpace, and while, conveniently, there is the DSpace REST API  module available for DSpace, it has not been used with the version of DSpace that Jorum uses, and until recently, it had no automated tests available for it. Given the centrality of this API for Jorum’s future development, we have started developing a suite of automated tests for the API. This post discusses progress, and mentions where our tests can be found on github.
Because the first front-end work we intend to perform is for OER resource discovery and download, so far we have only focussed on the ‘read’ functionality of the API. For this we have tested endpoints (URLs) that focus on read capabilities for:
- metadata harvest
For all of these, we wrote integration tests that tested the API endpoints running on DSpace,and then re-ran the tests on a full Jorum build.
The test development process
To implement the tests, we had to create a framework that would run the DSpace REST API using Jetty and control this programmatically.
We also needed to load database fixtures in order to have a known DSpace state to test against. When we started writing tests, loading SQL fixture files was problematic. We went through several iterations where, using a given means of loading our fixtures, all our existing tests would run, but frustratingly, for the very next test we tried, our fixture load mechanism would fail. Eventually we discovered that the appropriate way of loading a fixture is via the DatabaseManager class in DSpace.
We also needed to trace a bug in the DSpace REST API code where database connections weren’t being closed. This bug caused intermittent freezes during our test runs, which in turn made a stable test framework impossible while the bug existed.
Later, fixture creation became quite intricate when we needed to test file downloads were correct, as this involved finding and editing download directories in the data. This was solved neatly by the creation of a command line script that generates a database dump from a DSpace database, processes it, and replaces all the download paths with a Maven token that can be replaced with the actual file path location when the tests are run.
To test search, we also needed to create and load a Lucene index for DSpace. This was primarily done by using DSpace to construct a more intricate test fixture for the search actions and then taking a copy of the Lucene index from the DSpace installation. The index is then copied into place for use by the embedded Jetty server during the test run.
The tests themselves do a lot of validation of JSON structure. This is done with the aid of a simple JSON library which processes the JSON into JSONObject and JSONArray instances. This was a good starting point and was used to write the first few tests. As more tests were written, there was a lot of messy test fixture matching going on. To reduce this, we refactored our tests and started building up a set of matchers and matcher methods that allowed us to write tests much more quickly. The end result of this process was the beginning of a DSpace-specific test matcher library. This process could be taken further, but the stage we got to was enough to enable us to write tests quickly and with a minimum of effort.
Running the tests
The tests are built and run using Maven, so if you want to run the tests yourself (e.g. on a new DSpace release), you just need to get a copy of the REST API with our tests added, available at github.
Once you have the code, you will need to create a postgres database for the test run. This is aided with the script ‘create_integration_test_db’. Once the database is set up, you can run the tests with the command ‘mvn test’.
Here is the end of a successful test run (please click on this thumbnail image to see the output detail):
There is a lot of ‘noise’ on the output of a test run. This is unfortunately caused by various parts of the REST module that are logging directly to the console, rather than using a logging framework. Hopefully this will be fixed in future development on the module.
 We would prefer to call the API restful, since it does not follow the HATEOAS principle. For further details see any good reference on REST.