Tester Prototype User Manual =options no-nums ===Foreword This is a basic manual for the REBOL case test tool called Tester. The purpose of this tool is to create test cases for your program code which can be run as many times as you want to let you very quickly find bugs in the code, you may not otherwise have found. Tester can be compared to the Flight Data Recorder or black box on airplanes, which record everything. The data recorded by them are studied after a plane crashes to understand why it crashed. Depressing as it may sound, this analogy fits well with Tester, to help you understand why your REBOL scripts and functions don't work correctly. There are a few things to understand about Tester before we move on: *Tester is not a performance measuring tool. *Tester does not record other than what you ask it to record. *Tester doesn't provide access to interactive debugging. Once the test is started, it will continue at full speed until no more tests are available in the test list. *Tester is not a traditional step-by-step debugger, so if your code consists of multi-layered loops that are run millions of times, Tester may not be suited to debug that. *Tester is a concept prototype at this point with many things that might seem stupid or backwards, as it was originally designed as a tool for me alone. *Tester is principally not very complex. It could have been written by anybody with a fair bit of REBOL knowledge. ===Installing Tester Tester consists of the tester.r script, toolbar.r and list-view.r, always in their latest version from: http://www.hmkdesign.dk/rebol/ The simplest way os to run it directly from the site: http://www.hmkdesign.dk/rebol/tester/tester.r This makes it possible to create an icon for it in the Rebol/View desktop, which I think also is the best thing to do. Tester downloads some toolbar images, list-view.r and toolbar.r and then should start up. If a window like this comes up: =image tester3.png Then you can begin! Tester creates a configuration file in the same directory called tester-cfg.r. Tester automatically saves to this file very frequently, so there is no Save button in Tester. ===A Tour =image testerexplainsmall.png
Larger image here
Tester consists of the main window and a few sub-windows that you can open at any time and keep open if you desire. ---Sub Windows +++Test List =image testlist.png This is where you enter the tests you need to perform. It's opened by pressing the Tests... button in the main window, or by double clicking an entry in the result list. +++Watched Variables =image watchvars.png This is where you enter REBOL variables that you need to watch during the test. It's opened by pressing the Watch... button in the main window. +++File Watch =image filewatch.png This is currently a dead window, but the intent is to let you watch file contents the same way as you watch variable contents. This is not implemented at this time. +++Functions =image functions.png This is a list of system/words and acts as a code viewer. It has no practical purpose other than let you view the code of the functions. I have a habit of forgetting the arguments to various functions, so I tend to use this as a function reference. In the future this window might grow into an actual code editor. +++Variable Viewer =image varviewer.png This window simply lets you view the contents of a watched variable, so you can study larger objects in a comfortably big window. It can be brought up by double clicking a variable in the watched variables list. +++Entry Result Viewer =image entryresultviewer.png This window lets you browse the full contents of one of the text areas in the right side of the main window. From within the window, you can navigate back and forth in the results. It can be activated by pressing the Full button above the text area you wish to view. ---Basic Workflow =image procedure.png #First add your script if you have one to test #Add/modify the tests that need to be performed #Add/modify the variables you need to watch #Add/modify the function marks you need #Run the test #Study the output #Repeat the first step ===Simple Tests To use it, you can either test it with existing program code or just create stand alone tests. You can write code and test it directly in Tester. This is easier to do at first to understand the concept of Tester. A range of simple tests can be written to figure out how Tester works. To do this, the Test List, which resides in a separate window must be opened. This is done by pressing the Tests... button. In this window, you'll have a list view and a code window. To add a simple test, do the following: \group #Press Add #Type in your test code. It doesn't matter if it returns anything, but a return value will be registered. Let's type in: \in var: 3 /in #Tab out of the code window. This stores your test. /group Now we have one single test. We can now go back to the main window and press Run Test You should notice the result list now sporting a single entry with your code and the status value should be OK. All that happened was that the code you entered, was run and the result was that it didn't produce an error. This was stored in the result list. Nothing more. Let's add some more tests: \group #Go back to the Test List window #Press Add #Enter something different, such as: \in var: 5 /in #Then tab out again. Now press Copy to duplicate the entry. Go into the code window and change the code to: \in var: "Hello World!" /in /group After storing the result, go back to the main window and press Run Test again. Now there should be 3 entries in the result list all with the status OK. ---Watching Variables When running these three tests, all that happens is equivalent to saying: var: 3 var: 5 var: "Hello World!" One of the key advantages of Tester is that when you've run these three tests, each step can be stored, so you can go back and track what value var had at a particular point even when var has been overwritten many times. To monitor var, you need to enter the word in the Watch List: #Press Watch... and the Watch Variables window should open. #Press Add to add an entry for editing. #Type in "var" without the quotes and press Enter. #Go back to the main window and press Run Test. =image watch1.png The variable should now appear in the Watched Variables list in the right side when you click an entry in the result list. Click another and the contents of the list changes to fit whatever you set var to at that particular test. ===Testing Program Code To test existing program code, you must load it before the test is run. This is done by entering the path to the source code. When the path is specified, the code is loaded every time you press Run Test. The code is loaded into the same process as Tester (not launched!) and then run. It's very simple and has limitations, but for simple testing of functions, this works quite well. After the code is loaded and run, the tests are performed. \note Stability Since Tester is in its infancy, it's easy to knock over. The code is not wrapped in a context, and so if you accidentally overwrite a Tester variable, Tester might run haywire or crash. /note ===Function Marks Function marks is simply putting in the function called MARK inside your own program code, similar to when using PROBE to read out variables from the code. The variable is passed through the function in the same manner as PROBE, so it can be dropped in anywhere PROBE can. Instead of delivering the result on the console, MARK puts the result in the Function Marks list in the lower right corner of the main window. ---Studying Program Flow By letting MARK label parts of the code, you can study the program flow of your code for a single test. The basic syntax is: mark