LibPQ offers a basic unit testing framework, which consists of the following modules:
- UnitTest.Assert - a collection of assertion functions
- UnitTest.Constants - framework-wide constants
- UnitTest.Discover - discover and run unit tests from all local sources
- UnitTest.Run - runner for individual test suites
- UnitTest.Subtests - helper function for writing subtests
Individual test cases are implemented using test functions. A test function is a function that takes zero arguments and produces one of three outcomes when called:
- If test is succesfull (PASSED) the test function returns any value. The value itself is irrelevant.
- If test is unsuccesfull (FAILED) the test function raises
LibPQ.AssertionError. (This error reason is defined in UnitTest.Constants) - If the test code itself raises an error the test is considered neither succesfull nor failed, and the error must not be silenced (ERROR)
A test suite is a collection of test functions, usually related to each other in some way. Test suite has to store test functions as a record with field names starting with "test" (the test prefix is defined in UnitTest.Constants).
Any field of the test suite which name does not start with "test" prefix is ignored by the UnitTest framework.
It is recommended to add a metadata field to the test suite record to enable
automated tests discovery. The field and its value are LibPQ.TestSuite = 1.
The number 1 indicates the version of test suite format and will be
incremented in future if any non-backwards compatible changes will be
introduced.
Suites without the metadata will still be executable by test runners but will not be visible to discovery tools.
In order to simplify writing the tests LibPQ offers some useful assertion functions in UnitTest.Assert module.
Each of the functions in that module is a valid test function that tests some simple assertion. You can use them as building blocks for writing your own tests.
When you need to run the same tests against slightly different parameters writing all the variations one by one can become tedious.
LibPQ will treat a list of test functions that are stored in the same test suite field as a group of subtests. It will execute them until an error occurs, and that error will be treated as the test result.
There is also a helper function that simplifies creating subtests.
At this moment there are no special tools for defining and invoking test
fixtures, but setUp and tearDown field names in test suite record should be
considered reserved for that purpose.
To create test fixture now you can add a helper function to the test suite and store it in any field which name does not start with "test" prefix. Such function(s) will have to be invoked explicitly from each individual test.
Check the code of sample test suite and the test suite snippet to see LibPQ unit tests in action.
Use UnitTest.Run function to run individual test suites (passed by module name or as the test suite record).
Use UnitTest.Discover function to automatically discover and run all test suites from local sources.