Sequence File

Sequence File

Sequence File is a UTF-8 encoded text file with several lines, it's name is a constant called sample.seq. A line can be:

1. an empty line,
2. a commented line or
3. a command line.

One command line has one command, the command can control the flow of requests we descibed in Request Files.

Currentyly, there're 3 types of commands:

1. Sample Command

This command will launch a HTTP request using specified Request File to target server and it will be considered as a sample in your document (its result will be present in your document).

Format

//This is
// a
// comment
varName <[HTTP Code]< request-file-name [arg0 arg1 arg2 ... argN]

• You can write any comments behind a //, the commented lines will be merged in to one string and be the description of the following sample in your final API document.

• varName can be considered as a variable representing of the sample. As we mentioned above, if you analogize a Request File as a function, the varName would be the return value of the function.

• <[HTTP Code]< is the operator of this command

  • You can specify an expected HTTP Code here to make sure the response is exaclty what you want. e.g: <201< means you only accept 201 CREATED for this sample.
  • You can also omit the code, << means any response code is accepted.
  • If the actual response code is not expected, the execution of Sequence File will be terminated.

• request-file-name is the file name of Request File we've prepared.

• The [arg0 arg1 arg2 ... argN] is the argument list for the Request File, using SPACE as the separator. See here for more.

Examples

1. Use PostUser.req as the request. Abby as the arguement to call to target server and no matter what the response code is, the response will be always saved to a variable a, and the sample's description is Add a user called Abby

//Add a user called Abby
a << PostUser.req Abby

2. Use PutUser.req as the request. Use Abby Moore, the former example's response's ETag header and id in body as the arguements to call to target server and if the response code is 200, the response will be saved to variable b

b <200< PutUser.req `Abby Moore` $a:ETag $a.id

2. Request Command

This command is quite similar with Sample Command, the only difference is that this command is commonly used to get some values for reference in subsequent commands, and will not be considered as a sample and appeared in final API document.

Format

varName =[HTTP Code]= Request File-path [arg0 arg1 arg2 ... argN]

This command is totally as same as Sample Command except the operator. == means accept any response and =304= means only accpet 304 Not Modified status code of response.

Examples

See examples in Sample Command for reference.

3. Snapshot Command

This command will save the content of the request and the response to a text file. The content here includes HTTP status line, headers and body.

This command is usually used for troubleshooting since you can see the detail of the request and the response, it will not affect logic and result of the execution flow.

Format

varName >> snapshot-file-name

• varName is a previously defined variable name in a Request Command or a Sample Command
• >> is the operator of this command, which means write to a file.
• snapshot-file-name is the name of the file you wanna to save to, the file will be saved in Sample Package

Example

Assume a request file get.req like this, which accepts 2 args:

GET /foo{{{0}}}}
> Accept: {{{1}}}

And following commands in Sequence File:

a <200< get.req `?price=lt 2.00` application/json
a >> result.txt

If you launch the tool, you'll get a file result.txt in Sample Package with following content:

GET /foo?price=lt 2.00
> Accept: application/json
HTTP/1.1 200 OK
< ETag: W/"3138717599:fcac158ad5062c1afb0ba55d45738767"
< Content-Type: application/json
< Content-Length: 1982
< Server: Jetty(8.1.7.v20120910)
< Content-Length: 170
{
   "count":1,
   "items":[
      {
         "url":"/shopping-cart/1",
         "product":"2ZY48XPZ",
         "quantity":1,
         "name":"New socks",
         "price":1.25
      }
   ]
}

Arguments

There're 3 types of argument:

1. string

2. Any string without SPACES can be directly considered as a string argument. e.g: foo, foo-123_bar

3. If the argument needs to have some SPACES, you need to embrace the string using a pair of " " e.g: " foo bar "

4. If the string itself contains ", use \" to escape. e.g: I'm a \"nerd\"

5. ref of header value

Like variable in PHP, a $ and a defined varName can be a reference of some previous defined variable in Request Command or Sample Command

You can use a : to access the header of the response which the variable represents. e.g: $a:Etag, $b:Content-Type, $c:Content-Length 3. ref of body value

You can use a . to access body of the response which the variable represents.

Here's an assumption that the response body must be JSON format, so you can access the body's element using . for nested fields and [] for array fields. Note that currently we only support access to the primitive element in JSON object.(string, number and boolean)

e.g: If the var foo representing a response like this:

HTTP 200 OK
< Content-Type: application/json
< Content-Length: 170
{
 "count": 1,
 "items": [
 {
   "url": "/shopping-cart/1",
   "product":"2ZY48XPZ",
   "quantity": 1,
   "name": "New socks",
   "price": 1.25
 } ]
}

Then,

$foo:Content-Type = application/json;

$foo.count = 1;

$foo.items[0].url = /shopping-cart/1;

$foo.items and $foo is not supported.