requests

HTTP requests to send to your target server. Multiple requests can be defined.

requests:
  {request-name}:
    method: {method}

    # define complete url
    url: {url}
    # or define each url part separately
    url:
      scheme: {scheme}
      host: {host}
      port: {port}
      path: {path}
      query:
        {parameter-name}: {parameter-value}
        ...
      fragment: {fragment}

    header:
      {header-name}: {header-value}
      ...
    basic-auth:
      username: {username}
      password: {password}
    aws-signature:
      version: {version}
      access-key-id: {access-key-id}
      secret-access-key: {secret-access-key}
      session-token: {session-token}
      service: {service}
      region: {region}

    # define body directly
    body:
      {parameter-name}: {parameter-value}
      ...
    # or import file as body
    file: {file}

    before:
      # define as map
      {variable-name}: {variable-value}
      ...
      # or as array
      - {variable-name}: {variable-value}
        ...
      ...
    after:
      # same format as before
  ...

{request-name}

The name of a request. It may contain alphanumeric characters, underscore _ and hyphen-minus -. The first character cannot be hyphen-minus -. The length can be up to 64 characters.

default is a special request name that can define default values. See default for the detais.

method

HTTP method. The following methods can be used:

GET, POST, PUT, DELETE, HEAD, OPTIONS, TRACE, CONNECT, PATCH

If you don't specify method, it defaults to GET.

Example:

method: GET

url

The URL of a request.

Example:

url: https://your-host.com/path/to/resource

Example using JavaScript (see Redmine issue API):

get-issue:
  method: GET
  url: << "http://www.redmine.org/issues/" + $('id') + ".json"

Instead of using url, you can specify the URL parts scheme, host, port, path, query and fragment separately.

scheme

The URL scheme. http or https can be specified. If you don't specify scheme, it defaults to the empty path http.

host

The host part of URL. IPv6 addresses can be specified without enclosing in square brackets [].

Example:

host: your-host.com

host: 123.45.67.89

host: 123:45:67:89:0:ab:cd:ef

port

The port part of URL. You can omit port if using the default HTTP port 80 or HTTPS port 443.

Example:

port: 8080

path

The path part of URL. If you don't specify path, it defaults to the empty path /.

Example:

path: /path/to/resource

query

The query part of URL. Key-value pairs specified in query are appended to the request path as query parameters after URL encoding.

Example:

query:
  field1: value1
  field2: value2

Example using JavaScript (see Redmine issue API):

get-issues:
  url:
    host: www.redmine.org
    path: /issues.json
    query:
      created_on: << "<=" + (new Date()).toISOString()

fragment

The fragment part of URL.

Example:

fragment: section2

header

The header of a request.

• {header-name} is case insensitive. For example, Content-Type and content-type are treated as the same header filed name. It will be an error if both Content-Type and content-type are specified.
• For the format of {header-name} and {header-value}, refer to RFC7230. However, in the case when JavaScript is used for {header-value}, there will be no validation of the format.
• content-type can be either application/json or application/x-www-form-urlencoded. charset is always handled as charset=utf-8. When method is POST and content-type is not specified, content-type: application/json is used by default.

Example:

header:
  content-type: application/x-www-form-urlencoded
  User-Agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6)"

Example using content-type: application/json implicitly (see Redmine issue API):

post-issue:
  method: POST
  url: http://www.redmine.org/issues.json
  body:
    issue:
      project_id: 1
      subject: Example

In this case, the body is encoded in JSON and content-type: application/json is added to the header.

basic-auth

You can specify username and password for basic authentication.

Example:

basic-auth:
  username: user1
  password: passwd-for-user1

aws-signature

AWS signature settings to access an AWS service.

Note: As of now, only signature version 4 is supported.

Example:

aws-signature:
    access-key-id: AKIAIOSFODNN7EXAMPLE
    secret-access-key: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    service: s3
    region: ap-northeast-1

Example using $('secrets'):

aws-signature:
    access-key-id: << $('secrets')['access-key-id']
    secret-access-key: << $('secrets')['secret-access-key']
    service: s3
    region: ap-northeast-1

