nextcloud-integration/TEST-PLAN.md

Nextcloud Mail Tool - Testing Plan

Tool: nextcloud-mail Test Environment: https://teamworkapps.com (Nextcloud 25.0.13) Date: 2026-02-20

---

Pre-Test Setup

1. Build Verification

cd projects/nextcloud-integration

# Run build script with your credentials
./build.sh https://teamworkapps.com <username> <password_or_token>

# Verify binary exists
ls -lh ~/bin/nextcloud-mail

# Verify binary is executable
file ~/bin/nextcloud-mail

Expected Results:

• Binary exists at ~/bin/nextcloud-mail
• Binary is executable (ELF executable)
• Size should be ~7-8MB (static build with dependencies)

2. Credential Verification

# Test basic connectivity (should succeed if credentials are correct)
~/bin/nextcloud-mail --op list-folders

Expected Results:

• Lists at least INBOX folder
• No authentication errors
• No SSL/TLS certificate errors (unless --ignore-certs is set)

---

Test Suite 1: IMAP Operations

Test 1.1: List Folders

Purpose: Verify IMAP connectivity and folder discovery

~/bin/nextcloud-mail --op list-folders

Expected Results:

• Lists all IMAP folders/mailboxes
• Shows: INBOX, Sent, Drafts, Trash, Archive (or similar)
• Output format:

  IMAP Folders:
    INBOX
    Sent
    Drafts
    Trash
    Archive
  

Pass Criteria:

• ✅ At least 3 folders listed
• ✅ INBOX folder exists
• ✅ No errors

---

Test 1.2: List Messages (Page 1)

Purpose: Verify message listing with pagination

~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 10

Expected Results:

• Lists messages in INBOX (up to 10)
• Shows UID, From, To, Subject, Date
• Output format:

  Messages in INBOX (Page 1 of X, showing Y-Z of N):
  
  UID: 1234
    From: John Doe <john@example.com>
    To: me@example.com
    Subject: Test Email
    Date: Fri, 20 Feb 2026 17:00:00 +0000
  

Pass Criteria:

• ✅ Header shows correct pagination info
• ✅ Messages listed with all fields (UID, From, To, Subject, Date)
• ✅ Handles empty INBOX gracefully
• ✅ No errors

---

Test 1.3: List Messages (Pagination)

Purpose: Verify pagination works correctly

# Page 1
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 5

# Page 2
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 2 --page-size 5

Expected Results:

• Page 1 and Page 2 show different messages
• Total message count consistent
• Pagination math correct (showing X-Y of N)

Pass Criteria:

• ✅ Page 1 ≠ Page 2 (different messages)
• ✅ Total count consistent
• ✅ Page numbers update correctly

---

Test 1.4: List Messages (Different Folders)

Purpose: Verify folder selection works

# List in Sent folder
~/bin/nextcloud-mail --op list-messages --folder Sent --page 1 --page-size 5

# List in Drafts folder
~/bin/nextcloud-mail --op list-messages --folder Drafts --page 1 --page-size 5

Expected Results:

• Different folders show different messages
• Sent folder has outbound messages
• Drafts folder has draft messages (if any)

Pass Criteria:

• ✅ Folder selection works
• ✅ Different content in different folders
• ✅ No errors for empty folders

---

Test 1.5: Get Message Content

Purpose: Verify message body retrieval

# First, list messages to get a UID
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 1

# Get that message's content
~/bin/nextcloud-mail --op get-message --folder INBOX --uids 1234

Expected Results:

• Displays message UID, From, Subject
• Prints message body (text/plain)
• Output includes full message content

Pass Criteria:

• ✅ Message content displayed
• ✅ Body is readable text
• ✅ No truncation errors

---

Test 1.6: Search Messages

Purpose: Verify server-side search

# Search for common term
~/bin/nextcloud-mail --op search --folder INBOX --query "test"

# Search for another term
~/bin/nextcloud-mail --op search --folder INBOX --query "meeting"

Expected Results:

• Returns matching messages
• Shows UID, From, Subject, Date
• No results message if nothing matches

Pass Criteria:

• ✅ Search finds relevant messages
• ✅ Empty search handled gracefully
• ✅ Query parameter respected

---

Test Suite 2: Attachment Operations

Test 2.1: List Attachments

Purpose: Verify attachment detection

# Get a message with attachments
~/bin/nextcloud-mail --op get-message --folder INBOX --uids 1234 --list-attachments

Expected Results:

