0
# Testing Support
1

2
Development and testing utilities for creating temporary email accounts, viewing sent messages, and testing email functionality without sending real emails.
3

4
## Capabilities
5

6
### Test Account Creation
7

8
Create temporary test email accounts using the Ethereal Email service for development and testing.
9

10
```javascript { .api }
11
/**
12
 * Creates a test account on Ethereal Email service
13
 * @param {string} [apiUrl] - Optional API endpoint URL (default: https://api.nodemailer.com)
14
 * @param {Function} [callback] - Optional callback function (error, account) => void
15
 * @returns {Promise<TestAccount>} Promise if no callback provided
16
 */
17
function createTestAccount(apiUrl, callback);
18

19
interface TestAccount {
20
    user: string;                   // Test account email address
21
    pass: string;                   // Test account password
22
    smtp: {                         // SMTP configuration
23
        host: string;               // SMTP server hostname
24
        port: number;               // SMTP server port
25
        secure: boolean;            // Whether to use TLS
26
    };
27
    imap: {                         // IMAP configuration
28
        host: string;               // IMAP server hostname
29
        port: number;               // IMAP server port
30
        secure: boolean;            // Whether to use TLS
31
    };
32
    pop3: {                         // POP3 configuration
33
        host: string;               // POP3 server hostname
34
        port: number;               // POP3 server port
35
        secure: boolean;            // Whether to use TLS
36
    };
37
    web: string;                    // Web interface URL
38
}
39
```
40

41
**Usage Examples:**
42

43
Callback style:
44
```javascript
45
const nodemailer = require('nodemailer');
46

47
nodemailer.createTestAccount((error, account) => {
48
    if (error) {
49
        console.error('Failed to create test account:', error);
50
        return;
51
    }
52
    
53
    console.log('Test account created:');
54
    console.log('Email:', account.user);
55
    console.log('Password:', account.pass);
56
    console.log('SMTP Host:', account.smtp.host);
57
    console.log('SMTP Port:', account.smtp.port);
58
    
59
    // Create transporter using test account
60
    const transporter = nodemailer.createTransport({
61
        host: account.smtp.host,
62
        port: account.smtp.port,
63
        secure: account.smtp.secure,
64
        auth: {
65
            user: account.user,
66
            pass: account.pass
67
        }
68
    });
69
});
70
```
71

72
Promise style:
73
```javascript
74
async function setupTestAccount() {
75
    try {
76
        const account = await nodemailer.createTestAccount();
77
        
78
        console.log('Test account created:', account.user);
79
        
80
        const transporter = nodemailer.createTransport({
81
            host: account.smtp.host,
82
            port: account.smtp.port,
83
            secure: account.smtp.secure,
84
            auth: {
85
                user: account.user,
86
                pass: account.pass
87
            }
88
        });
89
        
90
        return transporter;
91
    } catch (error) {
92
        console.error('Failed to create test account:', error);
93
        throw error;
94
    }
95
}
96
```
97

98
Custom API URL:
99
```javascript
100
// Use custom Ethereal API endpoint
101
nodemailer.createTestAccount('https://custom-api.ethereal.email', (err, account) => {
102
    if (err) {
103
        console.error('Error:', err);
104
        return;
105
    }
106
    console.log('Account:', account);
107
});
108
```
109

110
### Test Message URL Generation
111

112
Generate URLs to view sent test messages in the Ethereal Email web interface.
113

114
```javascript { .api }
115
/**
116
 * Generates URL to view sent test message on Ethereal
117
 * @param {Object} info - Send result info object from sendMail
118
 * @returns {string|false} Message URL or false if not available
119
 */
120
function getTestMessageUrl(info);
121
```
122

123
**Usage Examples:**
124

