Understanding ApicaYAML Scripting and Syntax
- 1 Formatting an Apica YAML Script
- 2 Notes on Special Characters
- 3 The “config” section
- 3.1 Attributes of the “config” section
- 3.1.1 target
- 3.1.2 headers
- 3.1.3 inputs
- 3.1.4 variables
- 3.1.4.1 Examples of variable usage
- 3.1.5 externalfiles
- 3.1.6 inputfiles
- 3.1 Attributes of the “config” section
- 4 The “scenarios” section
- 4.1 Name
- 4.2 Flow
- 4.2.1 Page
- 4.2.2 HTTP Methods
- 4.2.3 Transactions & Loops
- 4.2.3.1 Transaction
- 4.2.3.2 Loop
- 4.2.4 Capture
- 4.2.5 JSON
- 4.2.6 RegEx
- 4.2.7 Xpath
- 4.2.8 Boundary (Left Right Boundary)
- 4.2.9 Header
- 4.2.10 Regex Header
- 4.2.11 Assert
- 4.2.12 Mimetype
- 4.2.13 Size
- 4.2.14 Before & After
- 4.2.15 Plugins & Inline Scripts
- 5 Example Scenarios
- 5.1 Simple Scenario
- 5.2 Complex Scenario
YAML scripts are divided into two main sections - a “config” section and a “scenarios” section. The “config” contains global parameters which are applied to all scripts within the “scenarios” section. The “scenarios” section contains the actual script(s) that will run during the test.
Dashes or other special characters cannot be used in the name of the scenario since the scenario name will become the Java class name and special characters are not allowed in the Java class name.
Formatting an Apica YAML Script
Each indentations level must be made with either two or four space characters, as long as it is consistent. The example below was done with an indent equaling 2 spaces.
Sample Formatting
Note the comments explaining the formatting.
config: # start of configuration. no indent.
target: null # mandatory for the script. 1 indent.
defaults: # start of settings for requests. 1 indent.
headers: # start of a specific default setting. 2 indents.
name: value # default setting parameters. 3 indents.
environments: # start of settings. 1 indent.
name: # environment identifier. 2 indents.
target: null # environment address. 3 indents.
inputs: # start of settings. 1 indent.
- name: null # mandatory input identifier. 2 indents and a dash.
default: null # optional default value. 2 indents.
files: # start of settings. 1 indent.
- path:"path/to/file" # mandatory path to the file. 2 indents and dash followed by a quoted path.
- fields: # start of list of variables to map to. 3 indents and dash.
- name: "arbitraryName" # start of list of variables to map to. 4 indents and dash, followed by a quoted name.
order: "sequential" # read order (sequential / random). 3 indents followed by quoted order.
scope: "global" # file scope (global / user / loop). 3 indents followed by quoted scope.
variables: # start of the Variables section. 1 indent.
- date: null # start of the date variables, each with a 2 indent dash and quoted name.
- format: null
- offset: null
- hour: null
- second: null
- day: null
- year: null
- timestamp: null
- random: # start of a variable. 2 indent dash and quoted name.
scope: null # variable Scope (global / user / loop). 3 indents followed by quoted scope.
from: null # start value. 3 indents followed by quoted scope.
to: null # end value. 3 indents followed by quoted scope.
leadingzeros: null # an optional number of zeros to prefix the value. 3 indents followed by quoted scope.
- java_property: # start of a variable. 2 indent dash and quoted name.
key: null. # Java property key. 3 indent and quoted name.
value: null # Java property value. 3 indent and quoted value.
scenario: # Start of Scenario: No indentation.
-name: # Name of: Dash and 1 indentation followed by the script name.
flow: # Start of the section: 2 indents
- get: # Start of Step: 3 indents and dash followed by the command.
url: # URL to be accessed: 4 indents. The URL counts as the first attribute. Include https://www
assert: # allow both 302 and 200 in the response code of the url you're getting. 4 indents
- status: # assert the returned URL is a certain status. 5 indents
codes: # assert status codes. 5 indents
- 200 # assert given status codes. 6 indents
- 302 # assert given status codes. 6 indents
Notes on Special Characters
Do not use a Word processor when creating ApicaYAML scripts; instead, treat the scripts as code and create/edit them in an IDE with integrated YAML formatting.
Indentations have a major impact on how the script is interpreted. If a script is indented incorrectly, it will not work.
Indentations must be made with “space” (in the examples we always use 2 spaces per indentation)
Single quotes (') are not escaped
Double quotes (“) are escaped
“\n” denotes a new line
“#” denotes a comment
Refer to the following rules for constructing arrays of attributes within ApicaYAML scripts:
“-” (dash) denotes a member of an array of attributes.
Only certain attributes are intended to be items in an array and only some attributes can be placed in arrays. The concept of an array is completely different here than it is in regular coding languages; instead arrays are intended an syntax component which specifies a one to many relationship in the ZT script. For instance, a user can have one to many input files in a script.
The first item in the array is the first item which is specified after the dash and the last item in the array is the last item in the indentation block! That is, the array starts with a dash and ends when the indentation block ends.
The dash can be placed on the same line as the first array item or on a separate line before the first array item. Arrays have no bearing on indentation level.
Every member of an array must have a dash in front of it.
This is acceptable syntax for an array: