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
```bash
./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
```bash
./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
```bash
# 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 (`*`)
```json
{
  "folderFilter": {
    "include": ["*"],
    "exclude": ["Drafts", "Trash"]
  }
}
```
Processes all folders except Drafts and Trash.

### Work Pattern (`Work*`)
```json
{
  "folderFilter": {
    "include": ["Work*", "Important*", "INBOX"],
    "exclude": ["*Temp*"]
  }
}
```
Includes Work/Projects, Work/Archive, Important/Urgent, Important/Meetings, and INBOX. Excludes Work/Temp.

### Specific Folders
```json
{
  "folderFilter": {
    "include": ["INBOX", "Sent", "Personal"],
    "exclude": []
  }
}
```
Only processes the exact named folders.

### Subfolder Pattern (`Work/*`)
```json
{
  "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
```bash
# 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.