The AppleScript Runner HyperCard stack is designed to run a series of scripts and compare the results returned against pre-specified values. You can use this stack as an automated test tool to verify your application’s implementation of AppleScript.
One caveat up front: be sure to run your tests from a backup stack. The will prevent you from winding up with a stack which has become corrupted in the process of running a series of scripts, especially if a crash or hang occurs. To be certain, you may wish to check the “Run a Copy” check box on the Contents card as described below before running a set of tests.
The stack requires HyperCard 2.0v2 (or later) with a Finder partition of >= 1000k installed.
There are four main sections of the stack: the Contents card, the test cards, the Failure List card, and the Utilities card.
- Contents card -
After an opening splash screen, the Contents card is the first card you’ll see when you open this stack. Use this card to view a list of all the tests you’ve created, and to control the running of every test in order. To go back to this card from elsewhere in the stack, simply click the “contents” button.
The button labeled “First Test” takes you to the first test card in the stack. The “Last Test” button takes you to the last test card. This button is useful for picking up from where you last left of.
The “Utilities” button takes you to a card which contains some useful buttons as described in the Utilities card section below.
To update the view of all of your tests by their titles, click on the “Update Test List” button. To go to a test listed here, simply click on its title.
To run all of the tests in the stack, click on the rather large “Run all Tests” button. This button will run every test the number of times specified by which radio button is selected to its right. To run all of the tests once, select the “Run Once” button. To run all of the tests three times, select the “Run 3 Times button. To run every test a specified number of times, select the “Run ‘n’ Times” button. You will be asked to specify how many times you’d like to run the whole suite. If you have selected the “Run Forever” option, the suite will run until you type command-period, to abort HyperCard’s script.
If the check box labeled “Compact Stack First” is checked, the stack will get compacted by HyperCard before all tests are run. This is only useful if you wish to check that the stack hasn’t been corrupted for some reason before running. In most cases, compacting a stack will indicate this.
If the “Run a “Copy” check box has been checked, a copy of the stack will be made and tests will be run from it instead. It’s very important that one way or another, you run your tests from a backup since stacks do get corrupted occasionally—especially when crashes with developmental software are a possibile.
The “Close All Components Every Test” check box will make your stack run slower if no other AppleScript components, such as Toy Surprise, are already open. By default, the stack keeps a component open throughout a whole run of tests unless this box is checked.
The Default Application Name field stores the name of a default application you’d like to target “tell application” blocks to. This only works with tell blocks of the following form “tell application <DefaultApp>.” All other “tell application” blocks are unaffected.
- Test Cards -
Each test card consist of four fields and a number buttons. To create a new test card chose “New Card” from the Edit menu or type CMD-N. To delete a card chose “Delete Card” from the Edit menu or type CMD-delete key. If you wish to delete a range of tests, there is a button on the Utilities card which will allow you to accomplish this.
The field at the top each test card labeled “Test Name” is where you enter the name of this test. It’s very important that you name your tests since it’s their names that appear in the contents field of the Contents card and the failures field of the Failures card.
The next field down is where you enter your test script. There are actually two fields here sharing the same location on the card. One field holds the script you type and the other holds the unparsed script as it’s returned from AppleScript. When you click in the parsed script field, the editable script field automatically comes to the front. You can toggle back and forth between these two fields by clicking the button which is alternately labeled “Show Parsed” and “Show Source.”
The field labeled “Expected Result” is where you enter the last result which you expect to be returned by your script. The field labeled “Result Returned” is where the actual result appears after the script is run. When a test is run, the contents of both of these fields are compared. If they are not exactly alike, the test fails. Be especially aware of placing extra returns in the Expected Result field since HyperCard will automatically add returns up to any length of blank space you click on in a field. To remove all extra returns, select from end of your exepected result to the end of the field and type the delete key.
If the “Manual Test Only” box is checked, this test will be completely ignored when a whole suite of tests is run. Check this box if you have a test which requires human input of some sort. A test marked this way will still run when the “Run this Test” button is clicked.
Check the “Skip this test, mark as failed” box if you wish to skip a test for some reason and still want it to appear in the list of failures. A test marked this way will still run when the “Run this Test” button is clicked.
The test number field indicates what the current number of this test is. Since this field is updated automatically, the number of a particular test might vary if the cards are sorted or cards are some are deleted or added to the middle.
The arrows in the upper right hand corner of the card take you to the first test card, the previous test card, the next test card, or the last test card, respectively.
The “Failures” button takes you to a card which lists all of the failures which occurred the last time all the tests were run.
The “Utilities” button takes you to a card which contains a number of useful buttons.
The “Contents” button takes you to the Contents card where you may either run all of the tests in the stack, or just view the list of all tests and go to any of them individually.
The “Run this Test” button will run the script contained on this card. Below this button in a field labeled “Pass/Fail:”, the result of a comparison of the “Expected Result” and “Result Returned” fields is displayed. If the fields match, “Pass” is displayed, otherwise “Fail” is displayed.
Clicking the “Find Failure” button takes you to the next card which displays a result of “Fail.”
Clicking the “Next Man. Test” button takes you to the next card which has the “Manual Test Only” box checked.
Checking the “Mark Card” check box will mark this card. Clicking the “Find Marked” button will take you to the next occurrence of a marked card.
In the lower right hand corner of each test card is a field which indicates the actual number of the this card in the stack and one that indicates the version number of this stack.
- Failures Card -
The Failures Card is where result of a run of tests is recorded. Any failed test that is listed can be clicked on in order to go to it.
This card also includes buttons for printing or running all tests which have the word “Fail” in their Pass/Fail fields.
- Utilities Card -
This card contains a number of useful buttons for accomplishing various tasks.
The “Delete Range of Cards…” button deletes a range of test cards starting and ending at any points you specify.
The “Sort Tests” button sorts all test cards of the stack by their title.
The “Print all Tests” button prints all test cards in the stack.
The “Print Failed Tests” button prints all test cards which have the word “Fail” displayed in their Pass/Fail field.
The “Import Tests from Stack…” button imports tests from a stack such as this one to the end of the current stack. Please note that a temporary text file named "temp" and some random number (e.g. temp395219) will remain which you may delete as you wish.
The “Export Tests to Text” button exports all of the tests from the current stack into a text file.
The “Import Tests from Text” button imports all of the tests from a text file saved with the “Export Tests to Text” button.
- Nota Bene -
If you run into any problems with the stack or if you wish to offer suggestions, please link me at BONGIORNO1.
