How to store metadata of a workspace in TFML

Testfully 1.179.0 introduced the support for file-based workspaces using Testfully Markup Language. This article demonstrates how to persist metadata for a workspace in TFML.

A file-based workspace in Testfully is a folder that contains a bunch of sub-folders and files that represent collections, folders, requests,environments, globals and more. The root of the workspace folder must contain a file named workspace.toml, which holds the metadata for the workspace.

Defining a workspace in TFML

To convert a folder into a file-based workspace, you need to place the workspace.toml file in the root of the folder. The file must be named exactly workspace.toml and contain the necessary metadata for the workspace.

The workspace.toml file can contain the following fields:

name field

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

Example below defines a workspace named "My Workspace":

# workspace.toml
name = "My Workspace"

Workspace Directory Structure

A typical file-based workspace directory structure looks like this:

MyWorkspace/
├── collections/ <- Collections folder
│   ├── MyCollection/ <- A collection folder
│   │   ├── Folder1/ <- A folder within the collection
│   │   │   ├── request1.toml <- A request file
│   │   │   └── request2.toml
│   │   ├── Folder2/
│   │   │   ├── request3.toml
│   │   │   └── request4.toml
│   │   └── echo_request.toml
│   └── AnotherCollection/
│       └── echo_request.toml
├── environments/ <- Environments folder
│   ├── Development.toml <- An environment file
│   └── Production.toml
├── globals.toml <- Globals file
└── workspace.toml <- Workspace metadata file

Let's break down the structure:

The collections folder

When Testfully opens a file-based workspace, it looks for a folder named collections in the root of the workspace folder. This folder contains one or more collection folders. Each collection folder can contain multiple folders and requests. If you need to define metadata for a collection or folder, you can do so by adding an index.toml file in the respective folder.

Your collections must be placed inside the collections folder, or they will not be recognized as collections. Also, Testfully considers each folder within the collections folder as a separate collection, so make sure to organize your collections accordingly.

Inside a collection folder, you can have unlimited levels of nested folders and requests. For a folder to be recognized as a folder, you DO NOT need to add any file inside it. However, if you want to define metadata for a folder, you can add an index.toml file inside the folder, just like you would do for a collection.

The environments folder

Similar to collections, Testfully looks for a folder named environments in the root of the workspace folder. This folder contains one or more environment files, each representing a different environment. You can name the environment files anything you want, as long as they have a .toml extension.

At the moment, Testfully does not support nested folders within the environments folder, so all environment files must be placed directly inside the environments folder.

The globals.toml file

To define one or more global variables for a file-based workspace, you need to create a file called globals.toml in the root of the workspace folder, next to the workspace.toml file. Please make sure the file is named exactly globals.toml or it will not be recognized as the globals file.

The workspace.toml file

The workspace.toml file is the only mandatory file in a file-based workspace. It must be placed in the root of the workspace folder and contain the necessary metadata for the workspace.