125
```javascript
126
const nodemailer = require('nodemailer');
127

128
async function sendTestEmail() {
129
    // Create test account
130
    const account = await nodemailer.createTestAccount();
131
    
132
    // Create transporter
133
    const transporter = nodemailer.createTransport({
134
        host: account.smtp.host,
135
        port: account.smtp.port,
136
        secure: account.smtp.secure,
137
        auth: {
138
            user: account.user,
139
            pass: account.pass
140
        }
141
    });
142
    
143
    // Send email
144
    const info = await transporter.sendMail({
145
        from: '"Test Sender" <test@example.com>',
146
        to: 'recipient@example.com',
147
        subject: 'Test Email',
148
        text: 'This is a test email',
149
        html: '<p>This is a <b>test email</b></p>'
150
    });
151
    
152
    // Get preview URL
153
    const previewUrl = nodemailer.getTestMessageUrl(info);
154
    
155
    if (previewUrl) {
156
        console.log('Message sent successfully!');
157
        console.log('Message ID:', info.messageId);
158
        console.log('Preview URL:', previewUrl);
159
    } else {
160
        console.log('Message sent but no preview available');
161
    }
162
}
163
```
164

165
### Complete Testing Workflow
166

167
Complete example combining test account creation, email sending, and message preview.
168

169
```javascript { .api }
170
/**
171
 * Complete testing workflow example
172
 */
173
async function testEmailWorkflow() {
174
    try {
175
        // Step 1: Create test account
176
        const account = await nodemailer.createTestAccount();
177
        console.log('Test account:', account.user);
178
        
179
        // Step 2: Create transporter
180
        const transporter = nodemailer.createTransporter({
181
            host: account.smtp.host,
182
            port: account.smtp.port,
183
            secure: account.smtp.secure,
184
            auth: {
185
                user: account.user,
186
                pass: account.pass
187
            }
188
        });
189
        
190
        // Step 3: Send test email
191
        const info = await transporter.sendMail({
192
            from: '"Test Sender" <test@example.com>',
193
            to: 'recipient@example.com',
194
            subject: 'Test Email',
195
            text: 'This is a test email',
196
            html: '<p>This is a <b>test email</b></p>',
197
            attachments: [
198
                {
199
                    filename: 'test.txt',
200
                    content: 'Test attachment content'
201
                }
202
            ]
203
        });
204
        
205
        // Step 4: Get preview URL
206
        const previewUrl = nodemailer.getTestMessageUrl(info);
207
        
208
        return {
209
            messageId: info.messageId,
210
            previewUrl: previewUrl,
211
            account: account
212
        };
213
        
214
    } catch (error) {
215
        console.error('Testing workflow failed:', error);
216
        throw error;
217
    }
218
}
219
```
220

221
**Usage Examples:**
222

223
Testing with different message types:
224
```javascript
225
async function testDifferentMessageTypes() {
226
    const account = await nodemailer.createTestAccount();
227
    
228
    const transporter = nodemailer.createTransport({
229
        host: account.smtp.host,
230
        port: account.smtp.port,
231
        secure: account.smtp.secure,
232
        auth: {
233
            user: account.user,
234
            pass: account.pass
235
        }
236
    });
237
    
238
    // Test plain text email
239
    const textInfo = await transporter.sendMail({
240
        from: account.user,
241
        to: 'test@example.com',
242
        subject: 'Plain Text Test',
243
        text: 'This is a plain text email'
244
    });
245
    console.log('Plain text preview:', nodemailer.getTestMessageUrl(textInfo));
246
    
247
    // Test HTML email
248
    const htmlInfo = await transporter.sendMail({
249
        from: account.user,
250
        to: 'test@example.com',
251
        subject: 'HTML Test',
252
        html: '<h1>HTML Email</h1><p>This is an HTML email</p>'
253
    });
254
    console.log('HTML preview:', nodemailer.getTestMessageUrl(htmlInfo));
255
    
256
    // Test email with attachments
257
    const attachmentInfo = await transporter.sendMail({
258
        from: account.user,
259
        to: 'test@example.com',
260
        subject: 'Attachment Test',
261
        text: 'Email with attachment',
262
        attachments: [
263
            {
264
                filename: 'test-file.txt',
265
                content: 'This is a test attachment'
266
            }
267
        ]
268
    });
269
    console.log('Attachment preview:', nodemailer.getTestMessageUrl(attachmentInfo));
270
}
271
```
272

273
### Account Caching
274

275
Test accounts are automatically cached to improve performance and reduce API calls.
276

