Class: Inferno::CLI::ExecuteScript

Inherits:
Object
  • Object
show all
Defined in:
lib/inferno/apps/cli/execute_script.rb

Overview

Orchestrates multi-session Inferno test runs from a YAML configuration file.

YAML format:

sessions:                                  # Controls the creation of Inferno sessions for the execution
                                           #   a session for each indicated suite will be created and
                                           #   a successful run will have the expected results for all sessions.
  - suite: my_suite                        # internal ID, title, or short title
    name: my_name                          # optional; used as key in multi-session
    preset: my-preset                      # optional; internal ID or title
    suite_options:                         # optional; option_key and option_value can be the
      option_key: option_value             #           internal values or the displayed titles

comparison_config:                         # optional; Controls the comparison of actual results during a run
                                           #    to the expected results for each created Inferno session.
                                           #    When the configured expected results file for a session does
                                           #    not exist, the run will be considered a failure and the expected
                                           #    results file will be generated using the results from the run.
                                           #    Developers are responsible for verifying that the results match
                                           #    their expectations before committing those expected results.
                                           #    When expected results are present, they must match for the run
                                           #    to be successful. When the results for a session do not match
                                           #    the expected results, an actual results JSON file and a CSV diff
                                           #    are written to the directory of the expected results file for
                                           #    use in evaluating the failure.
  normalized_strings:                      # optional; global normalization rules applied to
    - "http://my-server.example.com"       # both expected and actual before comparing.
    - "http://other-value.example.com"     # plain string: replaced with <NORMALIZED>;
                                           # URL-encoded form is also replaced automatically.
    - "/code_challenge=[A-Za-z0-9+\\/=_-]{20,}/"  # regex string (wrapped in /…/): compiled
                                           # to a Regexp and replaced with <NORMALIZED>.
                                           # Supports flags: /pattern/i, /pattern/m, etc.
                                           # URL-encoded form is NOT auto-replaced for regex.
    - pattern: '/code_challenge=[A-Za-z0-9+\\/=_-]{20,}/'  # hash form: use when you need
      replacement: '<CODE_CHALLENGE>'      # a named placeholder instead of <NORMALIZED>.
    - patterns:                            # 'patterns' (plural) shares one replacement
        - '/code_challenge=[A-Za-z0-9+\\/=_-]{20,}/'  # across multiple patterns.
        - '/code_verifier=[A-Za-z0-9+\\/=_-]{20,}/'
      replacement: '<PKCE_VALUE>'

  # Single-session scripts: expected file config lives directly under comparison_config.
  expected_results_file: expected.json     # optional; relative to yaml file; defaults to
                                           #   <yaml basename>_expected.json
  alternate_expected_files:                # optional; tried in order; first matching wins
    - file: alt_expected.json              # required; relative to yaml file
      when:                                # required; all conditions must match (AND logic)
        - field: inputs.url                # required: can be inputs.<name>, configuration_messages,
                                           #   or inferno_base_url
          matches: ^http://                # other values are top-level session detail fields.
                                           # Evaluated against GET api/test_sessions/{id}.

  # Multi-session scripts: per-session config is nested under sessions.<name>.
  sessions:
    my_name:                               # matches session name key (sessions[*].name or suite)
      expected_results_file: expected.json # optional; defaults to <yaml basename>_<name>_expected.json
      alternate_expected_files:            # optional; same structure as single-session above
        - file: alt_expected.json
          when:
            - field: inputs.url
              matches: ^http://

steps:                                     # Details the steps taken in the execution of the script
  - status: created|done|waiting           # required; other status values cannot be matched on
    last_completed: "1.01"                 # optional; required unless the status is created
                                           #           can be a full ID, short ID (e.g. "1.01"), or 'suite'
    session: my_name                       # optional; required when multiple sessions to indicate which session
                                           #           can match this step
    action: END_SCRIPT|NOOP|WAIT           # optional; built-in action (case-insensitive)
                                           #           (mutually exclusive with command/start_run)
    # OR
    command: "bundle exec ..."             # optional; arbitrary shell command (requires
                                           #           --allow-commands CLI flag)
    # OR
    start_run:
      session: "my_name"                   # optional; session name or template token
                                           #           (e.g. {session_id}); defaults to current session
      runnable: "1.01"                     # required; can be a short id from the UI,
                                           #           an internal long id, or 'suite'
      inputs:                              # optional; the key must be the internal name
        input_name: "value"                #           for the input
        input_name: "@path/to/file.txt"    #           prefix value with @ to read from a file;
                                           #           relative paths are resolved from the
                                           #           directory containing this script file
        input_name:                        #           YAML mappings and sequences are
          key: value                       #           automatically JSON-serialized, useful
        input_name:                        #           for auth_info and other JSON inputs
          - item1
    timeout: 300                           # optional; seconds to wait for next match (Default is 120)
    next_poll_session: other_name          # optional; switch polling target after command
    state_description: "..."               # optional; logged when step is matched
    action_description: "..."              # optional; logged when step is matched

Built-in action values:

END_SCRIPT  — terminate script successfully
NOOP        — no-op; keep polling with (optionally updated) timeout or session
WAIT        — keep polling without breaking out of the current poll loop
              (unlike noop, does not restart the loop with a new timeout or session)

Security note:

Steps using command: execute arbitrary shell commands via the system() call. This is
intentional for use cases like browser automation (e.g. Selenium) that must interact
with Inferno's waiting state mid-test. Because of this risk, command: steps are blocked
by default and require the --allow-commands CLI flag to run. Scripts that contain no
command: steps are unaffected and do not need the flag.

Template tokens in command strings and start_run input values:

{session_id}              — current session's Inferno session ID
{NAME.session_id}         — named session's ID
{result_message}          — current session's wait_result_message
{NAME.result_message}     — named session's wait_result_message
{wait_outputs.KEY}        — current session's wait output by name
{NAME.wait_outputs.KEY}   — named session's wait output by name
{inferno_base_url}        — the Inferno base URL (--inferno-base-url option)

Defined Under Namespace

Classes: ExecutionStatus, ScriptSession

Constant Summary collapse

SHORT_ID_PATTERN = 
/\A[0-9][0-9.]*\z/
LOG_INTERVAL_SECONDS =

Seconds subtracted from the initial last_log_time so the first active-status line is logged immediately rather than after one interval.

30

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(yaml_file, options) ⇒ ExecuteScript

Returns a new instance of ExecuteScript.



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/inferno/apps/cli/execute_script.rb', line 146

def initialize(yaml_file, options)
  self.yaml_file = yaml_file
  self.options = options
  validate_yaml_file!
  validate_commands_allowed!
  self.execution_status = ExecutionStatus.new(
    done: false,
    failed: false,
    timed_out: false,
    current_session: sessions.first,
    current_timeout: options[:default_poll_timeout],
    cross_session_status: {},
    last_step_signatures: {}
  )
end

Instance Attribute Details

#execution_status ⇒ Object

Returns the value of attribute execution_status.



144
145
146
 
# File 'lib/inferno/apps/cli/execute_script.rb', line 144

def execution_status
  @execution_status
end

#options ⇒ Object

Returns the value of attribute options.



144
145
146
 
# File 'lib/inferno/apps/cli/execute_script.rb', line 144

def options
  @options
end

#yaml_file ⇒ Object

Returns the value of attribute yaml_file.



144
145
146
 
# File 'lib/inferno/apps/cli/execute_script.rb', line 144

def yaml_file
  @yaml_file
end

Instance Method Details

#run ⇒ Object 



162
163
164
 
# File 'lib/inferno/apps/cli/execute_script.rb', line 162

def run
  exit(orchestrate)
end