portfolio/n8n-workflows/TESTING-CHECKLIST.md

# ✅ Telegram CMS Workflow - Testing Checklist

## Pre-Deployment Tests

### 1. Import Verification
- [ ] Import workflow JSON into n8n successfully
- [ ] Verify all 14 nodes are present
- [ ] Check all connections are intact
- [ ] Confirm credentials are linked (DK0_Server)
- [ ] Activate workflow without errors

### 2. Command Parsing Tests

#### Basic Commands
- [ ] Send `/start` → Receives dashboard with stats
- [ ] Send `/list projects` → Gets paginated project list
- [ ] Send `/list books` → Gets book review list
- [ ] Send `/search test` → Gets search results
- [ ] Send `/stats` → Gets statistics dashboard

#### Item Management
- [ ] Send `/preview<ID>` → Gets item preview with translations
- [ ] Send `/publish<ID>` → Successfully publishes item
- [ ] Send `/delete<ID>` → Successfully deletes item
- [ ] Send `/deletereview<ID>` → Removes review translations

#### Legacy Commands (Backward Compatibility)
- [ ] Send `/publishproject<ID>` → Works correctly
- [ ] Send `/publishbook<ID>` → Works correctly
- [ ] Send `/deleteproject<ID>` → Works correctly
- [ ] Send `/deletebook<ID>` → Works correctly

#### AI Review Creation
- [ ] Send `.review 12345 5 Test review` → Creates review with AI
- [ ] Send `/review 12345 5 Test review` → Also works with slash
- [ ] Verify EN review is generated
- [ ] Verify DE review is generated
- [ ] Check rating is set correctly
- [ ] Confirm status is "draft"

#### Error Handling
- [ ] Send `/unknown` → Gets help message
- [ ] Send `/preview999999` → Gets "not found" error
- [ ] Send `.review invalid` → Gets format error
- [ ] Test with empty search term
- [ ] Test with special characters in search

---

## Node-by-Node Tests

### 1. Telegram Trigger
- [ ] Receives messages correctly
- [ ] Extracts chat ID
- [ ] Passes data to Parse Command node

### 2. Parse Command
- [ ] Correctly identifies `/start` command
- [ ] Parses `/list projects` vs `/list books`
- [ ] Extracts search query from `/search <term>`
- [ ] Parses item IDs from commands
- [ ] Handles `.review` with correct regex
- [ ] Returns unknown action for invalid commands

### 3. Command Router (Switch)
- [ ] Routes to Dashboard Handler for "start"
- [ ] Routes to List Handler for "list"
- [ ] Routes to Search Handler for "search"
- [ ] Routes to Stats Handler for "stats"
- [ ] Routes to Preview Handler for "preview"
- [ ] Routes to Publish Handler for "publish"
- [ ] Routes to Delete Handler for "delete"
- [ ] Routes to Delete Review Handler for "delete_review"
- [ ] Routes to Create Review Handler for "create_review"
- [ ] Routes to Unknown Handler for unrecognized commands

### 4. Dashboard Handler
- [ ] Fetches draft projects count from Directus
- [ ] Fetches draft books count from Directus
- [ ] Formats message with stats
- [ ] Includes all command examples
- [ ] Uses Markdown formatting
- [ ] Handles API errors gracefully

### 5. List Handler
- [ ] Supports both "projects" and "books" types
- [ ] Limits to 5 items per page
- [ ] Shows correct fields (title, category, status, date)
- [ ] Includes action buttons for each item
- [ ] Displays pagination hint if more items exist
- [ ] Handles empty results
- [ ] Catches and reports errors

### 6. Search Handler
- [ ] Searches projects by title
- [ ] Searches books by title
- [ ] Uses Directus `_contains` filter
- [ ] Groups results by type
- [ ] Limits to 5 results per collection
- [ ] Handles no results found
- [ ] URL-encodes search query
- [ ] Error handling works

### 7. Stats Handler
- [ ] Calculates total project count
- [ ] Breaks down by status (published/draft/archived)
- [ ] Calculates book statistics
- [ ] Computes average rating correctly
- [ ] Groups projects by category
- [ ] Sorts categories by count
- [ ] Formats with emojis
- [ ] Handles empty data

### 8. Preview Handler
- [ ] Auto-detects projects first
- [ ] Falls back to books if not found
- [ ] Shows both EN and DE translations
- [ ] Displays metadata (status, category, rating)
- [ ] Truncates long text with "..."
- [ ] Provides action buttons
- [ ] Returns 404 if not found
- [ ] Error messages are clear

### 9. Publish Handler
- [ ] Tries projects collection first
- [ ] Falls back to books collection
- [ ] Updates status to "published"
- [ ] Returns success message
- [ ] Handles 404 gracefully
- [ ] Uses correct HTTP method (PATCH)
- [ ] Includes auth token
- [ ] Error handling works

### 10. Delete Handler
- [ ] Tries projects collection first
- [ ] Falls back to books collection
- [ ] Permanently removes item
- [ ] Returns confirmation message
- [ ] Handles 404 gracefully
- [ ] Uses correct HTTP method (DELETE)
- [ ] Includes auth token
- [ ] Error handling works

### 11. Delete Review Handler
- [ ] Fetches book review by ID
- [ ] Gets translation IDs
- [ ] Deletes all translations
- [ ] Keeps book entry intact
- [ ] Reports count of deleted translations
- [ ] Handles missing reviews
- [ ] Error handling works

