docs: Document debug mode support for tests and specifications

docs/get-started/concepts.md

@@ -41,6 +41,17 @@ An action is the task performed in a step. Doc Detective supports a variety of a
 
 A [context](/docs/references/schemas/context) consists of an application and platforms that support the tests.
 
+## Debug Mode
+
+Doc Detective provides comprehensive debugging capabilities through a hierarchical debug mode system. You can control debugging behavior at the config, specification, test, and step levels. Debug modes include:
+
+- `false` - Disable debugging (default)
+- `true` - Enable debugging with breakpoint support
+- `"stepThrough"` - Pause at every step waiting for user input
+
+Learn more about [debugging tests](/docs/get-started/debugging).
+
 ## Next steps
 
 - [Create your first test](/docs/get-started/create-your-first-test)
+- [Debug your tests](/docs/get-started/debugging)

docs/get-started/create-your-first-test.md

@@ -180,4 +180,5 @@ Additionally, you should see a new image file named `example.png` saved in your
 
 - [Explore sample tests](/docs/get-started/sample-tests) to see more examples.
 - [Learn more about available actions](/docs/category/actions) to expand your test capabilities.
+- [Learn about debugging tests](/docs/get-started/debugging) to troubleshoot issues and step through test execution.
 - Try modifying this test to check for different elements or add more steps.

docs/get-started/debugging.md