• Lists all attachments
• Shows filename, content type, and part path
• Output format:

  UID: 1234
    From: John Doe <john@example.com>
    Subject: Email with attachments
    Attachments (2):
      1. report.pdf (application/pdf) - Part: 1.2
      2. image.png (image/png) - Part: 1.3
  

Pass Criteria:

• ✅ All attachments listed
• ✅ Correct content types shown
• ✅ Part paths displayed
• ✅ Shows 0 attachments for messages without any

---

Test 2.2: Save Attachments

Purpose: Verify attachment download

# Create test directory
mkdir -p /tmp/mail-attachments

# Save attachments
~/bin/nextcloud-mail --op get-message --folder INBOX --uids 1234 \
  --save-attachments --save-dir /tmp/mail-attachments

# Verify files exist
ls -lh /tmp/mail-attachments

Expected Results:

• Attachments saved to specified directory
• Original filenames preserved
• File sizes reasonable (not 0 bytes)
• Output:

  Saving attachments to /tmp/mail-attachments:
    Saved: report.pdf (1024576 bytes)
    Saved: image.png (45678 bytes)
  

Pass Criteria:

• ✅ All attachments saved
• ✅ Filenames match original
• ✅ File sizes > 0 bytes
• ✅ Files are valid (can open PDF, images, etc.)

Validation Commands:

# Check PDF is valid
file /tmp/mail-attachments/report.pdf
# Should show: PDF document

# Check image is valid
file /tmp/mail-attachments/image.png
# Should show: PNG image data

---

Test 2.3: Multiple Attachments

Purpose: Verify handling of multiple attachments in one message

# Find message with 3+ attachments
# Then test:
~/bin/nextcloud-mail --op get-message --folder INBOX --uids <uid> \
  --save-attachments --save-dir /tmp/multi-attachments

# Count downloaded files
ls -1 /tmp/multi-attachments | wc -l

Expected Results:

• All attachments downloaded
• No files skipped
• Correct count matches message attachment count

Pass Criteria:

• ✅ All attachments saved
• ✅ No download errors
• ✅ File count matches

---

Test Suite 3: SMTP Operations

Test 3.1: Send Simple Email

Purpose: Verify basic email sending

# Send test email to yourself
~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to <your-email> \
  --subject "nextcloud-mail Test - Simple Email" \
  --body "This is a test email from nextcloud-mail tool."

Expected Results:

• Command completes without errors
• Message: "Email sent successfully"
• Email appears in INBOX or Sent folder

Pass Criteria:

• ✅ Command exits with code 0
• ✅ "Email sent successfully" message
• ✅ Email appears in INBOX (if you CC yourself)

Verification:

# Wait 10 seconds, then check INBOX
sleep 10
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 1 | grep "Test - Simple Email"

---

Test 3.2: Send Email to Multiple Recipients

Purpose: Verify multiple recipient handling

~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to "recipient1@example.com,recipient2@example.com" \
  --subject "nextcloud-mail Test - Multiple Recipients" \
  --body "This email was sent to multiple recipients."

Expected Results:

• Email sent successfully
• All recipients receive the email

Pass Criteria:

• ✅ Command succeeds
• ✅ Multiple recipients parsed correctly
• ✅ No errors

---

Test 3.3: Send Email with Single Attachment

Purpose: Verify attachment sending

# Create test file
echo "This is a test attachment." > /tmp/test-attachment.txt

# Send email
~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to <your-email> \
  --subject "nextcloud-mail Test - Single Attachment" \
  --body "Email with one attachment." \
  --attachments "/tmp/test-attachment.txt"

Expected Results:

• Email sent successfully
• Attachment included in email

Pass Criteria:

• ✅ Command succeeds
• ✅ Attachment appears in received email
• ✅ Attachment content is correct

Verification:

# After receiving, check attachment:
~/bin/nextcloud-mail --op get-message --folder INBOX --uids <uid> --list-attachments
# Should show: test-attachment.txt

---

Test 3.4: Send Email with Multiple Attachments

Purpose: Verify multiple attachment handling

# Create test files
echo "Attachment 1" > /tmp/att1.txt
echo "Attachment 2" > /tmp/att2.txt
echo "Attachment 3" > /tmp/att3.txt

# Send email
~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to <your-email> \
  --subject "nextcloud-mail Test - Multiple Attachments" \
  --body "Email with three attachments." \
  --attachments "/tmp/att1.txt,/tmp/att2.txt,/tmp/att3.txt"

Expected Results:

• Email sent successfully
• All 3 attachments included

Pass Criteria:

