Testing and Debugging Guide

This guide covers testing strategies, debugging techniques, and best practices for working with SwissArmyHammer prompts.

Interactive Testing

Basic Testing Workflow

The test command provides an interactive environment for testing prompts:

# Start interactive testing
swissarmyhammer test code-review

This will:

Load the specified prompt
Prompt for required arguments
Show optional arguments with defaults
Render the template
Display the result
Offer additional actions (copy, save, retry)

Testing with Predefined Arguments

# Test with known arguments
swissarmyhammer test code-review \
  --arg code="fn main() { println!(\"Hello\"); }" \
  --arg language="rust"

# Copy result directly to clipboard
swissarmyhammer test email-template \
  --arg recipient="John" \
  --arg subject="Meeting" \
  --copy

Debugging Template Issues

Common Template Problems

Missing Variables

<!-- Problem: undefined variable -->
Hello {{name}}

<!-- Solution: provide default -->
Hello {{ name | default: "Guest" }}

Type Mismatches

<!-- Problem: trying to use string methods on numbers -->
{{ count | upcase }}

<!-- Solution: convert types -->
{{ count | append: " items" }}

Loop Issues

<!-- Problem: not checking for empty arrays -->
{% for item in items %}
  - {{ item }}
{% endfor %}

<!-- Solution: check array exists and has items -->
{% if items and items.size > 0 %}
  {% for item in items %}
    - {{ item }}
  {% endfor %}
{% else %}
  No items found.
{% endif %}

Debug Mode

Use debug mode to see detailed template processing:

swissarmyhammer test prompt-name --debug

Debug output includes:

Variable resolution steps
Filter application results
Conditional evaluation
Loop iteration details
Performance timing

Validation Strategies

Argument Validation

Test with different argument combinations:

# Test required arguments only
swissarmyhammer test prompt-name --arg required_arg="value"

# Test with all arguments
swissarmyhammer test prompt-name \
  --arg required_arg="value" \
  --arg optional_arg="optional_value"

# Test with edge cases
swissarmyhammer test prompt-name \
  --arg text="" \
  --arg number="0" \
  --arg array="[]"

Template Edge Cases

Create test cases for common scenarios:

Empty inputs
Very long inputs
Special characters
Unicode content
Null/undefined values

Automated Testing

For prompt libraries, create test scripts:

#!/bin/bash
# test-all-prompts.sh

PROMPTS=$(swissarmyhammer search --json "" --limit 100 | jq -r '.results[].id')

for prompt in $PROMPTS; do
    echo "Testing $prompt..."
    if swissarmyhammer test "$prompt" --arg placeholder="test" 2>/dev/null; then
        echo "✓ $prompt"
    else
        echo "✗ $prompt"
    fi
done

Performance Testing

Measuring Render Time

# Time a complex template
time swissarmyhammer test complex-template \
  --arg large_data="$(cat large-file.json)"

# Use debug mode for detailed timing
swissarmyhammer test template-name --debug | grep "Performance:"

Memory Usage Testing

For large templates or data:

# Monitor memory usage during rendering
/usr/bin/time -v swissarmyhammer test large-template \
  --arg big_data="$(cat massive-dataset.json)"

Best Practices

Writing Testable Prompts

Provide sensible defaults for optional arguments
Handle empty/null inputs gracefully
Use meaningful argument names
Include example values in descriptions
Test with realistic data sizes

Testing Workflow

Start simple: Test with minimal arguments
Add complexity: Test with full argument sets
Test edge cases: Empty, null, large inputs
Validate output: Ensure rendered content makes sense
Performance check: Verify reasonable render times

Debugging Tips

Use debug mode for complex templates
Test filters individually in simple templates
Validate JSON/YAML with external tools
Check argument types match expectations
Use raw mode to see unprocessed templates

Integration with Development

IDE Integration

Many editors support SwissArmyHammer testing:

# VS Code task example
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Test Current Prompt",
      "type": "shell",
      "command": "swissarmyhammer",
      "args": ["test", "${fileBasenameNoExtension}"],
      "group": "test",
      "presentation": {
        "echo": true,
        "reveal": "always",
        "focus": false,
        "panel": "shared"
      }
    }
  ]
}

Continuous Integration

Add prompt testing to CI pipelines:

# .github/workflows/test-prompts.yml
name: Test Prompts
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install SwissArmyHammer
        run: cargo install --git https://github.com/wballard/swissarmyhammer.git swissarmyhammer-cli
      - name: Test all prompts
        run: |
          for prompt in prompts/*.md; do
            name=$(basename "$prompt" .md)
            echo "Testing $name..."
            swissarmyhammer test "$name" --arg test="ci_validation"
          done

SwissArmyHammer Documentation