mail2couch/test/README.md

mail2couch Test Environment

This directory contains a complete test environment for mail2couch using Podman containers.

Overview

The test environment provides:

• CouchDB: Database for storing email messages
• GreenMail IMAP Server: Java-based mail server designed for testing with pre-populated test accounts and messages
• Test Configuration: Ready-to-use config for testing both sync and archive modes

Quick Start

Run Full Integration Tests

./run-tests.sh

This will:

1. Start all containers
2. Populate test data
3. Run mail2couch
4. Verify results
5. Clean up

Run Wildcard Pattern Tests

./test-wildcard-patterns.sh

This will test various wildcard folder patterns including:

• * (all folders)
• Work* (prefix patterns)
• */Drafts (subfolder patterns)
• Complex include/exclude combinations

Manual Testing

# Start test environment
./start-test-env.sh

# Run mail2couch manually
cd ../go
./mail2couch -config ../test/config-test.json

# Stop test environment when done
cd ../test
./stop-test-env.sh

Test Accounts

The test environment includes these IMAP accounts:

Username	Password	Mode	Folder Pattern	Purpose
testuser1	password123	archive	* (exclude Drafts, Trash)	Wildcard all folders test
syncuser	syncpass	sync	Work*, Important*, INBOX	Work pattern test
archiveuser	archivepass	archive	INBOX, Sent, Personal	Specific folders test
testuser2	password456	archive	Work/*, Archive/*	Subfolder pattern test

Each account contains:

• 10 messages in INBOX (every 3rd has an attachment)
• 3 messages in each additional folder
• Test folders: Sent, Work/Projects, Work/Archive, Work/Temp, Personal, Important/Urgent, Important/Meetings, Archive/2024, Archive/Projects, Archive/Drafts, Drafts, Trash
• Various message types for comprehensive wildcard testing

Services

CouchDB

• URL: http://localhost:5984
• Admin: admin / password
• Web UI: http://localhost:5984/_utils

GreenMail Server

• Host: localhost
• IMAP Port: 3143 (plain)
• IMAPS Port: 3993 (SSL)
• SMTP Port: 3025
• Server: GreenMail (Java-based test server)

Database Structure

mail2couch will create separate databases for each mail source:

• wildcard_all_folders_test - Wildcard All Folders Test (archive mode)
• work_pattern_test - Work Pattern Test (sync mode)
• specific_folders_only - Specific Folders Only (archive mode)
• subfolder_pattern_test - Subfolder Pattern Test (archive mode)

Each database contains documents with:

• mailbox field indicating the origin folder
• Native CouchDB attachments for email attachments
• Full message headers and body content

Testing Sync vs Archive Modes

Sync Mode (syncuser)

• Database exactly matches mail account
• If messages are deleted from IMAP, they're removed from CouchDB
• 1-to-1 relationship

Archive Mode (archiveuser, testuser1)

• Database preserves all messages ever seen
• Messages deleted from IMAP remain in CouchDB
• Archive/backup behavior

Wildcard Pattern Examples

The test environment demonstrates these wildcard patterns:

All Folders Pattern (*)

{
  "folderFilter": {
    "include": ["*"],
    "exclude": ["Drafts", "Trash"]
  }
}

Processes all folders except Drafts and Trash.

Work Pattern (Work*)

{
  "folderFilter": {
    "include": ["Work*", "Important*", "INBOX"],
    "exclude": ["*Temp*"]
  }
}

Includes Work/Projects, Work/Archive, Important/Urgent, Important/Meetings, and INBOX. Excludes Work/Temp.

Specific Folders

{
  "folderFilter": {
    "include": ["INBOX", "Sent", "Personal"],
    "exclude": []
  }
}

Only processes the exact named folders.

Subfolder Pattern (Work/*)

{
  "folderFilter": {
    "include": ["Work/*", "Archive/*"],
    "exclude": ["*/Drafts"]
  }
}

Includes all subfolders under Work and Archive, but excludes any Drafts subfolder.

File Structure

test/
├── podman-compose.yml          # Container orchestration
├── config-test.json            # Main test configuration with wildcard examples
├── config-wildcard-examples.json # Advanced wildcard patterns
├── test-wildcard-patterns.sh   # Wildcard pattern testing script
├── run-tests.sh               # Full integration test
├── start-test-env.sh          # Start environment
├── stop-test-env.sh           # Stop environment
├── populate-greenmail.py      # Create test messages with folders
├── populate-test-messages.sh  # Wrapper script
├── dovecot/                   # Dovecot configuration (legacy)
└── README.md                 # This file

Prerequisites

• Podman and podman-compose
• OpenSSL (for certificate generation)
• curl and nc (for connectivity checks)
• Go (for building mail2couch)

Troubleshooting

Containers won't start

# Check podman status
podman ps -a

# View logs
podman logs mail2couch_test_couchdb
podman logs mail2couch_test_imap

CouchDB connection issues

• Verify CouchDB is running: curl http://localhost:5984
• Check admin credentials: admin/password

IMAP connection issues

• Test IMAP connection: nc -z localhost 143
• Check Dovecot logs: podman logs mail2couch_test_imap

Permission issues

• Ensure scripts are executable: chmod +x *.sh
• Check file permissions in dovecot directory

Advanced Usage

Add custom test messages

Edit populate-test-messages.sh to create additional test scenarios.

Modify IMAP configuration

Edit dovecot/dovecot.conf and restart containers.

Test with SSL

Update config-test.json to use port 993 and enable SSL.

Custom test scenarios

Create additional configuration files for specific test cases.