Recording Design

Recording Design - WIP

TODO: link here from other pages.

Definitions

Definitions are for the context of this page.

Object

Object is a user interface element that supports any kind of interaction. Imprecisely saying, Objects appear in outputs of programs.

This definition is intentionally shallow as Objects are not the focus of this page.

Interaction Record

More precisely, "Structured Interaction Record" is a structured data representation of single user interaction event with the shell. Examples:

• Entering a command
• Mouse click on an Object
• Hitting enter to interact with selected Object
• Opening context menu and selecting a command from the menu

Recording

Recording is a group of Interaction Records. Recording, in its purpose, is similar to a script: it provides reproducibility. Recordings are made automatically as user interacts with the shell and can be edited later, including:

• addition of assertions
• addition of comments
• parametrization
• editing of Object selection criteria (when guessed wrong), within limits

Compared to regular scripting, the effort of creating a Recording is much smaller.

Replay

Continuing the script analogy, if Recording is like creating a script, Replay is like running a script.

Assertion

Assertion is a condition articulated by the user (or guessed by the shell) that must hold true at a particular point during Replay. When that point is reached, if that condition is not evaluating to true, Replay can not continue and should either stop or switch to debugging/editing mode.

Adapter

Adapter is a (presumably small) program that takes an output of an external program and converts it to data structure so it could be represented as Objects in the end, allowing interaction: default action and various operations in the context menu. Example: if the output contains IP, when presented as Object after processing, it should support operations for the IP data type such as ping, whois, tcpdump, etc in the context menu.

Side note. There are two big parts for adapter to implement: parsing the output (syntax) and giving semantic meaning to the output. Parsing is already solved for many utilities by the jc utility.

Challenges

To be usable for Replay, Interaction Record must capture the intent (semantics) of the interaction. For example, if there is a list of EC2 instances, and the user decides to stop one of the instances in the list, the user is not interacting with instance with id i-123456. The user might be interacting with instance having Name tag dev, or the most recently launched of the machines having tag Role with value staging, or any other unforeseen criteria. Unfortunately, this semantics is not directly available - we don't know why the user choose to interact with one Object or another.

While we want to capture the precise semantics of the interaction, it is also inappropriate to stop and ask the user. The shell can not be getting in the way of performing tasks. This is especially true when the user does one off (or what seems to be one off at the moment) task and doesn't care about recording and reproducibility.

Requirements

WIP

• Capturing interaction intent (semantics) must include:
  • Which command output was interacted with? Typically that would be the last command that was run but not always.
  • Which element of the out was interacted with?
    • For rows in a table that includes which row was selected and why and which column/field was interacted with.
    • An attempt should be made to find generic (likely recursive) heuristics for different data structures. For example, Tags field with key-value tags must be supported: interacting with a row because it has Tags column/field with tag Name with value db-1 should be supported when capturing the intent.
  • What was the command that user performed? Typically "default action" or a command from a context menu.
• Replay (and therefore Interaction Records) should work despite wide variation of context. Example:
  • Running under another AWS account, in different region, etc
  • Run from other user's machine (after sharing)
• Replay must support both "normal" run and step-by-step execution.
• Recording must support parametrization during recording and after the fact. For example: if the user performed a chain of UI interactions starting with ECS task MyTask1, it should be possible to introduce parameter task_name, use it instead of the value, and provide the value for the parameter at the beginning of Replay.
• Recording must support editing (TODO: elaborate here)
  • Support adding assertions. Ideally, assertions in the UI should be consistent with assert() implementation in NGS: it takes actual value, a pattern to compare to, and an error message to show when the value does not match the pattern.
  • Support adding loops or other means to express "these Interaction Records apply to these objects".
• Outputs from external programs must

Design

WIP

• The criteria by which the user has selected particular Object during interaction are guessed when creating a new Interaction Record.
  • The assumption here is that few relatively simple heuristics would "guess" the criteria correctly in the majority of cases. Example: among table rows, a unique value in a particular column is a good candidate (excluding random unique ID column).
  • Interaction Record is modifiable after the fact. The modification is limited though to sets of criteria that would produce the same result. TODO: elaborate.
• TODO: Guessing Command/output selection criteria.
• TODO: Assertions, including automatic (ex: single match), stopping/debugging on failed assertion
• TODO: Multi-selection
• TODO: Why it's OK to ask the user to interact with fields when selecting an Object
• TODO: Step by step replay.
• TODO: Parametrization

Thinking over Time

WIP

TODO: explain why changed from textual representation of interaction (as code) to structured data.