1 Formatting an Apica YAML Script
- 1.1 Sample Formatting
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
4 The “scenarios” section
- 4.1 Name
- 4.2 Flow
  - 4.2.1 Page
  - 4.2.2 HTTP Methods
    - 4.2.2.1 Get:
    - 4.2.2.2 Post
    - 4.2.2.3 Put
    - 4.2.2.4 Delete
  - 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.11.1 Status
    - 4.2.11.2 Text
  - 4.2.12 Mimetype
  - 4.2.13 Size
  - 4.2.14 Before & After
    - 4.2.14.1 Before
    - 4.2.14.2 After
    - 4.2.14.3 A list that contains plugins or inline scripts that will be executed after the current HTTP request.
  - 4.2.15 Plugins & Inline Scripts
    - 4.2.15.1 Plugin
    - 4.2.15.2 Inline
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:
1. “-” (dash) denotes a member of an array of attributes.
2. 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.
3. 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.
4. 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.
5. Every member of an array must have a dash in front of it.
  
  This is acceptable syntax for an array:
  config: target: 'http://ticketmonster.apicasystem.com/ticket-monster' inputs: - name: 'integrationTest' default: 'http://ticketmonsterdev.apicasystem.com/ticket-monster' - name: 'production' default: 'http://ticketmonster.apicasystem.com/ticket-monster'
  This is also acceptable syntax for an array:
  config: target: 'http://ticketmonster.apicasystem.com/ticket-monster' inputs: - name: 'integrationTest' default: 'http://ticketmonsterdev.apicasystem.com/ticket-monster' - name: 'production' default: 'http://ticketmonster.apicasystem.com/ticket-monster'

The “config” section

Attributes of the “config” section

Note the tabs and spaces in the following code sections!

There is no default order for config attributes.

The config section begins with the “config:” keyword:

target

The main URL of the application you want to test. This will become the base URL for all requests in the scenarios section unless you provide a full url for the request. If the protocol (HTTP or HTTPS) is omitted, the request will default to HTTP. Target may also include part of the URI path following the hostname.

headers

Specified headers will be applied to all requests in the YAML definition file. For example, the following headers will direct the YAML script to accept the “application/json” Content-Type in the response headers which comes back after the request is made:

The following image shows an example response header from a ZT script which was compiled from a YAML file which contains the above headers:

inputs

It is possible to provide inputs which become User Input Fields within the compiled ZebraTester script. In the following example, two “inputs” are provided in the YAML file. They should be inserted into the YAML script using the following syntax:

The following inputs become User Input Fields in the final ZebraTester script:

variables

The “variables” keyword specifies runtime variables whose values are initialized when starting the test. You can either provide one field or an array of fields to use. The available runtime variables include:

timestamp: Create a Unix timestamp based on the time when the test is started. By default, the value of the variable will be reinitialized with every test iteration.
random: Create a random number in a range. By default, the value of the variable will be reinitialized with every test iteration.
javaproperty: Create a java system property. By default, the value of the variable will be reinitialized with every test iteration.

Examples of variable usage

The following screenshot shows how the above code translates into a ZebraTester script:

externalfiles

It is possible to declare external files to be used within a compiled ApicaYAML script. This functionality mirrors the external file import functionality which is built into ZebraTester and can be accessed by opening a URL Details window within a ZebraTester script and by clicking on the Folder icon at the top right of the Var Handler:

Clicking on that icon brings up the “Config External Resource” page:

You can specify an external file to add by adding the following attributes to your ApicaYAML definition file:

Place the input file (in this case, externalResource.java) within the “input” folder within your ApicaYAML Solutions folder:

When you compile an ApicaYAML script with the “externalfiles” attribute included and the specified file in the “input” folder, the file will be declared and added as a resource to the final script. This option is most commonly used for importing Java files and adding them to your classpath so they can be utilized by your ZebraTester script or a plugin which is referenced by your ZebraTester script.

inputfiles

It is possible to specify input files which contain test data which can be used by the ZebraTester script. These files will be shown in the “Input Files” section in ZT. External files should be placed in the “/scripts” subfolder of the project folder. You can either provide one file or an array of files to use. Supported file formats are .txt and .csv. Columns must be separated by “,” (comma). Attributes include:

Path (mandatory): The file path to the test data file. Remember that the path is relative to the YAML definition file.
Fields (mandatory): A list of variables that the fields in the test file should map to. The variables will be mapped to the columns in the order that they appear in the list. Columns must be separated by "," (comma).
Order (optional): How the rows in the test file will be picked during the test. Valid options are 'sequential' and 'random'. Random selection is chosen if this option is omitted.
Scope (optional): The scope the extracted variables should have during the test. Valid options are 'global', 'user' and 'loop'. Loop scope is chosen if this option is omitted.
- Global: Same value (row) is used for each and all test iteration
- User: One value (row) is used by each Virtual User for the whole test duration (one row per VU)
- Loop: A new value (row) is selected for each test iteration
EOF: the action to take when the end of the file is reached