body

The body of a request. The structure depends on content-type.

• application/json

  Arbitrary JSON structured data can be written in rocro.yml.

  Example (see Redmine issue API):

  post-issue:
    method: POST
    url: http://www.redmine.org/issues.json
    header:
     content-type: application/json
  body:
    issue:
      project_id: 1
      subject: Example
  

• application/x-www-form-urlencoded

  Only flat key-value pairs can be written in rocro.yml.

  Example:

  body:
    field1: value1
    field2: value2
  

file

You can specify a file under the Git repository instead of using body. The file content will be sent as the request body. You can also arbitrarily set the content-type.

Example (see Redmine issue API):

JSON file placed at path/to/data.json in your repository:

{
  "issue": {
    "project_id": 1,
    "subject": "Example",
    "priority_id": 4
  }
}

post-issue:
  method: POST
  url: http://www.redmine.org/issues.json
  header:
     Content-Type: application/json
  file: path/to/data.json

default

default is a special request name that can define default values. All the other requests refer to the values under default as default. Under default, you cannot define body, file, before and after. You also cannot use JavaScript expressions under default.

Example:

default:
  url:
    scheme: https
    host: your-host.com
another:
  # equivalent to "url: https://your-host.com/path/to/resource"
  url:
    path: /path/to/resource

JavaScript Expressions

You can write a JavaScript expression as the value of url, header, body etc by putting the prefix << before the expression: << {expression}. In the before and after sections, you can define your own variables using JavaScript expressions without <<.

Variables

In the before and after sections, you can define variables that are evaluated before/after each request. {variable-name} is the name of a variable and {variable-value} is an JavaScript expression to be evaluated. The result of each expression is stored into the corresponding variable. Variables are bound to each virtual user and cannot be shared with other virtual user.

Each variable can be accessed using $('{variable-name}') in JavaScript code. If you access an undefined variable, the return value is undefined of JavaScript. Furthermore, if an expression raises an exception, then it returns null of JavaScript.

$('response')

$('response') is a reserved variable and holds the response of a request.

• $('response').status retrieves the status code.

• $('response').header.{header-name} retrieves the header value.

  Examples:

  $('response').header.Connection
  $('response').header['User-Agent']
  $('response').header['Set-Cookie'][0]` // case of multiple header fields
  

• $('response').json holds the decoded response body assuming that the response is in JSON format.

• $('response').text holds the response body as a text.

Example (see Redmine issue API):

requests:
  list-issues:
    method: GET
    url:
      host: www.redmine.org
      path: /issues.json
      query:
        sort: created_on
    after:
      - last-issue-idx: $('response').json.issues.length - 1
      - last-issue-id:  $('response').json.issues[$('last-issue-idx')].id
  get-issue:
    method: GET
    path: << "/issues/" + $('last-issue-id') + ".json"

$('secrets')

$('secrets') is a reserved variable that can hold sensitive information you'd like to hide. Secrets can be added via the Web UI (Repository >> Settings >> Secrets).

Once the secrets are added, they can be easily accessed using JavaScript expression.

aws-signature:
  access-key-id: << $('secrets')['access-key-id']
  secret-access-key: << $('secrets')['secret-access-key']

$('agent')

$('agent') is a reserved variable that can hold information of each virtual user.

• $('agent').id is a sequential and unique integer starting with 0. It does not change in the same scenario. For example, you can use it in order to assign different credentials to virtual users.

Example (see Redmine issue API):

requests:
  issues:
    url:
      host:  www.redmine.org
      path: /issues.json
    method: GET
    basic-auth:
      username: $('account').username
      password: $('account').password
    before:
      - accounts: '[{"username": "userA", "password": "passwordA"},
                    {"username": "userB", "password": "passwordB"},
                    {"username": "userC", "password": "passwordC"}]'
      - account:  $('accounts')[$('agent').id]

Limitations

There are the following limitations on JavaScript expressions you can write in rocro.yml.

• Allow only one JavaScript expression for each variable

  • JavaScript block, statement and declaration are forbidden.

• Forbid the identifiers starting with $$