How to store request metadata in TFML format

Requests in Testfully represent individual API calls that can be grouped into collections. Each request can have its own metadata, such as headers, query parameters, and request body, which can be defined using Testfully Markup Language (TFML).

Defining a request in TFML

To define a request in TFML, you should create a .tfml file in any folder within your collection. The file can have any name, which represents the request name, except for the echo_request.toml file, which is reserved for defining collections and folders.

Cheat Sheet

A request file in TFML format consists of the following fields. All fields are optional, except for the name and url fields, which are mandatory. The fields do not follow any specific order, so you can define them in any order you like.

Field	Type	Description
name	String	The name of the request.
url	String	The URL of the request.
seq	Integer	The sequence of the request in the parent folder or collection. This is useful for ordering requests when they are executed in serial mode.
headers	Key/Value Pair	A set of headers that can be used in the request.
params	Key/Value Pair	A set of query and route parameters that can be used in the request.
pre_request	String	A script that runs before the request is made.
post_response	String	A script that runs after the request is made.
json	String	A JSON body for the request.
xml	String	An XML body for the request.
url_encoded	Key/Value Pair	A set of URL-encoded form fields for the request. This can be repeated to define multiple fields.
form	Key/Value Pair	A set of multi-part/form-data fields for the request. This can be repeated to define multiple fields.
graphql_query	String	A GraphQL query for the request.
graphql_variables	String	A set of GraphQL variables for the request. This can be used to pass dynamic values to the GraphQL query.
secure	Boolean	Whether to enforce secure connections (valid certificates) for the request. When set to `true`, invalid certificates are not accepted. When set to `false`, the request will accept invalid certificates.
insecure	Boolean	Whether to allow insecure connections (invalid certificates) for the request. When set to `true`, the request will accept invalid certificates. When set to `false`, invalid certificates are not accepted.
redirects	Boolean/Integer	Whether to follow redirects for the request. Can be `true`, `false` or a positive integer.
history	String	The history mode for the request, can be `store` or `do_not_store`.
timeout	Integer	The timeout (in milliseconds) for the request.
cookie	Key/Value Pair	A set of cookies that can be used in the request. This can be repeated to define multiple cookies. Each cookie can have the following fields: `name`, `value`, and `enabled`.
html	String	An HTML body for the request.
text	String	A plain text body for the request.
raw	String	A raw body for the request. This can be useful for testing endpoints that require a specific format or structure.
yaml	String	A YAML body for the request.
javascript	String	A JavaScript body for the request. This can be useful for testing endpoints that require a specific JavaScript payload.

`name` field

The name field is a string that defines the name of the request. It is mandatory.

Example below defines a request named "Echo Request":

# echo_request.toml
name = "Echo Request"

`url` field

The url field is a string that defines the URL of the request.

Example below defines a request with the URL https://httpbin.org/anything:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"

`seq` field

The seq field is an integer that defines the sequence of the request in the parent folder or collection. This is useful for ordering requests when they are executed in serial mode.

Example below defines a request with a sequence of 1:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
seq = 1

`headers` field

Attach one or more headers to the request using the headers field.

Example below defines a request with a header named Content-Type and Authorization:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
[headers]
Content-Type = "application/json"
Authorization = "Bearer {{token}}"

If we wanted to exclude the Authorization header from the collection, we would prefix it with a dash -:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
[headers]
Content-Type = "application/json"
-Authorization = "Bearer {{token}}"

Did you notice the {{token}} variable in the Authorization header? This is a variable that can be resolved at runtime, allowing you to use dynamic values in your requests.

`params` field

Attach one or more query or route parameters to the request using the params field, which has a syntax identical to the variables field.

Example below defines a request with a query parameter named name and version:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
[params]
name = "Testfully"
version = "1.0"

If we wanted to exclude the version parameter from the collection, we would prefix it with a dash -:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
[params]
name = "Testfully"
-version = "1.0"

`pre_request` field

Run a Javascript code before making the HTTP call using the pre_request field.

Example below defines a request with a pre_request script that logs a message to the console:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
pre_request = """
console.log("Running pre-request script");
"""

`post_response` field

Run a Javascript code after receiving the HTTP response using the post_response field.

Example below defines a request with a post_response script that logs the response to the console:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
post_response = """
console.log("Response:", response);
"""

`json` field

Attach a JSON body to the request using the json field.

Example below defines a request with a JSON body:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
json = """
{
  "name": "Testfully",
  "version": "1.0"
}
"""

`xml` field

Attach an XML body to the request using the xml field.

Example below defines a request with an XML body:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
xml = """
<request>
  <name>Testfully</name>
  <version>1.0</version>
</request>
"""

`url_encoded` field

Attach a URL-encoded form body to the request using the url_encoded field. To use multiple fields, repeat the url_encoded field for each field you want to define.

# echo_request.tfml
name = "Echo Request"
url = "https://httpbin.org/anything"
[[url_encoded]]
name = "name"
value = "Teddy"
enabled = true
[[url_encoded]]
name = "version"
value = "1.0"
enabled = true

