Developer Commands (non-menu commands)
The following commands are intended to aid with development and testing and are not normally for general use. They are not mapped to any buttons but may be accessed by typing the command into the register,
ResetCalculator
This command resets the calculator back to the state of the calculator when it is first installed.
RunTests
This command recursively runs all calculator tests in the designated test folder and sub-folders (see below for more about test types). Results are displayed in a dialog box where individual test result lines can be clicked for more information. This command should be run against the full test suite before every release.
SetTestFolder
Sets the test folder for the RunTests command.
NumberTest/StringTest/CommandTest
Saves off the current state of the calculator as a test file including results for each stack entry. (Note: results are not normally part of a save file and are normally recalculated whenever a calculator state is loaded.) When the test file is run, the new results on the calculator will be checked against the saved results for any differences and if there are any differences it is assumed that an error has been introduced into the calculator. Note that it is important that all of the results displayed on the calculator be checked for correctness before the state is saved as a test.
How to use: Before the NumberTest etc. command is used, "SetTestFolder" should have been used to set where the test will be saved. Also, the top stack entry should be a string indicating the name of the test to be saved.
Test Formats: Different test commands save off the test results in different formats. In general, the NumberTest is usually the best option, but other options can be helpful in some circumstances.
- NumberTest
- Saves off calculation results as numbers when possible, strings otherwise. Numeric results are least prone to becoming invalidated by inconsequential changes in output format, but test result output will fall back to strings for results that aren't numbers (e.g. in exact mode a valid result may be "1/3", results may be sets, strings, etc.).
- StringTest
- Saves off all calculation results as strings.
- CommandTest
- Saves off all calculation results as a set of commands that will recreate the exact result format (e.g. 45.6 will be saved as 45.6, 1/3 will be saved as 1 3 /).
Admin
This command checks a numeric code on the top of the stack. If the code is correct, it puts the calculator in Admin mode and it is then possible to run exception and crash testing.
Exception and Crash Testing
These commands only work in Admin mode (see above).
These commands are intended to test exception handling in the calculator. They cause various types of exceptions to appear in various stages of calculations. All of the exceptions should result in an error message to the user and some sort of error recovery attempt. UserExceptions result in a fairly minimal error message to alert the user to their mistake. The other exceptions indicate some sort of program error and the error message may include exception data, a call stack dump (in debug mode), and a recommendation to report the error to the developer.
- ThrowUserException
- Causes a user exception to be thrown in the calculation of the Expression result. These exceptions can occur when the user tries to do an invalid calculation (for instance, dividing two string values or performing add on an empty stack). These exceptions are expected to occur and recovery should allow the user to continue with normal operation after the last operation is automatically rejected.
- ThrowException
- Causes a generic exception to be thrown in the calculation of the Expression result. These sorts of exceptions should not occur in the calculator and represent an unforeseen problem or situation that wasn't handled correctly. The calculator attempts to handle these exceptions by rejecting the last entry.
- ThrowProgramException
- Causes a program exception to be thrown in the calculation of the Expression result. These exceptions can be thrown in response to caught exceptions or they can be thrown when a check inside the program unexpectedly fails or a method is called that shouldn't have been. The calculator attempts to handle these exceptions by rejecting the last entry.
- ThrowStackEntryException
- This causes a stack entry exception to be thrown when a new stack entry is added to the UI of the stack. The new stack entry will remain but it will show a display error instead of the entered expression.
- ThrowUIException
- This causes an exception to be thrown when rendering an expression in the UI. Because UI Exceptions only show up at the application level and because they can indicate an unrecoverable state in the UI, this exception will result in an attempt to recover by restarting the app with the last stack entry deleted.
- CrashTest
- Causes the app to crash. This should cause a crash report to be sent for diagnostics.
All of these exceptions should be tested by entering them directly in the calculator and also by putting the throw commands into .vrpn files to test exception handling when loading calculator state. Note that if an error occurs in the saved calculator state, the old state will be rejected, the calculator will be restarted without the saved data, and the user will be given the option to save off the rejected state data for analysis.