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