Each url_encoded block represents a single field in the URL-encoded form body, supporting the following attributes:

Attribute	Type	Description
`name`	String	The name of the field.
`value`	String	The value of the field.
`enabled`	Boolean	Whether the field is enabled or not. Defaults to `true`. If set to `false`, the field will be excluded from the request body.

`form` field

Attach a multi-part/form-data request body to the request using the form field. To use multiple fields, repeat the form field for each field you want to define.

# echo_request.tfml
name = "Echo Request"
url = "https://httpbin.org/anything"
[[form]]
name = "name"
value = "Teddy"
enabled = true
[[form]]
name = "version"
value = "1.0"
enabled = true

Each form block represents a single field in the multi-part form body, supporting the following attributes:

Attribute	Type	Description
`name`	String	The name of the field.
`value`	String	The value of the field.
`enabled`	Boolean	Whether the field is enabled or not. Defaults to `true`. If set to `false`, the field will be excluded from the request body.

`graphql_query` field

Attach a GraphQL query to the request using the graphql_query field.

Example below defines a request with a GraphQL query:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
graphql_query = """
{
  user(id: "1") {
    name
    email
  }
}
"""

`graphql_variables` field

Attach GraphQL variables to the request using the graphql_variables field.

Example below defines a request with GraphQL variables:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
graphql_query = """
{
  user(id: $id) {
    name
    email
  }
}
"""
graphql_variables = """
{
  "id": "1"
}
"""

`secure` field

When set to true, the secure field ensures that invalid certificates are not accepted when making HTTP calls. This is useful for ensuring that the requests are made to secure endpoints. When set to false, the requests will accept invalid certificates.

Example below defines a request with secure set to true:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
secure = true

`insecure` field

When set to true, the insecure field ensures that invalid certificates are accepted when making HTTP calls. This is useful for testing endpoints with self-signed certificates or when the certificate is not trusted.

Example below defines a request with insecure set to true:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
insecure = true

`redirects` field

When set to true, the redirects field allows the request to follow redirects.
This is useful for testing endpoints that redirect to other endpoints. When set to false, the request will not follow redirects.
When set to a positive integer, the request will follow redirects up to the specified number of times.

Example below defines a request with redirects set to true:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
redirects = true

`history` field

Testfully supports a concept called "history", which allows you to see a list of previously executed requests in a collection. This can be useful for debugging and understanding the sequence of requests that were made. The history field controls whether the history is enabled or disabled for the request.

Set it to store to enable history feature for the request.
Set it to do_not_store to disable history feature for the request.

Example below defines a collection with history set to store:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
history = "store"

`timeout` field

Set a timeout (in milliseconds) for the request using the timeout field.

Example below defines a request with a timeout of 5000 milliseconds (5 seconds):

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
timeout = 5000

`cookie` field

The cookie field allows you to attach a cookie to the request. This can be useful for testing endpoints that require authentication or session management.

The cookie field can be repeated to attach multiple cookies to the request. Each cookie field should contain the following fields:

Field	Type	Description
name	String	The name of the cookie.
value	String	The value of the cookie.
enabled	Boolean	Whether the cookie is enabled or not. Defaults to `true`. If set to `false`, the cookie will be excluded from the request.

Example below defines a request with a cookie named session_id:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
[[cookie]]
name = "session_id"
value = "1234567890"
enabled = true

Example below defines a request with multiple cookies:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
[[cookie]]
name = "session_id"
value = "1234567890"
[[cookie]]
name = "user_id"
value = "teddybear"

`html` field

Attach an HTML body to the request using the html field.

Example below defines a request with an HTML body:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
html = """
<!DOCTYPE html>
<html>
<head>
  <title>Testfully</title>
</head>
<body>
  <h1>Welcome to Testfully</h1>
  <p>This is a sample HTML body.</p>
</body>
</html>
"""

`text` field

Attach a plain text body to the request using the text field.

Example below defines a request with a plain text body:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
text = """
This is a sample plain text body.
"""

`raw` field

Attach a raw body to the request using the raw field. This can be useful for testing endpoints that require a specific format or structure.

Example below defines a request with a raw body:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
raw = """
This is a sample raw body.
It can contain any text or data you want to send in the request.
"""

`yaml` field

Attach a YAML body to the request using the yaml field.

Example below defines a request with a YAML body:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
yaml = """
title: Testfully
description: This is a sample YAML body.
"""

`javascript` field

Attach a JavaScript body to the request using the javascript field. This can be useful for testing endpoints that require a specific JavaScript payload.

Example below defines a request with a JavaScript body:

# echo_request.toml
name = "Echo Request"
url = "https://httpbin.org/anything"
javascript = """
function testfully() {
  return "This is a sample JavaScript body.";
}
"""

Defining a request in TFML

Cheat Sheet

name field

url field

seq field

headers field

params field

pre_request field

post_response field

json field

xml field

url_encoded field

form field

graphql_query field

graphql_variables field

secure field

insecure field

redirects field

history field

timeout field

cookie field

html field

text field

raw field

yaml field

javascript field