Skip to content

Actions

Jump to bottom Edit New page
Phillip Markert edited this page Nov 22, 2016 · 35 revisions

About Actions

Actions are the processing commands that get executed by hyperpotamus. Actions can be used to make an HTTP request, validate an HTTP response, capture data, print or output data, manipulate session variables, or control script execution. It is also pretty easy to write action plugins using javascript. For more information, see writing action plugins.

For a given step, actions are executed in the order that they appear under the .actions property. If an action fails, then processing is halted and an error is raised. Conversely, when an action succeeds, processing continues with the following action until the last action in a step is completed. When there are no more actions for the current step then the step is complete and processing moves to the next step in the script.

Each action element uses a named property to identify which plugin handles the action. The name of this top-level property maps to the name of the plugin that will process the action. See the section Identifying Actions

For example, the following script uses the set, compare, and the print actions. equals is an alias for the compare action:

- actions:
   # using the "set" action, which accepts an object
   - set:
       question: "Is this easy?"
       answer: "yes"

   # using the "equals" alias for the "compare" action, which accepts an array of values
   - equals: [ "yes", "<% answer %>" ]

   # using the "print" action, which accepts a single value
   - print: "Q. <% question %>. The answer is <% answer %>!"

The specific properties/values supported for each individual action are completely dependent upon the specific plugin that processes the action. Some actions use a single property value which may be a string, a number, or an array of values. Other actions make use of nested objects with multiple properties. To understand the format of a particular action, read the documentation about that action under the action reference.

Property value interpolation

Any of the values for the properties of an action may contain dynamic <% macro %> values that will be interpolated by the hyperpotamus engine. This allows some very powerful techniques to be used with the action configuration.

In the example above, the interpolation engine will replace the <% answer %> and <% question %> macros with the proper session data values before the action is processed. After interpolation, the last two actions will be processed with the following the configurations:

   # using the "equals" alias for the "compare" action, which accepts an array of values
   - equals: [ "yes", "yes" ]

   # using the "print" action, which accepts a single value
   - print: "Q. Is this easy?. The answer is yes!"

The result of macro expressions is a string (textual) value. Macro interpolation is not limited to replacing simple values, but also supports some very powerful transformations through the use of pipes. Object references <%! ... %> can be used to provide raw/typed access to session data, such as numbers, dates, arrays, and objects in a value expressions.

For more information, see interpolation and pipes.

Standard action properties

Even though each action has properties that are specific to the processing plugin, there are some standard properties that can be utilized on any action.

on_failure/on_success

These properties can be set on any action to modify the processing flow. Each of these properties can specify an action or an array of actions to be processed if the parent action was successful or not. If the on_failure property is specified and the action fails, the normal error handling is suspended and the on_error actions are processed instead.

The value can either be a simple string, an action, or an array of actions. If the value of an on_success or on_failure property is a string, then it is assumed to specify a jump/goto target and will be normalized into a goto action.

- actions:
   # This action will fail and jump to the 'report' step below
   - equals: [ true, false ]
     on_failure: 
       goto: report

- actions: 
   print: This step will be skipped

- name: report
  actions:
   - print: Confirmed - true does not equal false.

debugger: true

Sometimes you may need to debug your hyperpotamus script to figure out why something is not working as you expect. In those cases, you can run hdb (the hyperpotamus debugger command-line), which will run hyperpotamus attached to the node.js debugger allowing you step through the code. There are a lot of steps to get to the right spot to troubleshoot a specific action. As a convenience, if the debugger property of any action is set to true, then a breakpoint will be hit just before that action is processed. For more information about debugging hyperpotamus scripts with the hdb command-line utility, see Debugging.

- print: This action will be debuggable
  debugger: true

Identifying actions

When the processor encounters an action element, it uses the names of the first-level properties on the action (minus the standard properties) to identify which plugin should process the action. Any first-level property names are matched against the names of all loaded plugins. If no matching plugins are found or if more than one plugin is found, then an error is raised and processing stops.

As a general practice, all of the data to configure an action should be nested underneath a single property that matches the plugin's name. There are a few notable exceptions to this "all data under the action property" rule for the sake of keeping simplified syntax, but any first-level properties that a plugin works with have the potential to cause naming conflicts with future plugins. Here are some of the actions that have additional first-level properties (in parenthesis).

Types of actions

Actions usually fall into one of the following categories:

Session variable manipulation

Actions can be used to calculate, modify, or set variables within the session.

Script control

Actions can be used to control the flow of the script processor. Examples of control actions include setting a session variable to a specified value, iterating one or more requests across an array, saving the contents of a file, emitting some text for output/capture, or other miscellaneous actions.

Logical and conditional

Actions can be used for logical and conditional tests within a script.

Reporting and output

Actions can deliver output to logfiles, the console (stdout), or data files.

Sending requests

The request action sends an HTTP request.

Validating responses

The response property of the request action allows other actions to be performed on the response that was received. Actions can check that certain expectations about an HTTP response were met such as the HTTP status code, the presence or a specific value of an HTTP header, or checking the content within the body of the response. Examples of response validation actions include:

Data capture

Actions can also be used to capture data from the responses. Captured data is added to the current session for use in later requests and actions. Captured data might come from the HTTP headers or from the content body of the response.

Hyperpotamus Documentation - home

Index

Clone this wiki locally