How to store collections in TFML

Collections in Testfully group related API requests, folders and other resources together, while providing a set of reusable features like variables, params, scripts to all resources in the collection to use. You can define a collection using Testfully Markup Language.

Defining a collection

To define a collection in TFML, you should use the index.toml file in the root of your collection folder. Using any other file name will result in the file being ignored by Testfully. The index.toml file can contain the following fields:

Cheat Sheet

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

The following table summarizes the fields you can use in a collection file:

name field

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

Example below defines a collection named "My Collection":

# index.toml
name = "My Collection"

variables field

The variables field hosts a set of variables that can be used in the collection.

Example below defines a collection with a variable named base_url and echo_endpoint:

# index.toml
[variables]
base_url = "https://httpbin.org"
echo_endpoint = "/anything"

You can define a variable and exclude it from the collection by prefixing it with dash -.

Example below defines a collection with a variable named base_url and echo_endpoint, but excludes echo_endpoint from the collection:

# index.toml
[variables]
base_url = "https://httpbin.org"
-echo_endpoint = "/anything"

params field

Attach one or more query parameters to the requests in the collection using the params field, which has a syntax identical to the variables field.

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

# index.toml
[params]
name = "Testfully"
version = "1.0"

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

# index.toml
[params]
name = "Testfully"
-version = "1.0"

headers field

Attach one or more headers to the requests in the collection using the headers field, which has a syntax identical to the variables field.

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

# index.toml
[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 -:

# index.toml
[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.

pre_request field

Run a script before each request in the collection using the pre_request field. This field can contain a script written in JavaScript, which will be executed before each request in the collection.

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

# index.toml
pre_request = """
console.log("Running pre-request script");
"""

post_response field

Run a script after each request in the collection using the post_response field. This field can contain a script written in JavaScript, which will be executed after each request in the collection.

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

# index.toml
post_response = """
console.log("Response:", response);
"""

execution_mode field

Requests in a collection can be executed in groups or individually. When executing requests in groups, the requests can be executed in serial, parallel or random order. The execution_mode field defines how the requests in the collection are executed.

Example below defines a collection with execution_mode set to serial:

# index.toml
execution_mode = "serial"

delay field

When executing requests in a collection using the serial or random execution modes, you can set a delay (in milliseconds) between the requests using the delay field.

Example below defines a collection with a delay of 1000 milliseconds (1 second) between the requests:

# index.toml
delay = 1000

timeout field

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

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

# index.toml
timeout = 5000

secure field

When set to true, the secure field ensures that invalid certificates are not accepted when making requests in the collection. 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 collection with secure set to true:

# index.toml
secure = true

insecure field

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

Example below defines a collection with insecure set to true:

# index.toml
insecure = true

redirects field

• When set to true, the redirects field allows the requests in the collection to follow redirects.

• This is useful for testing endpoints that redirect to other endpoints. When set to false, the requests will not follow redirects.

• When set to a positive integer, the requests will follow redirects up to the specified number of times.

history field

Testfully supports a concept called "history", which allows you to see a list of previously executed requests in the 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 collection.

• Set it to store to enable history feature for the requests in the collection.
• Set it to do_not_store to disable history feature for the requests in the collection.