Variables

TestFlowKit's variable system allows you to store and reuse data throughout your test scenarios, enabling dynamic and data-driven testing.

Variable Syntax

Variables use the {{variable_name}} syntax and are automatically substituted in all step parameters:

# Store a value
When I store the "John Doe" into "user_name" variable

# Use the variable
When the user enters "{{user_name}}" into the "name" field
Then the "name" field should contain "{{user_name}}"

Key Features

✅ Automatic Substitution — Variables are replaced in strings, tables, and parameters
✅ Scenario Scope — Variables persist throughout the entire scenario
✅ Type Support — Supports strings, numbers, booleans, and complex data
✅ Cross-Step Usage — Use variables across different step types

Types of Variables

Environment Variables

Environment variables are defined in configuration files and accessible globally across all scenarios using the {{ env.variable_name }} syntax.

Define in config.yml:

env:
  api_key: "your-api-key"
  base_url: "https://api.example.com"
  database:
    host: "localhost"
    port: "5432"

Use in Gherkin:

# Simple variables
Given the user goes to "{{ env.base_url }}"
And I set the header "Authorization" to "Bearer {{ env.api_key }}"

# Nested variables (use dot notation)
When I connect to "{{ env.database.host }}:{{ env.database.port }}"

External Environment Files:

# Use environment-specific files
tkit run --env-file .env.staging.yml
tkit run --env-file .env.production.yml

Environment variables persist across all scenarios and are loaded at startup. See the Configuration guide for more details.

Custom Variables

Store any value for reuse:

# Store different types of data
When I store the "test@example.com" into "email" variable
And I store the "12345" into "user_id" variable
And I store the "Active" into "status" variable

# Use in form filling
When the user enters "{{email}}" into the "email" field
And the user enters "{{user_id}}" into the "id" field

JSON Path Variables

Extract data from API responses using GJSON path expressions:

# Make an API request
Given I prepare a request for the "get_user" endpoint
When I send the request

# Extract specific fields from the JSON response
And I store the JSON path "user.name" from the response into "user_name" variable
And I store the JSON path "user.email" from the response into "user_email" variable
And I store the JSON path "user.id" from the response into "user_id" variable

JSON Path Syntax

TestFlowKit uses GJSON for JSON path expressions.

Expression	Description	Example
`name`	Root level field	`name` → `"John"`
`user.email`	Nested field	`user.email`
`items.0`	Array index	`items.0` → first item
`items.#`	Array length	`items.#` → `3`
`items.#.name`	All items field	`items.#.name` → all names

💡 For advanced queries, filters, and modifiers, see the GJSON Path Syntax documentation

HTML Element Variables

Capture text content from web page elements:

# Navigate to a page
Given the user goes to the "profile" page

# Capture element content
When I store the content of "page_title" into "title" variable
And I store the content of "user_name_label" into "displayed_name" variable

# Use captured values
Then the "{{title}}" should contain "Profile"

Advanced Usage

End-to-End Data Flow

Combine API testing with frontend testing:

Scenario: Create user via API and verify in UI
  # Create user via API
  Given I prepare a request for the "create_user" endpoint
  And I set the request body to:
    """
    {
      "name": "Test User",
      "email": "test@example.com"
    }
    """
  When I send the request
  And I store the JSON path "data.id" from the response into "user_id" variable
  And I store the JSON path "data.name" from the response into "user_name" variable
  Then the response status code should be 201

  # Verify in frontend
  Given the user goes to the "users" page
  When the user enters "{{user_id}}" into the "search" field
  And the user clicks the "search_button" button
  Then the "user_row" should contain "{{user_name}}"

Data-Driven Testing

Use variables with Scenario Outlines:

Scenario Outline: Login with different users
  When I store the "<email>" into "current_email" variable
  Given the user goes to the "login" page
  When the user enters "{{current_email}}" into the "email" field
  And the user enters "<password>" into the "password" field
  And the user clicks the "login" button
  Then the "welcome_message" should contain "<name>"

  Examples:
    | email            | password | name  |
    | john@example.com | pass123  | John  |
    | jane@example.com | pass456  | Jane  |

Cross-Page Data Transfer

Transfer data between different pages:

Scenario: Copy product details to order form
  # Get product info
  Given the user goes to the "product_details" page
  When I store the content of "product_name" into "selected_product" variable
  And I store the content of "product_price" into "price" variable

  # Use in order form
  When the user goes to the "checkout" page
  Then the "order_summary" should contain "{{selected_product}}"
  And the "total_price" should contain "{{price}}"

Common Patterns

API to Frontend Flow

# Get data from API
Given I prepare a request for the "get_products" endpoint
When I send the request
And I store the JSON path "data.0.id" from the response into "product_id" variable
And I store the JSON path "data.0.name" from the response into "product_name" variable

# Use in frontend
Given the user goes to the "products" page
When the user searches for "{{product_name}}"
Then the "product_{{product_id}}" should be visible

Page Content Verification

# Capture initial state
Given the user goes to the "dashboard" page
When I store the content of "total_count" into "initial_count" variable

# Perform action
And the user clicks the "add_item" button

# Verify change
Then the "total_count" should not contain "{{initial_count}}"

Best Practices

Variable Naming

✅ Use descriptive names: user_email not data
✅ Use snake_case: api_response_id
✅ Include source context: api_user_id, page_title

Variable Usage

✅ Store variables early in your scenario
✅ Use variables to make tests maintainable
✅ Use for data that changes between environments
✅ Verify variables exist before critical steps

⚠️ Variable Scope: Variables are scoped to the current scenario. They don't persist across scenarios. For cross-scenario data, use global hooks.

Next Steps

Macros — Create reusable test patterns
API Testing — REST API testing features
Step Definitions — Variable-related steps