• ✅ Command succeeds
• ✅ All 3 attachments present
• ✅ All attachments correct size

Verification:

~/bin/nextcloud-mail --op get-message --folder INBOX --uids <uid> --list-attachments
# Should show: 3 attachments

---

Test 3.5: Send Large Attachment

Purpose: Verify large file handling

# Create 1MB test file
dd if=/dev/zero of=/tmp/large-file.bin bs=1024 count=1024

# Send email
~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to <your-email> \
  --subject "nextcloud-mail Test - Large Attachment" \
  --body "Email with 1MB attachment." \
  --attachments "/tmp/large-file.bin"

Expected Results:

• Email sent successfully (or timeout if server has size limit)
• Attachment included

Pass Criteria:

• ✅ Command succeeds (within reasonable time)
• ✅ Attachment intact
• ✅ No corruption

---

Test Suite 4: Message Management

Test 4.1: Move Message to Archive

Purpose: Verify message moving

# First, note a message UID
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 1

# Move it to Archive
~/bin/nextcloud-mail --op move-messages \
  --folder INBOX --uids 1234 \
  --dest-folder Archive

# Verify it's gone from INBOX
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 10 | grep 1234
# Should not find the UID

# Verify it's in Archive
~/bin/nextcloud-mail --op list-messages --folder Archive --page 1 --page-size 10 | grep 1234
# Should find the UID

Expected Results:

• Message removed from INBOX
• Message appears in Archive
• Command output: "Messages moved successfully"

Pass Criteria:

• ✅ Message moves correctly
• ✅ No duplication
• ✅ UID preserved

---

Test 4.2: Move Multiple Messages

Purpose: Verify bulk move operation

# Get UIDs of 2-3 messages
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 3

# Move them
~/bin/nextcloud-mail --op move-messages \
  --folder INBOX --uids 1234,1235,1236 \
  --dest-folder Archive

# Verify all moved
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1

Expected Results:

• All messages moved
• None remain in INBOX
• All appear in Archive

Pass Criteria:

• ✅ All UIDs moved
• ✅ No partial failures
• ✅ Command succeeds

---

Test 4.3: Delete Message

Purpose: Verify message deletion

# First, find a test message (preferably one you created)
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 1

# Delete it
~/bin/nextcloud-mail --op delete-messages --folder INBOX --uids 1234

# Verify it's gone
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 10 | grep 1234
# Should not find the UID

Expected Results:

• Message deleted from INBOX
• Command output: "Messages deleted successfully"

Pass Criteria:

• ✅ Message removed permanently
• ✅ UID no longer listed
• ✅ No errors

---

Test 4.4: Delete Multiple Messages

Purpose: Verify bulk deletion

# Get UIDs of test messages
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 5

# Delete them
~/bin/nextcloud-mail --op delete-messages --folder INBOX --uids 1234,1235,1236

# Verify all gone
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 10

Expected Results:

• All messages deleted
• Command succeeds

Pass Criteria:

• ✅ All UIDs deleted
• ✅ No partial failures
• ✅ Count reduced appropriately

---

Test Suite 5: SSL/TLS and Security

Test 5.1: SSL/TLS Connection (Default)

Purpose: Verify secure connection

# Default should be SSL
~/bin/nextcloud-mail --op list-folders

Expected Results:

• Successful connection
• No certificate errors

Pass Criteria:

• ✅ Connects successfully
• ✅ Uses SSL/TLS
• ✅ No warnings

---

Test 5.2: Ignore Certificate Validation

Purpose: Verify self-signed cert support

# Try with ignore-certs (useful for testing)
~/bin/nextcloud-mail --op list-folders --ignore-certs=true

Expected Results:

• Connects even if cert is self-signed
• No certificate validation errors

Pass Criteria:

• ✅ Connects regardless of cert validity
• ✅ No cert-related errors

---

Test 5.3: STARTTLS (Non-SSL Port)

Purpose: Verify STARTTLS support

# Try non-SSL connection
~/bin/nextcloud-mail --op list-folders --ssl=false

Expected Results:

• Connects via STARTTLS if supported
• Fails gracefully if not supported

Pass Criteria:

• ✅ Works with STARTTLS if server supports it
• ✅ Clear error message if not supported

---

Test Suite 6: Error Handling

Test 6.1: Invalid Credentials

Purpose: Verify error handling

# Test with wrong password
~/bin/nextcloud-mail --op list-folders \
  --imap-user <wrong-user> \
  --imap-pass <wrong-pass>

Expected Results:

