feat: add variables set in the interaction tests

Author: xavidop

docs/docs/static/conversationtest.json

@@ -97,6 +97,11 @@
 					},
 					"agent": {
 						"$ref": "#/$defs/Agent"
+					},
+					"variables": {
+						"type": "object",
+						"additionalProperties": true,
+						"description": "Variables to set in the agent state after this interaction completes"
 					}
 				},
 				"additionalProperties": false,

docs/docs/tests/interaction-tests.md

@@ -20,6 +20,20 @@ description: These are some tests
 interactions:
   # The ID of the interactions
   - id: test_1
+    user:
+      # the input type
+      # it could be text, audio or prompt
+      type: launch
+    # Optional: Variables to set in the agent state after this interaction
+    variables:
+      user_name: "John Doe"
+      account_type: "premium"
+    agent:
+      validate:
+        - type: traceType
+          value: speak
+
+  - id: test_2
     user:
       # the input type
       # it could be text, audio or prompt
@@ -247,7 +261,92 @@ interactions:
           value: "You selected yes"
 ```
 
+## Setting Variables
+
+You can set variables in the agent's state during a test using the `variables` property on any interaction. Variables are set using the [Voiceflow State Variables API](https://docs.voiceflow.com/reference/updatestatevariables-1) **after** the interaction completes. This is especially important for `launch` interactions, where the session must exist before variables can be set.
+
+### When to Use Variables
+
+- **Initialize agent state**: Set variables after launching a session to configure the agent's behavior
+- **Simulate pre-existing data**: Set user data or context variables that your agent expects
+- **Test different scenarios**: Use different variable values to test how your agent responds under various conditions
+
+### How It Works
+
+1. **For `launch` interactions**: The launch is executed first to create the session, then variables are set afterwards (the session must exist before variables can be set)
+2. **For all other interactions**: Variables are set **before** the interaction executes, so the agent has access to them during the interaction
+3. Subsequent interactions will have access to the updated variables
+
+### Example
+
+```yaml
+name: Variable Setting Example
+description: Test demonstrating variable setting in interaction tests
+
+interactions:
+  - id: launch_conversation
+    user:
+      type: launch
+    # Variables are set AFTER the launch interaction creates the session
+    variables:
+      user_name: "John Doe"
+      account_type: "premium"
+      service_list: "basic, premium, enterprise"
+    agent:
+      validate:
+        - type: traceType
+          value: speak
+
+  - id: ask_about_account
+    user:
+      type: text
+      text: "What is my account type?"
+    agent:
+      validate:
+        - type: contains
+          value: "premium"
+
+  - id: update_preferences
+    user:
+      type: text
+      text: "Update my preferences"
+    # For non-launch interactions, variables are set BEFORE the interaction
+    variables:
+      preferred_language: "Spanish"
+    agent:
+      validate:
+        - type: contains
+          value: "preferences updated"
+```
+
+### Variable Types
+
+Variables support any value type including strings, numbers, booleans, arrays, and objects:
+
+```yaml
+variables:
+  # String
+  user_name: "Jane Smith"
+  # Number
+  retry_count: 3
+  # Boolean
+  is_vip: true
+  # Object
+  user_profile:
+    name: "Jane Smith"
+    email: "jane@example.com"
+  # Array/List
+  selected_items:
+    - "item1"
+    - "item2"
+```
+
+### Important Notes
 
+- For `launch` interactions, variables are set **after** the interaction (the session must exist first)
+- For all other interactions, variables are set **before** the interaction executes
+- The `variables` property uses the same underlying API as the [Agent-to-Agent testing variables](/tests/agent-to-agent-tests/#voiceflowagenttargetconfig-voiceflow-agent-to-agent-testing-only)
+- Variables are merged with existing state variables (PATCH operation), not replacing them entirely
 
 ## Validation types
 

examples/tests/test_1.yaml

@@ -4,6 +4,9 @@ interactions:
   - id: test_1_1
     user: 
       type: launch
+    variables:
+      user_name: "John Doe"
+      account_type: "premium"
     agent:
       validate:
         - type: contains
@@ -14,6 +17,9 @@ interactions:
     user: 
       type: text
       text: 'I am doing well'
+    variables:
+      user_name: "John Does"
+      account_type: "premium"
     agent:
       validate:
         - type: traceType

internal/types/tests/testTypes.go

@@ -37,10 +37,11 @@ type UserInfo struct {
 }
 
 type Interaction struct {
-	ID      string   `yaml:"id" json:"id"`
-	User    User     `yaml:"user" json:"user"`
-	Agent   Agent    `yaml:"agent" json:"agent"`
-	Buttons []Button `yaml:"-" json:"-"` // Stores buttons from previous response, not serialized
+	ID        string                 `yaml:"id" json:"id"`
+	User      User                   `yaml:"user" json:"user"`
+	Agent     Agent                  `yaml:"agent" json:"agent"`
+	Variables map[string]interface{} `yaml:"variables,omitempty" json:"variables,omitempty"` // Variables to set in the agent state
+	Buttons   []Button               `yaml:"-" json:"-"`                                     // Stores buttons from previous response, not serialized
 }
 
 type User struct {

pkg/test/runner.go

@@ -44,10 +44,31 @@ func runTest(environmentName, userID string, test tests.Test, apiKeyOverride, su
 			logCollector.AddLog("\tInteraction Request Button: " + interaction.User.Value)
 		}
 
+		// For non-launch interactions, set variables BEFORE the interaction
+		if interaction.User.Type != "launch" && len(interaction.Variables) > 0 {
+			logCollector.AddLog(fmt.Sprintf("\tSetting %d variables in agent state before interaction", len(interaction.Variables)))
+			err := voiceflow.UpdateStateVariables(environmentName, userID, interaction.Variables, apiKeyOverride, subdomainOverride)
+			if err != nil {
+				return fmt.Errorf("error setting variables for Interaction ID %s: %v", interaction.ID, err)
+			}
+			logCollector.AddLog("\tSuccessfully updated agent state variables")
+		}
+
 		interactionResponses, err := voiceflow.DialogManagerInteract(environmentName, userID, interaction, apiKeyOverride, subdomainOverride, availableButtons)
 		if err != nil {
 			return err
 		}
+
+		// For launch interactions, set variables AFTER the interaction
+		// (the session must exist before variables can be set)
+		if interaction.User.Type == "launch" && len(interaction.Variables) > 0 {
+			logCollector.AddLog(fmt.Sprintf("\tSetting %d variables in agent state after launch", len(interaction.Variables)))
+			err = voiceflow.UpdateStateVariables(environmentName, userID, interaction.Variables, apiKeyOverride, subdomainOverride)
+			if err != nil {
+				return fmt.Errorf("error setting variables for Interaction ID %s: %v", interaction.ID, err)
+			}
+			logCollector.AddLog("\tSuccessfully updated agent state variables")
+		}
 		validations := interaction.Agent.Validate
 		validations = autoGenerateValidationsIDs(validations)
 

server/docs/docs.go

@@ -392,6 +392,11 @@ const docTemplate = `{
                 },
                 "user": {
                     "$ref": "#/definitions/tests.User"
+                },
+                "variables": {
+                    "description": "Variables to set in the agent state",
+                    "type": "object",
+                    "additionalProperties": true
                 }
             }
         },