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
See Also
test
command - Command reference- Template Variables - Template syntax
- Custom Filters - Filter reference