Test cases

Running the test cases is of course not something ordinary users do, but there might be scenarios when you want to run them anyway, so here we go.

To execute the test cases no intimate knowledge of the test framework is required. However, if you wish to use one of the more sophisticated features of the test framework then you are advised to look at https://github.com/aplteam/Tester/

Preconditions

Of course you have to fork the acre project from GitHub and open it by itself before you can run the test cases.

In a second step you must call:

#.acre.AcreDesktop_Testcases.Tests.Prepare

This function establishes some helpers and references in the #.acre.AcreDesktop_Testcases.Tests namespace you will need.

Running the test cases

Note: in order to keep the statements simple we assume that you have executed this:

)cs #.acre.AcreDesktop_Testcases.Tests

If you want to run the test cases then you have several choices:

Run all test cases and get either a 1 (success) or a 0 (failure) as result.

The syntax is simple:

(rc report dummy)←Run

• rc is a return code with 0 indicating success.

• report is a vector of text vectors with one item per test case.

• dummy is just ⍬; other Run* function return a ref pointing to the GUI created by Tester, but Run does not create a GUI.

Note that Run is not for integrating the tests into an automated build process; see RunBatchTests for this. The difference is that RunBatchTests will only execute test cases that do not require a user sitting in front of the monitor responding to questions and prompts.

Run might or might not interact with the user, depending on the test cases to be executed.

Run all test cases with the debug flag set.

This makes any test cases crash the moment it hits an unexpected result. This is the function to call if you want to investigate something that goes wrong.

(rc report ref2GUI)←#.acre.AcreDesktop_Testcases.Tests.RunDebug 0

The function takes a boolean as right argument which decides whether the test framework should stop just before any test case is executed (1) or not (0). That allows you to easily trace through test cases if you wish so.

Notes:

• RunDebug, RunThese and RunBatchTestsInDebugMode both create a GUI to keep the user informed about the progress. These functions both return a ref pointing to the GUI rather than ⍬ as third element of the result.
• After running the test cases with either RunDebug, RunThese or RunBatchTestsInDebugMode the GUI stays around only until the first garbage collection is executed by the interpreter (which you can enforce by executing ⎕WA in the session). If you want the GUI to stay around until you explicitly close it then assign the reference returned as third element to a variable.

Run all test cases and get either a 1 (success) or a 0 (failure) as result but without user interaction

The syntax is the same as with the Run function:

(rc report ref2GUI)←RunBatchTests

Notes:

• This is for integrating the tests into an automated build process: RunBatchTests will not execute any test cases that require a user to interact with them.

• RunBatchTestsInDebugMode behaves similar to RunDebug: in case it hits an unexpected result it crashes. That allows you to investigate on the spot.

Execute just one (or some) particular test cases

If you are working on a particular test case or on a specific part of your application that is tested by one (or a few) test cases then you might want to execute just those rather than the full test suite.

This can be achieved by calling RunThese which accepts different arguments.

The acre test cases are split into groups, and numbered within a group. If you want to, say, execute all test cases that belong to the "Erase" group:

#.acre.AcreDesktop_Testcases.Tests.RunThese 'Erase'

This executes at the time of writing the test funtions Test_Erase_001, Test_Erase_002 and Test_Erase_003.

If you want to execute just the test cases 4 and 5 of the "CreateProject" group:

#.acre.AcreDesktop_Testcases.Tests.RunThese 'CreateProject' (4 5)

Finally you can specify negative numbers: that will let RunThese stop just before that test case is executed, allowing you to trace through the test cases.