@@ -0,0 +1,308 @@
+---
+sidebar_position: 6
+---
+
+# Debugging Tests
+
+Doc Detective provides comprehensive debugging capabilities to help you troubleshoot and step through your tests. The debug mode system operates on a hierarchical structure, allowing you to control debugging behavior at multiple levels.
+
+## Debug Mode Hierarchy
+
+Debug settings follow a hierarchical override system:
+
+1. **Config level** - Global default (`config.debug`)
+2. **Spec level** - Overrides config (`spec.debug`) 
+3. **Test level** - Overrides spec/config (`test.debug`)
+4. **Step level** - Individual breakpoints (`step.breakpoint`)
+
+Each level can override the settings from higher levels, giving you fine-grained control over debugging behavior.
+
+## Debug Mode Values
+
+All debug properties support three values:
+
+- `false` - Disable debugging (default)
+- `true` - Enable debugging with breakpoint support  
+- `"stepThrough"` - Pause at every step waiting for user input
+
+## Configuration Level
+
+Set global debug defaults in your `.doc-detective.json` configuration file:
+
+```json
+{
+  "debug": true,
+  "input": "tests/",
+  "output": "results/"
+}
+```
+
+## Specification Level
+
+Override global debug settings for an entire test specification:
+
+```json
+{
+  "specId": "api-tests",
+  "debug": "stepThrough",
+  "tests": [
+    {
+      "steps": [
+        {
+          "checkLink": "https://api.example.com"
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Test Level
+
+Control debugging for individual tests, overriding both config and spec settings:
+
+```json
+{
+  "tests": [
+    {
+      "testId": "critical-test",
+      "debug": true,
+      "steps": [
+        {
+          "goTo": "https://example.com"
+        },
+        {
+          "find": {
+            "selector": "[name='q']"
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Step Level Breakpoints
+
+Set breakpoints on individual steps regardless of higher-level debug settings:
+
+```json
+{
+  "tests": [
+    {
+      "testId": "detailed-test",
+      "debug": "stepThrough",
+      "steps": [
+        {
+          "goTo": "https://example.com"
+        },
+        {
+          "checkLink": "https://api.example.com",
+          "breakpoint": true
+        },
+        {
+          "screenshot": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Debugging Workflows
+
+### Step-Through Debugging
+
+Use `"stepThrough"` mode to pause at every step:
+
+```json
+{
+  "testId": "step-by-step-test",
+  "debug": "stepThrough",
+  "steps": [
+    {
+      "goTo": "https://example.com"
+    },
+    {
+      "find": {
+        "selector": "input[type='search']"
+      }
+    },
+    {
+      "type": "search query"
+    }
+  ]
+}
+```
+
+### Selective Debugging
+
+Enable debugging globally but disable it for specific tests:
+
+```json
+{
+  "debug": true,
+  "tests": [
+    {
+      "testId": "fast-test",
+      "debug": false,
+      "steps": [
+        {
+          "checkLink": "https://example.com"
+        }
+      ]
+    },
+    {
+      "testId": "debug-test",
+      "steps": [
+        {
+          "goTo": "https://example.com",
+          "breakpoint": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Critical Step Breakpoints
+
+Set breakpoints only on critical steps:
+
+```json
+{
+  "tests": [
+    {
+      "testId": "api-validation",
+      "steps": [
+        {
+          "loadVariables": ".env"
+        },
+        {
+          "httpRequest": {
+            "url": "https://api.example.com/users",
+            "method": "POST"
+          },
+          "breakpoint": true
+        },
+        {
+          "screenshot": true
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Best Practices
+
+### Development vs Production
+
+Use different configurations for development and production:
+
+**Development (.doc-detective.dev.json):**
+```json
+{
+  "debug": "stepThrough",
+  "input": "tests/",
+  "logLevel": "debug"
+}
+```
+
+**Production (.doc-detective.json):**
+```json
+{
+  "debug": false,
+  "input": "tests/",
+  "logLevel": "info"
+}
+```
+
+### Debugging Complex Tests
+
+For complex tests, use a combination of approaches:
+
+```json
+{
+  "specId": "complex-workflow",
+  "debug": true,
+  "tests": [
+    {
+      "testId": "setup-test",
+      "debug": false,
+      "steps": [
+        {
+          "loadVariables": ".env"
+        }
+      ]
+    },
+    {
+      "testId": "main-test",
+      "debug": "stepThrough",
+      "steps": [
+        {
+          "goTo": "https://app.example.com"
+        },
+        {
+          "find": {
+            "selector": "#login-form"
+          },
+          "breakpoint": true
+        },
+        {
+          "type": {
+            "keys": ["$USERNAME$"]
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Debugging Failed Tests
+
+When tests fail, add breakpoints around the failing step:
+
+```json
+{
+  "steps": [
+    {
+      "goTo": "https://example.com"
+    },
+    {
+      "find": {
+        "selector": "#problematic-element"
+      },
+      "breakpoint": true
+    },
+    {
+      "click": {
+        "selector": "#problematic-element"
+      },
+      "breakpoint": true
+    }
+  ]
+}
+```
+
+## Running Tests with Debug Mode
+
+Execute tests with debug configuration:
+
+```bash
+# Use specific config with debug enabled
+npx doc-detective --config .doc-detective.dev.json
+
+# Override debug setting via command line
+npx doc-detective --debug true
+
+# Step through all tests
+npx doc-detective --debug stepThrough
+```
+
+## Next Steps
+
+- Learn about [test configuration](/docs/get-started/config/contexts)
+- Explore [action reference](/docs/get-started/actions)
+- See [troubleshooting guide](/docs/get-started/resources)

docs/get-started/intro.md

@@ -40,6 +40,10 @@ Doc Detective’s core strength is the ability to systematically check each and
 
 When Doc Detective runs tests, it can take screenshots and make recordings. You can include this media in the documentation to complement written processes, aiding the readers who prefer visual media while making sure your videos and images are up-to-date.
 
+### Debug and troubleshoot tests
+
+Doc Detective provides comprehensive debugging capabilities with breakpoint support and step-through debugging. You can control debugging behavior at multiple levels (config, specification, test, and step) to help troubleshoot failing tests and understand test execution flow.
+
 ## What can't Doc Detective do?
 
 It’s important to know your limits, and Doc Detective’s too.

docs/get-started/resources.md

@@ -8,6 +8,7 @@ There are a handful of resources to help you write and run tests:
 
 - The [Action Builder](/app) prototype is an interactive tool to help you build test actions, using the same action definitions and validations as Doc Detective itself.
 - The [Schemas](/docs/category/schemas) include detailed information about the schemas and actions available in Doc Detective.
+- The [Debugging Guide](/docs/get-started/debugging) provides comprehensive information about debugging tests with breakpoints and step-through debugging.
 - The [Discord](https://discord.gg/uAfSjVH7yr) community is a great place to ask questions and get help from other users and the maintainers.
 - The [Issue tracker](https://github.com/doc-detective/doc-detective/issues) is the best place to report bugs and request new features.
 - The [Contribution guide](https://github.com/doc-detective/doc-detective/blob/main/CONTRIBUTIONS.md) includes information about how to contribute to the project.

docs/references/schemas/common.md

@@ -16,6 +16,7 @@ Field | Type | Description | Default
 $schema | string | Optional. JSON Schema for this object.<br/><br/>Accepted values: `https://raw.githubusercontent.com/doc-detective/common/refs/heads/main/dist/schemas/step_v3.schema.json` | 
 stepId | string | Optional. ID of the step. | 
 description | string | Optional. Description of the step. | 
+breakpoint | boolean | Optional. Whether to pause execution at this step when debugging is enabled. When `true`, execution will pause at this step regardless of the debug mode setting, waiting for user input before continuing. | `false`
 unsafe | boolean | Optional. Whether or not the step may be unsafe. Unsafe steps may perform actions that could modify the system or environment in unexpected ways. Unsafe steps are only performed within Docker containers or if unsafe steps are enabled with the `allowUnsafeSteps` config property or the `--allow-unsafe` flag. | `false`
 outputs | object(Outputs (step)) | Optional. Outputs from step processes and user-defined expressions. Use the `outputs` object to reference outputs in subsequent steps. If a user-defined output matches the key for a step-defined output, the user-defined output takes precedence. | ``{}``
 variables | object(Variables (step)) | Optional. Environment variables to set from user-defined expressions. | ``{}``

docs/references/schemas/config.md

@@ -20,6 +20,7 @@ beforeAny | one of:<br/>- string<br/>- array of string | Optional. Path(s) to te
 afterAll | one of:<br/>- string<br/>- array of string | Optional. Path(s) to test specifications to perform after those specified by `input`. Useful for cleaning up testing environments. | 
 detectSteps | boolean | Optional. Whether or not to detect steps in input files based on defined markup. | `true`
 allowUnsafeSteps | boolean | Optional. Whether or not to run potentially unsafe steps, such as those that might modify files or system state. | 
+debug | one of:<br/>- boolean<br/>- string | Optional. Enable debugging mode globally. `true` allows pausing on breakpoints, waiting for user input before continuing. `stepThrough` pauses at every step, waiting for user input before continuing. `false` disables all debugging.<br/><br/>Accepted values: `false`, `true`, `stepThrough` | `false`
 logLevel | string | Optional. Amount of detail to output when performing an operation.<br/><br/>Accepted values: `silent`, `error`, `warning`, `info`, `debug` | `info`
 runOn | array of object([context](/docs/references/schemas/context)) | Optional. Contexts to run the test in. Overrides contexts defined at the config and spec levels. | 
 fileTypes | array of one of: string, object([File type (custom)](/docs/references/schemas/file-type-custom)), object([File type (executable)](/docs/references/schemas/file-type-executable)) | Optional. Configuration for file types and their markup detection. | ``["markdown","asciidoc","html"]``
@@ -118,3 +119,20 @@ environment | object([Environment details](/docs/references/schemas/environment-
   }
 }
 ```
+
+```json
+{
+  "debug": true,
+  "input": "tests/",
+  "output": "results/",
+  "logLevel": "debug"
+}
+```
+
+```json
+{
+  "debug": "stepThrough",
+  "input": "tests/critical/",
+  "allowUnsafeSteps": true
+}
+```