From 59e4191fd1a08bde570e92843913369ffab461a1 Mon Sep 17 00:00:00 2001
From: rob <robdickson444@hotmail.com>
Date: Sat, 17 Jan 2026 14:39:17 -0400
Subject: [PATCH] Add contextual tooltips to TestStepDialog

- Input Variables: explains {variable} syntax and variable sources
- Assertions: lists all available assertion types with descriptions
- Provider: explains override options including mock provider
- Run Step: describes what happens when clicked
- Output: explains status, output text, variables, and assertion results

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/cmdforge/gui/dialogs/test_step_dialog.py | 42 +++++++++++++++++++-
 1 file changed, 41 insertions(+), 1 deletion(-)

diff --git a/src/cmdforge/gui/dialogs/test_step_dialog.py b/src/cmdforge/gui/dialogs/test_step_dialog.py
index 6f604a9..3738197 100644
--- a/src/cmdforge/gui/dialogs/test_step_dialog.py
+++ b/src/cmdforge/gui/dialogs/test_step_dialog.py
@@ -137,6 +137,14 @@ class TestStepDialog(QDialog):
 
         # Left: Variables input
         vars_group = QGroupBox("Input Variables")
+        vars_group.setToolTip(
+            "<p><b>Input Variables</b></p>"
+            "<p>These are the variables referenced by this step using {variable} syntax.</p>"
+            "<p>Enter test values to simulate what the step would receive during actual execution.</p>"
+            "<p><b>{input}</b> - The main input text (stdin or piped content)<br>"
+            "<b>{argname}</b> - Values from tool arguments<br>"
+            "<b>{prev_output}</b> - Output from previous steps</p>"
+        )
         vars_layout = QVBoxLayout(vars_group)
 
         vars_help = QLabel("Provide test values for variables used in this step:")
@@ -154,6 +162,19 @@ class TestStepDialog(QDialog):
 
         # Right: Assertions
         assert_group = QGroupBox("Assertions (Optional)")
+        assert_group.setToolTip(
+            "<p><b>Assertions</b></p>"
+            "<p>Define checks to automatically validate the step output.</p>"
+            "<p><b>Available assertion types:</b><br>"
+            "• <b>Not Empty</b> - Output must contain text<br>"
+            "• <b>Contains</b> - Output must include specific text<br>"
+            "• <b>Does Not Contain</b> - Output must NOT include text<br>"
+            "• <b>Equals</b> - Output must exactly match expected value<br>"
+            "• <b>Valid JSON</b> - Output must be parseable JSON<br>"
+            "• <b>Valid Python</b> - Output must be valid Python syntax<br>"
+            "• <b>Matches Regex</b> - Output must match a pattern<br>"
+            "• <b>Min/Max Length</b> - Output length constraints</p>"
+        )
         assert_layout = QVBoxLayout(assert_group)
 
         assert_help = QLabel("Define checks to validate the step output:")
@@ -174,6 +195,7 @@ class TestStepDialog(QDialog):
 
         # Add assertion button
         btn_add_assertion = QPushButton("+ Add Assertion")
+        btn_add_assertion.setToolTip("Add a new assertion to validate the step output")
         btn_add_assertion.clicked.connect(self._add_assertion_row)
         assert_layout.addWidget(btn_add_assertion)
 
@@ -191,8 +213,17 @@ class TestStepDialog(QDialog):
 
         # Provider override (for prompt and tool steps)
         if isinstance(self.step, (PromptStep, ToolStep)):
-            controls_layout.addWidget(QLabel("Provider:"))
+            provider_label = QLabel("Provider:")
+            provider_label.setToolTip("Override the AI provider for this test run")
+            controls_layout.addWidget(provider_label)
             self.provider_combo = QComboBox()
+            self.provider_combo.setToolTip(
+                "<p><b>Provider Override</b></p>"
+                "<p>Select a different provider for testing:</p>"
+                "<p>• <b>(use step's default)</b> - Use the provider configured in the step<br>"
+                "• <b>mock</b> - Fast testing without API calls (returns debug info)<br>"
+                "• Other providers will make real API calls</p>"
+            )
             self.provider_combo.addItem("(use step's default)")
             providers = load_providers()
             for provider in sorted(providers, key=lambda p: p.name):
@@ -210,6 +241,7 @@ class TestStepDialog(QDialog):
 
         # Run button
         self.btn_run = QPushButton("Run Step")
+        self.btn_run.setToolTip("Execute this step with the provided input variables and check assertions")
         self.btn_run.setMinimumHeight(36)
         self.btn_run.setMinimumWidth(120)
         self.btn_run.clicked.connect(self._run_test)
@@ -219,6 +251,14 @@ class TestStepDialog(QDialog):
 
         # Output section
         output_group = QGroupBox("Output")
+        output_group.setToolTip(
+            "<p><b>Output</b></p>"
+            "<p>Shows the results after running the step:</p>"
+            "<p>• <b>Status</b> - Success/failure and execution time<br>"
+            "• <b>Output text</b> - The actual output produced by the step<br>"
+            "• <b>Output variables</b> - Variables that would be available to subsequent steps<br>"
+            "• <b>Assertion results</b> - Pass/fail status for each assertion</p>"
+        )
         output_layout = QVBoxLayout(output_group)
 
         # Status line