The following syntax will add the following files and input fields within the compiled ZebraTester script:

The following screenshot shows a created input file.

The following screenshots show the created variables. These can be assigned manually in the ZT script.

The “scenarios” section

The scenarios section of the definition file is where one or more scripts are defined. If multiple scripts are defined, the config options will be applied to all scripts within the “scenarios” section.

Name

The “name” value specified in the ApicaYAML definition file becomes the name of the script.

This syntax

Becomes

Flow

The “Flow” keyword denotes any content which will be parsed into runnable pages, URLs, etc. within the ZebraTester script. It is where you will define URLs to GET, data to POST, etc.

The following flow objects are supported:

get
post
put
delete
page
loop
transaction

Page

A page break. Every script must start with a page break. Page breaks are followed by HTTP requests.

Can contain the following keywords:

name (mandatory)
thinktime

HTTP Methods

Get:

Can contain the following keywords:

url (mandatory)
capture
assert
before
after
headers

Post

Can contain the following keywords:

url (mandatory)
capture
assert
before
after
json
data
form
plain
headers

Put

Can contain the following keywords:

url (mandatory)
capture
assert
before
after
json
data
form
plain
headers

Delete

Can contain the following keywords:

url (mandatory)
capture
assert
before
after
headers

Transactions & Loops

Transactions and loops must contain a flow that works the same way as the flow at the highest level of the script. This allows for nested transactions and loops.

Transaction

Used to declare multiple requests as part of a single transaction.

Can contain the following keywords:

flow (mandatory)
transactionname (mandatory)

Loop

Used to loop over multiple requests.

flow (mandatory)
loopname (mandatory)
count
over

Capture

This is a list of captures. A capture signifies the extraction of data from an HTTP response.

The capture keywords are:

json
regex
xpath
boundary
header
regexheader

JSON

Can contain the following keywords:

target (mandatory)
as (mandatory)
fallback
random
occurrence

RegEx

Can contain the following keywords:

target (mandatory)
as (mandatory)
fallback
random
occurrence

Xpath

Can contain the following keywords:

target (mandatory)
as (mandatory)
fallback
random
occurrence

Boundary (Left Right Boundary)

Can contain the following keywords:

leftboundary (mandatory)
rightboundary (mandatory)
as (mandatory)
fallback
random
occurrence

Header

Can contain the following keywords:

target (mandatory)
as (mandatory)
fallback
random
occurrence

Regex Header

Can contain the following keywords:

target (mandatory)
as (mandatory)
fallback
random
occurrence

Assert

This is a list of asserts. An assert signifies the verification of a status code, text string, mime type or the size of response data. The load test can be configured to abort if an assert fails.

Can contain the following keywords:

status
text
size
mimetype

Status

Can contain the following keywords:

codes
onfail

Text

Can contain the following keywords:

string1
string2
operand
onfail

Mimetype

Can contain the following keywords:

target
onfail

Size

Can contain the following keywords:

target
deviation
onfail

Before & After

The before and after keywords signify a list of plugins and inline scripts that can be run either before or after an HTTP request.

Before

A list that contains plugins or inline scripts that will be executed before the current HTTP request.

Can contain the following keywords:

plugin
inline

After

A list that contains plugins or inline scripts that will be executed after the current HTTP request.

Can contain the following keywords:

plugin
inline

Plugins & Inline Scripts

Plugin

Plugins are java programs specifically created for ZebraTester/ZebraCLI. Plugins extend the functionality of ZebraCLI and allow java code to be run before and after HTTP requests.

Can contain the following keywords:

file (mandatory)
input
output

Inline

Inline scripts are written in BASIC and extend the functionality of ZebraCLI. Inline scripts can be run before and after HTTP requests.

Can contain the following keywords:

code (mandatory)
input
output

Example Scenarios

The following scenarios serve as examples to reference when creating and modifying scripts.

Understanding ApicaYAML Scripting and Syntax

Formatting an Apica YAML Script

Sample Formatting

Notes on Special Characters

The “config” section

Attributes of the “config” section

target

headers

inputs

variables

Examples of variable usage

externalfiles

inputfiles

The “scenarios” section

Name

Flow

Page

HTTP Methods

Get:

Post

Put

Delete

Transactions & Loops

Transaction

Loop

Capture

JSON

RegEx

Xpath

Boundary (Left Right Boundary)

Header

Regex Header

Assert

Status

Text

Mimetype

Size

Before & After

Before

After

A list that contains plugins or inline scripts that will be executed after the current HTTP request.

Plugins & Inline Scripts

Plugin

Inline

Example Scenarios

Simple Scenario

Complex Scenario