277
```javascript { .api }
278
/**
279
 * Account caching behavior
280
 * - Accounts are cached by default for the session
281
 * - Subsequent calls to createTestAccount return the same account
282
 * - Caching can be controlled via ETHEREAL_CACHE environment variable
283
 */
284

285
// Environment variables for configuration
286
process.env.ETHEREAL_CACHE = 'yes';     // Enable caching (default)
287
process.env.ETHEREAL_CACHE = 'no';      // Disable caching
288
process.env.ETHEREAL_API = 'https://api.nodemailer.com';  // API endpoint
289
process.env.ETHEREAL_WEB = 'https://ethereal.email';      // Web interface
290
process.env.ETHEREAL_API_KEY = 'your-api-key';            // API key (optional)
291
```
292

293
**Usage Examples:**
294

295
Cached account behavior:
296
```javascript
297
async function demonstrateCaching() {
298
    // First call creates a new account
299
    const account1 = await nodemailer.createTestAccount();
300
    console.log('First account:', account1.user);
301
    
302
    // Second call returns the same cached account
303
    const account2 = await nodemailer.createTestAccount();
304
    console.log('Second account:', account2.user);
305
    
306
    // account1.user === account2.user (true)
307
    console.log('Same account:', account1.user === account2.user);
308
}
309
```
310

311
Disable caching:
312
```javascript
313
// Disable caching for this session
314
process.env.ETHEREAL_CACHE = 'no';
315

316
async function createMultipleAccounts() {
317
    // Each call creates a new account when caching is disabled
318
    const account1 = await nodemailer.createTestAccount();
319
    const account2 = await nodemailer.createTestAccount();
320
    
321
    console.log('Account 1:', account1.user);
322
    console.log('Account 2:', account2.user);
323
    // account1.user !== account2.user
324
}
325
```
326

327
### Integration with Testing Frameworks
328

329
Examples of integrating Nodemailer testing with popular testing frameworks.
330

331
**Jest Example:**
332
```javascript
333
const nodemailer = require('nodemailer');
334

335
describe('Email Sending Tests', () => {
336
    let testAccount;
337
    let transporter;
338
    
339
    beforeAll(async () => {
340
        testAccount = await nodemailer.createTestAccount();
341
        transporter = nodemailer.createTransporter({
342
            host: testAccount.smtp.host,
343
            port: testAccount.smtp.port,
344
            secure: testAccount.smtp.secure,
345
            auth: {
346
                user: testAccount.user,
347
                pass: testAccount.pass
348
            }
349
        });
350
    });
351
    
352
    test('should send plain text email', async () => {
353
        const info = await transporter.sendMail({
354
            from: testAccount.user,
355
            to: 'test@example.com',
356
            subject: 'Test Email',
357
            text: 'This is a test'
358
        });
359
        
360
        expect(info.messageId).toBeDefined();
361
        expect(nodemailer.getTestMessageUrl(info)).toMatch(/ethereal\.email/);
362
    });
363
    
364
    afterAll(() => {
365
        transporter.close();
366
    });
367
});
368
```
369

370
**Mocha Example:**
371
```javascript
372
const nodemailer = require('nodemailer');
373
const { expect } = require('chai');
374

375
describe('Email Testing', function() {
376
    this.timeout(10000); // Increase timeout for network requests
377
    
378
    let testAccount, transporter;
379
    
380
    before(async () => {
381
        testAccount = await nodemailer.createTestAccount();
382
        transporter = nodemailer.createTransporter({
383
            host: testAccount.smtp.host,
384
            port: testAccount.smtp.port,
385
            secure: testAccount.smtp.secure,
386
            auth: {
387
                user: testAccount.user,
388
                pass: testAccount.pass
389
            }
390
        });
391
    });
392
    
393
    it('should create test account successfully', () => {
394
        expect(testAccount).to.have.property('user');
395
        expect(testAccount).to.have.property('pass');
396
        expect(testAccount).to.have.property('smtp');
397
    });
398
    
399
    it('should send email and return preview URL', async () => {
400
        const info = await transporter.sendMail({
401
            from: '"Sender" <sender@example.com>',
402
            to: 'recipient@example.com',
403
            subject: 'Test Subject',
404
            html: '<p>Test message</p>'
405
        });
406
        
407
        const previewUrl = nodemailer.getTestMessageUrl(info);
408
        expect(previewUrl).to.include('ethereal.email');
409
    });
410
    
411
    after(() => {
412
        if (transporter) {
413
            transporter.close();
414
        }
415
    });
416
});
417
```