Addons/Test scripts
Test Scripts for Addons
Including test script(s) with your addon:
- helps prevent the introduction of bugs during development
- makes it easier for new developers to contribute changes without fear of screwing up
- provide valuable example data and usage to users
The WhyTestCases page on the APLWiki examines the benefits of test cases in more detail.
It is recommended that a test script be included with every addon published in the JAL. The test script should be run and complete successfully before an update is committed to the JAL SVN repository.
This page is an attempt to provide some guidance for including test scripts as part of an Addon.
Conventions
The test script should be named test_<addonname>.ijs , for example the test script for the tables/csv addon is named test_csv.ijs .
The test script should assume that the addon has been loaded.
The canonical form is any number of J sentences, followed by a test verb that contains a sequence of asserts. At the end of the script is the call to the test verb. See the following examples:
Single test script scenario
If you only have one test script, then it should be formatted as described above, see the example below.
The instructions in Note are targeted at users who install your addon and want to check that it is working properly. Using Note is preferable to NB. because a user is able to place their curser on the line and use Ctrl+r to run the sentence. [{{#file: "test_csv.ijs"}} Download script: test_csv.ijs ]
NB. test csv addon Note 'To run all tests:' load 'tables/csv' load 'tables/csv/test/test_csv' ) NB. ------------------------------------------------------- NB. create nouns for testing d=: 4 5?.@$ 200 NB. simple numeric NB. ------------------------------------------------------- NB. verbs for testing test=: 3 : 0 NB. ..... assert. d -: 0".> fixcsv makecsv d NB. ..... ) smoutput test''
Multiple test script scenario
For larger addons, or addons with distinct components, you may wish to have a separate test script for each of those components. In this situation you may want to create a separate sub-folder for your addon that contains test_{addonname}.ijs, each of your test scripts and any other supporting test files. You can then reference your individual test scripts in test_{addonname}.ijs as shown in the example script below.
The verb loc returns the path of the script that calls it, so as long as you can load the test_{addonname}.ijs and your test scripts reside in the same folder, they should be loaded with no problem. This is especially useful if you keep the development version of your Addon scripts in a separate location to your installed version (i.e. not in the ~addons system folder). It means you can call the development versions of the tests when you are developing and you (or other users) can load the installed version of the test scripts when using the installed Addon without needing to change anything. [{{#file: "test_tara.ijs"}} Download script: test_tara.ijs ]
NB. test tara addon
Note 'To run all tests:'
load 'tables/tara'
load 'tables/tara/test_tara'
)
loc=. 3 : '> (4!:4 <''y'') { 4!:3 $0' NB. Returns path of script that called it
PATH=. getpath_j_ loc''
NB. -------------------------------------------------------
NB. scripts for testing
load PATH,'taratest.ijs'
load PATH,'taratest2.ijs'
The files taratest.ijs and taratest2.ijs should have the same format as the script in the single test script example (test_csv.ijs).
Using with Project Manager
If you use Project Manager to build your source scripts then the generic project test script below (the script that runs when you hit the "Test" button in Project Manager) should work as is for all your addons. Just create a file with the following content in the same folder as your test script(s) and tell Project Manager that it is the Test file (Project tab|Add|Test|OK). [{{#file: "test_src.ijs"}} Download script: test_src.ijs ]
NB. Builds and loads project, then
NB. loads test_{addonname}.ijs located in the same folder as this script.
buildproject_jproject_ ''
loadtarget_jproject_ ''
TestPath=. getpath_j_ TESTFILE_jproject_
TestFile=.'test_',(#@getpath_j_ }. ]) TARGETFILE_jproject_
cocurrent 'base'
load TestPath,TestFile