Go to: SAFS DRIVER CONTROL, SAFS DRIVER CONTROL POF, Using Variables, Using POF, Using Step/Retry, JSAFS Usage, Service References
Our standard SAFS Driver monitors the value of two predefined SAFSVARS variables:
Custom SAFS Drivers--like those available via Java API for SAFS (JSAFS)--can also take advantage of these SAFS Monitor features.
See the JSAFS Usage section in this document for more details!
The values currently supported for this variable:
| SHUTDOWN_HOOK | Immediately stop runnings tests and shutdown. |
| PAUSE | Pause execution indefinitely; it will be set automatically when failure occurs if SAFS_DRIVER_CONTROL_POF is ON. |
| RUNNING | Continue or Resume running tests. |
| STEP | While PAUSED, execute one record (STEPPING) then re-enter PAUSE mode. |
| STEPPING | Enter PAUSE mode at the end of the current record. |
| STEP_RETRY | While PAUSED, execute current record again (STEPPING_RETRY) then re-enter PAUSE mode. |
| STEPPING_RETRY | Enter PAUSE at the end of the re-tried record. |
The values currently supported for this variable:
| ON | Turn on the switch of automatically pausing the test when a failure occurs. |
| OFF | Turn off the switch of automatically pausing the test when failure occurs. |
The SAFS Monitor UI provides easy access for changing the value of SAFS_DRIVER_CONTROL and SAFS_DRIVER_CONTROL_POF, but the variables can also be changed from any process having access to STAF on the target machine. That means a tester can change these from the command-line, a program, a running SAFS test, or even a remote machine properly configured with STAF and granted appropriate STAF Trust levels.
This provides an array of opportunities when needing to debug running SAFS tests.
For example, a tester can PAUSE the running test and:
The tester can essentially query the state of the entire SAFS framework.
The test can be paused via the PAUSE button on the SAFS Monitor. A running SAFS test can also initiate a PAUSE by setting the appropriate SAFS_DRIVER_CONTROL value:
Having PAUSED the test via the SAFS Monitor, via the running test, or any other mechanism; the user can now evaluate the state of the test. Typically this is done by reviewing the SAFSVARS variables thru a DOS Command window.
(SAFS Monitor will likely offer this feature automatically in a future upgrade.)
To get an idea on accessing SAFSVARS from the command-line, type the following and press ENTER:
The key SAFSVARS command we would most likely use for debugging as we step through a test would be SAFSVARS LIST. This will give us a snapshot of the value of every variable currently known to SAFS:
The information shown is the state of all variables and status for the test record that just finished executing.
If desired, with SAFSVARS SET we can create new variables or change the value of existing variables. Notice when referencing variable names directly with the SAFSVARS service we do not use the caret (^) symbol used in SAFS test tables.
A common practice at this point is to use SAFS Monitor to STEP through the test one record at a time monitoring the variable values with SAFSVARS LIST to make sure they are what we expect them to be.
In the SAFS Monitor UI, this is a checkbox representing whether the test will PAUSE when a failure occurs.
When PAUSED, each token of the current test command, no matter whether failed or not, is loaded in the Watch table as shown above. The Watch table can be hidden or shown by the 'Watch/Edit' toggle button. The tokens in white are editable. The remaining tokens in grey are not editable.
This allows the tester to debug a failing test step by (re)trying it with different values until the desired results are achieved.
Custom SAFS Drivers--like those available via Java API for SAFS (JSAFS)--can also take advantage of these SAFS Monitor features, if they choose to set/get the values of these same predefined variables.
JSAFSDriver jsafs = new JSAFSDriver("JSAFS");
...
// find out the current SAFS Monitor state:
String monitor_state = jsafs.getVariable(DRIVER_CONTROL_VAR);
...
// force a PAUSE that the tester can interactively change to RUN when ready
setVariable(DRIVER_CONTROL_VAR, JavaHook.PAUSE_EXECUTION);
...
// programmatically enable PAUSE ON FAILURE that the tester can later disable
setVariable(DRIVER_CONTROL_POF_VAR, JavaHook.POF_SWITCH_ON);
Valid values for 'SAFS_DRIVER_CONTROL' are shown at top and can be referenced via JavaHook constants.
The same is true for 'SAFS_DRIVER_CONTROL_POF' values.
By default, a JSAFSDriver instance automatically supports and performs these SAFS Monitor functions whenever a DriverCommand or ComponentFunction is executed. A developer can disable these features by setting the jsafs.useSAFSMonitor field to 'false'.
By default, a JSAFSDriver instance that detects a SHUTDOWN request when running a DriverCommand or ComponentFunction--whether it was user-initiated through the SAFS Monitor interface or code-initiated by the developer--automatically attempts to close all SAFS Engines and services. It also attempts to run the JVM finalization routines and force a System.exit(0) -- a complete JVM shutdown. A developer can disable the JVM finalization and shutdown feature by setting the jsafs.systemExitOnShutdown field to 'false'.
The developer can also insert a call to the JSAFSDriver.checkSAFSMonitorStatus function at arbitrary points in the code to take advantage of these SAFS Monitor features.
Remember, you can always refer to the available commands for each service at the command-line by using HELP, as shown for SAFSVARS below:
To get a list of all available STAF services you can always ask for the SERVICE LIST:
Documentation for the core STAF services can be found locally in the C:\STAF\docs installation directory, or you can look in the STAF archives for older STAF V2.6.11 documentation. Testers can also refer to the STAF website for the latest STAF documentation if using later versions of STAF.
Go to: TOP, SAFS DRIVER CONTROL, SAFS DRIVER CONTROL POF, Using Variables, Using POF, Using Step/Retry, JSAFS Usage, Service References