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