### 12. Create Review Handler
- [ ] Fetches book by Hardcover ID
- [ ] Builds AI prompt correctly
- [ ] Calls OpenRouter API
- [ ] Parses JSON from AI response
- [ ] Handles malformed AI output
- [ ] Creates EN translation
- [ ] Creates DE translation
- [ ] Sets rating correctly
- [ ] Sets status to "draft"
- [ ] Returns formatted message with preview
- [ ] Provides action buttons
- [ ] Error handling works

### 13. Unknown Command Handler
- [ ] Returns help message
- [ ] Lists all available commands
- [ ] Uses Markdown formatting
- [ ] Includes examples

### 14. Send Telegram Message
- [ ] Uses chat ID from input
- [ ] Sends message text correctly
- [ ] Applies Markdown parse mode
- [ ] Uses correct credentials
- [ ] Returns successfully

---

## Integration Tests

### Directus API
- [ ] Authentication works with token
- [ ] GET requests succeed
- [ ] PATCH requests update items
- [ ] DELETE requests remove items
- [ ] GraphQL queries work (if used)
- [ ] Translation relationships load
- [ ] Filters work correctly
- [ ] Aggregations return data
- [ ] Pagination parameters work

### OpenRouter AI
- [ ] API key is valid
- [ ] Model name is correct
- [ ] Prompt format works
- [ ] JSON parsing succeeds
- [ ] Fallback handles non-JSON
- [ ] Rate limits are respected
- [ ] Timeout is reasonable

### Telegram Bot
- [ ] Bot token is valid
- [ ] Chat ID is correct
- [ ] Messages send successfully
- [ ] Markdown formatting works
- [ ] Emojis display correctly
- [ ] Long messages don't truncate
- [ ] Error messages are readable

---

## Error Scenarios

### API Failures
- [ ] Directus is unreachable → User-friendly error
- [ ] Directus returns 401 → Auth error message
- [ ] Directus returns 404 → Item not found message
- [ ] Directus returns 500 → Generic error message
- [ ] OpenRouter fails → Review creation fails gracefully
- [ ] Telegram API fails → Workflow logs error

### Data Issues
- [ ] Empty search results → "No results" message
- [ ] Missing translations → Shows available languages
- [ ] Invalid item ID → "Not found" error
- [ ] Malformed AI response → Uses fallback text
- [ ] No Hardcover ID match → Clear error message

### User Errors
- [ ] Invalid command format → Help message
- [ ] Missing parameters → Format example
- [ ] Wrong item type → Auto-detection handles it
- [ ] Non-numeric ID → Validation error

---

## Performance Tests

- [ ] Dashboard loads in < 2 seconds
- [ ] List loads in < 2 seconds
- [ ] Search completes in < 2 seconds
- [ ] Preview loads in < 1 second
- [ ] Publish/delete complete in < 1 second
- [ ] AI review generates in < 5 seconds
- [ ] No timeout errors with normal load
- [ ] Concurrent requests don't conflict

---

## Security Tests

- [ ] API token not exposed in logs
- [ ] Error messages don't leak sensitive data
- [ ] Chat ID validation works
- [ ] Only authorized user can access (check bot settings)
- [ ] SQL injection is impossible (using REST API)
- [ ] XSS is prevented (Markdown escaping)

---

## User Experience Tests

- [ ] Messages are easy to read
- [ ] Emojis enhance clarity
- [ ] Action buttons are clear
- [ ] Error messages are helpful
- [ ] Success messages are satisfying
- [ ] Command examples are accurate
- [ ] Help message is comprehensive

---

## Regression Tests

After any changes:
- [ ] Re-run all command parsing tests
- [ ] Verify all handlers still work
- [ ] Check error handling didn't break
- [ ] Confirm AI review still generates
- [ ] Test backward compatibility

---

## Deployment Checklist

### Pre-Deployment
- [ ] All tests pass
- [ ] Workflow is exported
- [ ] Documentation is updated
- [ ] Credentials are configured
- [ ] Environment variables set

### Deployment
- [ ] Import workflow to production n8n
- [ ] Activate workflow
- [ ] Test `/start` command
- [ ] Monitor execution logs
- [ ] Verify Directus connection
- [ ] Check Telegram bot responds

### Post-Deployment
- [ ] Run smoke tests (start, list, search)
- [ ] Create test review
- [ ] Publish test item
- [ ] Monitor for 24 hours
- [ ] Check error logs
- [ ] Confirm no false positives

---

## Monitoring

Daily:
- [ ] Check n8n execution logs
- [ ] Review error count
- [ ] Verify success rate > 95%

Weekly:
- [ ] Test all commands manually
- [ ] Review API usage
- [ ] Check for rate limiting
- [ ] Update this checklist

Monthly:
- [ ] Full regression test
- [ ] Update documentation
- [ ] Review and optimize queries
- [ ] Check for n8n updates

---

## Rollback Plan

If issues occur:
1. Deactivate workflow in n8n
2. Revert to previous version
3. Investigate logs
4. Fix in staging
5. Re-test thoroughly
6. Deploy again

---

## Sign-off

- [ ] All critical tests pass
- [ ] Documentation complete
- [ ] Team notified
- [ ] Backup created
- [ ] Ready for production

**Tested by:** _________________  
**Date:** _________________  
**Version:** 1.0.0  
**Status:** ✅ Production Ready

---

## Notes

Use this space for test observations:

```
Test Run 1 (2025-01-21):
- All commands working
- AI generation successful
- No errors in 50 test messages
- Performance excellent
```