Good practices for using procedures within gp_test scripts

Did you know that there are some good practices for using procedures within gp_test scripts?

Do:

• Define and reuse standard procedures that do one specific job well, where “standard” means usable across multiple test cells or multiple tests.
• Make sure to clearly identify and limit the number of external dependencies, for example:

• • use @STABILITY_SPECS and @LIMIT_SPECS features within a gp_test procedure rather than relying on externally defined running averages or limit_specs.
  • Use @CREATE_VAR for temporary variables used within a procedure rather than defining the variables in gen_labels.

• At the start of the script document:

• • a procedure’s purpose and intended scope of use (and limitations).
  • changes to the procedure with date/time and reason for change.

• Place comments in procedures about the reasons for various elements (comments on “why” are generally more useful than those on “what” or “how”).
• Keep flow through the procedure as linear as possible, i.e. avoid mode-to-mode jumps other than skipping one or more modes and sequence the mode numbers and order in the file consistently with the normal flow through the procedure.
• Consider whether a procedure is a “root” procedure (i.e. highest level that is started with ‘nt’) vs. a sub-procedure.  Root procedures should not use RETURNs, as there would be no script to which to RETURN.
• Note that there are some procedures such as gp_shutdown and gp_emergency which don’t RETURN.  Also, procedures called from @GLOBAL_EVENTS and @UNIVERSAL*_EVENTS usually don’t RETURN.  For example, typically the “test” instance of gp_test handles (or should handle) ‘emergency’ and ‘abort_limit’ events in @GLOBAL_EVENTS by triggering gp_emergency and gp_shutdown respectively.
• Make use of display strings to indicate status of procedure to users, especially when handling abnormal conditions, such as abnormal test termination due to some discovered test article or test equipment fault.  Provide clear information and guidance to test cell operators and support personnel in these cases.
• Make use of test tables (aka “furball” files), but keep it simple and well defined:

• • Document the required columns of the test table that the procedure needs.
  • Use at most one active test table per procedure.

• Use “ck” to check for syntax errors, missing variables and more.
• Validate your procedure operates as expected prior to launching it into a long / un-observed automated test.
• There may be multiple gp_test instances running and most procedures apply to only one specific instance.  Use the @INSTANCE keyword in each procedure to define which instance can use this procedure and prevent its use in other procedures.  For example, a smoke meter management instance should never call a procedure which manages the engine, such as “gp_shutdown”.
• Use trace files and ‘hold’, ‘release’, ‘adv’ commands to troubleshoot a gp_test procedure.  The trace file location is defined in the gp_test header for each instance of gp_test that is running, typical /specs/gp/TRACE for the main test procedure
• See the CyFlex User Manual chapter on gp_test for more information.

Don’t:

• Change a procedure without assessing impact on any procedures that call it.
• Use multiple nested loops in one procedure.
• Start a new service (CyFlex program) in a procedure without determining where that same process will be terminated and factoring that into your overall test, for example use of background and auxiliary tasks started by a gp_test procedure should have a means to be ‘cleaned up’ at an appropriate time.
• Use a procedure from another test cell or previous test setup without checking that its contents are compatible with the present test configuration and appropriate to the test needs.