ASTA Programming Languages Documentation
Rules Language
The Rules language is designed for defining rules that consist of multiple scenarios, each with a single Gherkin rule expression. Rules follow a structure with given contexts, actions, assertions, and optional final assignments.
Rule Structure
Rules consist of a rule identifier and a title, followed by one or more scenarios.
| Production Rule | Description | Source |
|---|---|---|
| Rule | Defines a rule with scenarios | Rule = "Rule" ruleId? ":" title Scenario+ |
| ruleId | An optional rule identifier | ruleId = name | numericLiteral |
| name | An identifier name for the rule | name = identifierName |
| title | A title for the rule | title = letter ~"\n" (alnum | "_" | "-" | " " | "\t")* |
Scenarios
Scenarios describe the conditions, actions, and assertions for a rule.
| Production Rule | Description | Source |
|---|---|---|
| Scenario | Defines a scenario with a rule expression | Scenario = "Scenario" ruleId? ":" title RuleExp |
| RuleExp | The main expression for a scenario | RuleExp = "Given" Context "When" Actions "Then" Assertions ("Finally" Assignments)? |
Context, Actions, Assertions, Assignments Clauses
These sections define the components of a scenario, detailing the initial context, actions performed, expected outcomes, and final assignments.
| Production Rule | Description | Source |
|---|---|---|
| Context | Initial conditions or setup for the scenario. Used to check application and page state. | Context = BooleanList | wildcard |
| Actions | Checks what kind action that just occurred, and what it was performed on. | Actions = NonemptyConjunctionList<ActionContext> | wildcard |
| ActionContext | Defines an action context | ActionContext = "action" "is" Action |
| Assertions | Expected outcomes of the actions. Scenarios will pass or fail if this passes or fails. | Assertions = BooleanList |
| Assignments | Optional. Updates run and application state. Only runs if assertions pass. | Assignments = NonemptyListOf<Assignment, "And"> |
| Assignment | Sets a state variable to a value | Assignment = "set" memberExp "to" (class | ValueExp) |
Actions
Defines specific user actions such as input, mouse actions, visits, and browser actions.
| Production Rule | Description | Source |
|---|---|---|
| Action | Defines an action | Action = InputAction | MouseAction | VisitAction | BrowserAction |
| InputAction | Defines an input action | InputAction = ("set" | "drag" | "fill") Component ("to" | "with") ValueExp |
| MouseAction | Defines a mouse action | MouseAction = ("click" | "dblclick" | "hover" | "rightclick") Component |
| VisitAction | Defines a visit action | VisitAction = "visit" ("page" | stringLiteral) |
| BrowserAction | Defines a browser action | BrowserAction = "browser" ("back" | "forward" | "refresh") |
Flows Language
The Flows language is designed for defining flows consisting of a series of steps in a breadcrumb notation. Flows include steps like actions, flow calls, command calls, assignments, assertions, and control statements like while and if.
Flow Structure
A flow is defined with a title, optional parameters, and a series of steps.
| Production Rule | Description | Source |
|---|---|---|
| Flow | Defines a flow with parameters and steps | Flow = title #"(" Params ")" ":" Steps |
| Params | A comma-separated list of parameters | Params = ListOf<FormalParameter, ","> |
| FormalParameter | A parameter in the flow | FormalParameter = identifier |
Steps
Steps describe the sequence of actions and other statements in a flow.
| Production Rule | Description | Source |
|---|---|---|
| Steps | A list of steps separated by >, comments, or whitespace | Steps = nonemptyListOf<Step, stepDelimiter> |
| Step | A single step in a Flow | Step = Action | flowCall | commandCall | AssignmentStatement | AssertionStatement | WhileStatement | IfStatement |
Actions
Defines specific user actions within a flow.
| Production Rule | Description | Source |
| ------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ------------ |
| Action | Defines an action | Action = InputAction \| MouseAction \| VisitAction \| BrowserAction | SmartAction |
| InputAction | Fills an <input>, <form>, <select> or any other element that can hold a value. | InputAction = ("set" \| "drag" \| "fill") Component ("to" \| "with") ValueExp |
| MouseAction | Perform an action with the mouse (e.g. click, hover) | MouseAction = ("click" \| "dblclick" \| "hover" \| "rightclick") Component |
| VisitAction | Defines a visit action | VisitAction = "visit" ("page" \| stringLiteral) |
| BrowserAction | Defines a browser action | BrowserAction = "browser" ("back" \| "forward" \| "refresh") |
| SmartAction | Defines a smart action using selectors | SmartAction = Selector |
Flow and Command Calls
Flow calls and command calls within a flow.
| Production Rule | Description | Source |
|---|---|---|
| flowCall | A call to another flow | flowCall = "$flow" "." flowIdentifier "(" applySyntactic<Args> ")" |
| commandCall | A call to a built-in command | commandCall = "$cmd" "." qualifiedIdentifier "(" applySyntactic<Args> ")" |
Built-in Commands
The following built-in commands are available for use in flows:
| Command | Description | Parameters | Returns | Example |
|---|---|---|---|---|
gen_auth_code | Generate a Two-Factor authenticator code from an authenticator key | authKey: string - The auth key to generate an auth code from | string - The generated auth code | $cmd.gen_auth_code("JBSWY3DPEHPK3PXP") |
get_auth_key | Get a Two-Factor Authentication key from the page | None | string - The extracted 2FA key | $cmd.get_auth_key() |
get_temp_code | Get a temporary authenticator code from the page | None | string - The extracted temporary code | $cmd.get_temp_code() |
wait | Pause the action for a desired amount of time | ms: number - Duration to wait in milliseconds | None | $cmd.wait(1000) |
extract_text | Extract text from a page element | selector: string - The selector to extract text fromregex: string - The regex to use to extract text | string - The extracted text | $cmd.extract_text("input[name='email']", "(.+@.+)") |
generate_data | Use AI to generate data for form elements on the current page | useInvalidData?: boolean - Whether to generate invalid data (optional) | object - The generated data as key-value pairs | $cmd.generate_data() or $cmd.generate_data(true) |
Assignments
Declare or re-assign variables.
| Production Rule | Description | Source |
|---|---|---|
| AssignmentStatement | Assigns a value to a variable. This both reassigns existing variables and declares new ones. | AssignmentStatement = memberExp "=" (ValueExp | Component) |
Assertions
Assert that some condition is true, terminating the flow with a failure if it is not.
| Production Rule | Description | Source |
|---|---|---|
| AssertionStatement | Asserts a condition | AssertionStatement = "assert" BooleanList |
Control Flow
Control the flow of execution with while and if statements.
| Production Rule | Description | Source |
|---|---|---|
| WhileStatement | Executes steps while a condition is true | WhileStatement = "while" BooleanList "do" Steps "end" |
| IfStatement | Executes steps based on a condition | IfStatement = "if" BooleanList "then" Steps ("else" Steps)? "end" |
Selectors
Selectors are used to identify and locate UI components within a page. They can be hierarchical or primary, using various forms such as classes, model items, locators, semantic selectors, and substring selectors.
| Production Rule | Description | Source |
|---|---|---|
| Selector | A UI component selector | Selector = HierarchicalSelector | PrimarySelector |
| HierarchicalSelector | Selector composed of a primary selector and a sub-selector | HierarchicalSelector = PrimarySelector "/" Selector |
| PrimarySelector | Basic selector including class, model item, locator, semantic, substring, or parenthesis selector | PrimarySelector = class | modelItem | Locator | semSel | SubstringSelector | ParenSelector |
| class | Selector for a component class | class = "~" qualifiedIdentifier |
| modelItem | Selector for a model item | modelItem = "@" qualifiedIdentifier |
| Locator | Selector for an element using Playwright syntax | Locator = "(" Attributes ")" |
| semSel | Semantic selector using a tilde and string literal | semSel = "~" stringLiteral |
| SubstringSelector | Substring selector using a string literal without tilde | SubstringSelector = stringLiteral ~(space* "+") |
| ParenSelector | Selector wrapped in parentheses | ParenSelector = "~"? "(" (Selector | StringExp) ")" |
| Attributes | List of attribute-value pairs for locators | Attributes = NonemptyListOf<AttrValue, ","> |
| AttrValue | An attribute-value pair in a locator | AttrValue = (attr | stringLiteral) "=" ValueExp |
| attr | An attribute name in a locator | attr = qualifiedIdentifier |
| Component | UI components identified by a selector or special name | Component = ComponentInner |
| ComponentProp | Component property identified by a property name | ComponentProp = property |
| property | A property name for a component | property = identifier |
| Page | Special page identifiers, "current" or "prior" | Page = ("current" | "prior")? "page" |