Scripts

Top-level script element

A hyperpotamus script instructs the processor how to do your bidding and is usually loaded from a YAML or JSON file. A script can also be dynamically constructed using Javascript code to build out the proper objects/properties, but reading scripts from a file is much more common. While scripts have a specific format and structure, hyperpotamus allows many shortcuts and simplifications so that you can spend less time worrying about the syntax and more time getting stuff done.

The structure of a properly normalized script:

version: # semantic versioning specifier of the required hyperpotamus version
normalized: false
steps:
  - name: step_1
    actions:
      - { action_1 }
      - { action_2 }
      # ...
      - { action_N }
  - name: step_2
    actions:
      - { action_1 }
      # ...
      - { action_N }
  # ...
  - name: step_N
    actions: # ...

As shown here, a script is composed of a single top-level object/element that has the following properties:

The version property

The optional semantic version specifier for the version of hyperpotamus required to run the script. This can be used to ensure that a script is only processed by a specific version (or range of versions) of hyperpotamus with which it is considered compatible. If no version is specified, then any version of hyperpotamus may be used.

The normalized property

The optional normalized property is a boolean value on the script-element that is used to indicate whether or not a script has already been normalized. This property is used internally by hyperpotamus and should be omitted when creating scripts. For more information about normalization, see the section below on normalization.

The steps property

The steps property can either be a single step object or an array of one or more steps to be processed by hyperpotamus. Steps are blocks of actions to be processed and are executed from top to bottom in the order that they appear in the steps array, however, actions can use jump results to cause the processor to skip ahead to another step, loop back to a previous step, repeat the current step, or to stop processing the script altogether. There are also command-line options that can be used to tell hyperpotamus to start processing a script at a specific step.

Shortcut!: The top-level script element is actually optional. For example, if a script does not need to specify a version restriction, then the contents of the steps property can simply be put at the top level of the script. The script normalizer will detect if there is a steps property on the top level object and if not, will auto-wrap the script contents with an inferred script element, nesting the contents as the steps.

Step elements

A step represents a block of actions to be processed. Steps have the following properties:

The name property

[optional] The name of the step. Step names serve a few purposes:

1. The name can be used to identify the step as the target of a jump operation. Jump operations include goto actions, on_success and on_failure properties for any action element, and the next property of an iterate action. Custom extensions and javascript functions can also trigger jump operations.
2. The name can be used as the target for the command-line --init or --start options.
3. The name is useful for documenting the purpose/meaning of the step.
4. The name of a step is also output in any error messages so it can be easier to identify which step is failing when the steps are named.

NOTE: While step names are currently not required to be unique, if you intend to use the step-name as the target of a jump operation, only the first step matching the name will be used. In the future, uniqueness for step names may be enforced. For now, having multiple steps with the same name should be avoided.

The actions property

An action object or an array of one or more action elements to be processed for the step.

Just as the top-level script object can be omitted and the contents auto-wrapped into the steps property, so also, each step element can be elided and the contents will be auto-wrapped into the actions property of an inferred step. In the case where both the script and step elements are elided, an entire hyperpotamus script can be expressed as a single action object, or an array of action objects.

The following scripts are all equivalent:

# Single action
{ action_element }

# Array of actions
- { action_element }

# Single step with a single action
actions:
  { action_element }

# Array of steps with a single action
- actions:
    { action_element }

# Array of steps with an array of actions
- actions:
    - { action_element }

# Top-level script with array of steps
steps:
  - actions:
     - { action_element }

Action elements

Actions represent the individual operations that hyperpotamus should perform. Actions typically serve one or more of the following purposes:

• Sending an HTTP request
• Validating/Capturing data from an HTTP response
• Script flow control
• Modifying session variables
• Prompting the user for input values
• Printing output/saving files

All actions, including the built-in hyperpotamus actions, are implemented via processing plugins.

Actions are a large enough topic that they are covered on a separate page. Please see actions.

Script Normalization

Hyperpotamus runs all input scripts through a process called normalization. Normalization conforms scripts to the standard syntax, expanding shortcuts, renaming elements according to any aliases, adding default values for optional properties, and converting singular elements into an arrays as appropriate.

When a script has been through the normalization process, the normalized property of the top-level script element is set to true to indicate this. When writing scripts, this property should be omitted and hyperpotamus will automatically add it after normalization to prevent further analysis/processing overhead from renormalizing the script if it is to be executed multiple times (for example in a loop or across a .csv file).

You can see the normalized form of any script by using the --normalize option when running the command-line interface. This may give you some indications about how hyperpotamus understood or interpreted your input. Using the --normalize option shows both the YAML and JSON versions of the script.

It is important to note that JSON, which is a sub-set of YAML, is not able to represent some of the richer structures and data-types that YAML is able to convey (such as regular expressions, functions, linked-references, and included files). When displaying a normalized script that contains values that cannot be serialized to JSON, the formatter will do it's best, but values may simply be missing from the displayed output. This means that JSON output is not guaranteed to be "round-trippable", if non-representable elements are present.