• Clear error message
• No crash

Pass Criteria:

• ✅ "IMAP login failed" or similar error
• ✅ Command exits with non-zero code
• ✅ No panic/crash

---

Test 6.2: Invalid Folder Name

Purpose: Verify folder error handling

# Try to access non-existent folder
~/bin/nextcloud-mail --op list-messages --folder NonExistentFolder --page 1

Expected Results:

• Clear error message
• "failed to select folder" or similar

Pass Criteria:

• ✅ Descriptive error
• ✅ Command exits with non-zero code
• ✅ No crash

---

Test 6.3: Invalid Message UID

Purpose: Verify UID error handling

# Try to get non-existent message
~/bin/nextcloud-mail --op get-message --folder INBOX --uids 999999999

Expected Results:

• "Message UID 999999999 not found" or similar
• Command continues

Pass Criteria:

• ✅ Graceful handling
• ✅ Clear error message
• ✅ No crash

---

Test 6.4: Missing Required Parameters

Purpose: Verify parameter validation

# Missing --folder
~/bin/nextcloud-mail --op list-messages

# Missing --uids
~/bin/nextcloud-mail --op get-message --folder INBOX

# Missing --from and --to
~/bin/nextcloud-mail --op send-email

Expected Results:

• Clear error messages
• Usage hints

Pass Criteria:

• ✅ "Error: --folder is required" or similar
• ✅ Command exits with non-zero code
• ✅ Helpful error messages

---

Test 6.5: Missing Attachment File

Purpose: Verify file error handling

# Try to send with non-existent attachment
~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to <your-email> \
  --subject "Test" \
  --body "Test" \
  --attachments "/tmp/non-existent-file.txt"

Expected Results:

• Error about missing file
• Command fails gracefully

Pass Criteria:

• ✅ "failed to read attachment" or similar
• ✅ Command exits with non-zero code
• ✅ No partial email sent

---

Test Suite 7: Edge Cases

Test 7.1: Empty Folder

Purpose: Verify empty folder handling

# List messages in empty folder
~/bin/nextcloud-mail --op list-messages --folder EmptyFolder --page 1

Expected Results:

• "No messages in folder" or similar
• No errors

Pass Criteria:

• ✅ Graceful handling
• ✅ No crash
• ✅ Clear message

---

Test 7.2: Very Long Subject

Purpose: Verify long string handling

# Create long subject
LONG_SUBJECT="This is a very long subject that exceeds normal length to test how the tool handles it without truncation or errors"

# Send email
~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to <your-email> \
  --subject "$LONG_SUBJECT" \
  --body "Long subject test"

Expected Results:

• Email sent successfully
• Subject preserved

Pass Criteria:

• ✅ Subject not truncated
• ✅ No encoding errors
• ✅ Email appears correctly

---

Test 7.3: Special Characters in Subject

Purpose: Verify character encoding

~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to <your-email> \
  --subject "Test: émojis 🎉 and spëcial chårs" \
  --body "Special characters test"

Expected Results:

• Email sent successfully
• Characters preserved

Pass Criteria:

• ✅ Unicode characters preserved
• ✅ Subject displays correctly
• ✅ No encoding errors

---

Test 7.4: Empty Body

Purpose: Verify empty body handling

~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to <your-email> \
  --subject "Test with empty body" \
  --body ""

Expected Results:

• Email sent successfully
• Body is empty but valid

Pass Criteria:

• ✅ Email delivered
• ✅ No validation errors
• ✅ Empty body is acceptable

---

Test Suite 8: Performance

Test 8.1: Large Folder Listing

Purpose: Verify performance with many messages

# List with large page size
time ~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 100

Expected Results:

• Completes in reasonable time (< 10 seconds)
• No timeouts

Pass Criteria:

• ✅ Completes within 10 seconds
• ✅ No memory issues
• ✅ All messages listed

---

Test 8.2: Many Attachments Download

Purpose: Verify attachment download performance

# Test with message containing 10+ attachments
# Then:
time ~/bin/nextcloud-mail --op get-message --folder INBOX --uids <uid> \
  --save-attachments --save-dir /tmp/many-attachments

Expected Results:

• All attachments downloaded
• Reasonable time

Pass Criteria:

• ✅ All attachments saved
• ✅ Completes in reasonable time
• ✅ No timeouts

---

Test Suite 9: Integration Workflow

Test 9.1: Full Email Workflow

Purpose: Verify complete email lifecycle

