TOML in 5 Minutes

TOML (Tom's Obvious, Minimal Language) is a configuration file format designed for readability and simplicity. Testfully Markup Language (TFML) is built on top of TOML, providing a structured way to define API requests, collections, folders, environments, vaults, cookies, and more in a human-readable format.

TOML uses a simple key-value pair structure, making it easy to read and write. This introduction is a minimal overview of TOML syntax, focusing on the elements that are relevant for defining API requests and collections in Testfully.

To learn more about TOML, you can visit the official TOML documentation.

Key-Value Pairs

Key-Value pairs are the fundamental building blocks of TOML. They consist of a key and a value, separated by an equals sign (=). Keys can be simple strings or enclosed in double quotes if they contain spaces or special characters. Values can be strings, numbers or booleans.

Below is an example request definition in TOML format:

name = "Get a single character"
url = "https://rickandmortyapi.com/api/character/:id"

Tables

A table is a collection of key-values that are grouped together under a specific name. Tables are defined using square brackets ([]).

Below example shows how to define a set of query and route parameters for an API request using the table syntax:

name = "Get a single character"
url = "https://rickandmortyapi.com/api/character/:id"
[params]
id = 1
format = "json"

Lists

Lists are ordered collections of tables. They are defined using double square brackets ([[ ]]) and can contain any type of value, including strings, numbers, booleans, and even other tables.

Below is an example of how to define two form fields in a request:

name = "Create a new character"
method = "POST"
url = "https://rickandmortyapi.com/api/character"
[[form]]
name = "name"
value = "Rick Sanchez"
[[form]]
name = "status"
value = "Alive"

Multi-line Strings

If your string value spans multiple lines or contains special characters and you want to preserve the formatting, you can use triple quotes (""").

Here is an example of sending a JSON body with a request:

name = "Create a new character"
method = "POST"
url = "https://rickandmortyapi.com/api/character"
json = """
{
  "name": "Rick Sanchez",
  "status": "Alive"
}
"""

Comments

You can add comments to your TOML files using the hash symbol (#). Comments can be placed on their own line or at the end of a line.

Here is an example of using TOML comments to annotate a request definition:

name = "Get a single character"
url = "https://rickandmortyapi.com/api/character/:id"

# The request query and route parameters
[params]
id = 1
format = "json" # The format of the response