# Step 1: Send email with attachments
echo "Test attachment content" > /tmp/workflow-test.txt
~/bin/nextcloud-mail --op send-email \
  --from <your-email> \
  --to <your-email> \
  --subject "Integration Workflow Test" \
  --body "This is a workflow test." \
  --attachments "/tmp/workflow-test.txt"

# Step 2: Wait and find the email
sleep 10
~/bin/nextcloud-mail --op list-messages --folder INBOX --page 1 --page-size 5 | grep "Integration Workflow Test"

# Step 3: Get the message UID and retrieve
~/bin/nextcloud-mail --op get-message --folder INBOX --uids <uid>

# Step 4: List attachments
~/bin/nextcloud-mail --op get-message --folder INBOX --uids <uid> --list-attachments

# Step 5: Save attachments
mkdir -p /tmp/workflow-attachments
~/bin/nextcloud-mail --op get-message --folder INBOX --uids <uid> \
  --save-attachments --save-dir /tmp/workflow-attachments

# Step 6: Verify attachment
cat /tmp/workflow-attachments/workflow-test.txt

# Step 7: Search for it
~/bin/nextcloud-mail --op search --folder INBOX --query "Integration Workflow Test"

# Step 8: Move to Archive
~/bin/nextcloud-mail --op move-messages --folder INBOX --uids <uid> --dest-folder Archive

# Step 9: Verify it's in Archive
~/bin/nextcloud-mail --op list-messages --folder Archive --page 1 --page-size 1 | grep "Integration Workflow Test"

# Step 10: Delete from Archive
~/bin/nextcloud-mail --op delete-messages --folder Archive --uids <uid>

Expected Results:

• All 10 steps complete successfully
• Attachment preserved through all steps
• Search finds the email
• Move and delete work correctly

Pass Criteria:

• ✅ All steps succeed
• ✅ Attachment intact throughout
• ✅ No data loss
• ✅ Workflow complete

---

Test Execution Checklist

Use this checklist to track test completion:

Pre-Test

• Build verification
• Credential verification

IMAP Operations

• Test 1.1: List Folders
• Test 1.2: List Messages (Page 1)
• Test 1.3: List Messages (Pagination)
• Test 1.4: List Messages (Different Folders)
• Test 1.5: Get Message Content
• Test 1.6: Search Messages

Attachment Operations

• Test 2.1: List Attachments
• Test 2.2: Save Attachments
• Test 2.3: Multiple Attachments

SMTP Operations

• Test 3.1: Send Simple Email
• Test 3.2: Send Email to Multiple Recipients
• Test 3.3: Send Email with Single Attachment
• Test 3.4: Send Email with Multiple Attachments
• Test 3.5: Send Large Attachment

Message Management

• Test 4.1: Move Message to Archive
• Test 4.2: Move Multiple Messages
• Test 4.3: Delete Message
• Test 4.4: Delete Multiple Messages

SSL/TLS and Security

• Test 5.1: SSL/TLS Connection (Default)
• Test 5.2: Ignore Certificate Validation
• Test 5.3: STARTTLS (Non-SSL Port)

Error Handling

• Test 6.1: Invalid Credentials
• Test 6.2: Invalid Folder Name
• Test 6.3: Invalid Message UID
• Test 6.4: Missing Required Parameters
• Test 6.5: Missing Attachment File

Edge Cases

• Test 7.1: Empty Folder
• Test 7.2: Very Long Subject
• Test 7.3: Special Characters in Subject
• Test 7.4: Empty Body

Performance

• Test 8.1: Large Folder Listing
• Test 8.2: Many Attachments Download

Integration Workflow

• Test 9.1: Full Email Workflow

---

Test Results Template

After running tests, fill in results:

# Test Results - [Date]

## Build Information
- Commit: [commit-hash]
- Built: [timestamp]
- Binary size: [size]

## Test Summary
- Total tests: 38
- Passed: [number]
- Failed: [number]
- Success rate: [percentage]%

## Failed Tests
- [Test X.Y]: [description]
  - Expected: [what should happen]
  - Actual: [what actually happened]
  - Notes: [debugging info]

## Issues Found
- [Issue 1]: [description]
  - Severity: [low/medium/high]
  - Impact: [what it affects]

## Recommendations
1. [recommendation 1]
2. [recommendation 2]

---

Notes

• All tests assume credentials are embedded via build script
• Adjust UIDs, emails, and paths to match your environment
• Some tests may require you to create test emails first
• Test 9.1 is the most comprehensive - run it last to verify everything works

---

Test Plan: 2026-02-20