The Email Library

/* @provengo summon email */

The Email library is designed to assist in testing systems that interact with emails.

This library is still experimental. Methods and events might change a bit as we respond to user feedback.

Code Example

In the following code example, we’ll illustrate the usage of the Email library using the provided functions.

/* @provengo summon email */ (1)

const emailSession = new EmailSession("gmail", { (2)
    username: "userName",
    password: "password", // getEnv("USER_5_PASS"),
    server: "server",
    imap: {
        server: "imap server",
        username: "imap user name",
        password: "imap password"
    },
    smtpServer: {
        server: "smtp server",
        username: "smtp username",
        password: "smtp password"
    }
});

bthread('send and receive emails', function () {
    // Sending an Email
    emailSession.send({ (3)
        to: "destination@gmail.com",
        subject: "Your OTP is enclosed",
        body: "Your code is 0112358 4545"
    });

    // Reading an Email
    emailSession.read({ (4)
        name: "read OTP code",
        timeout: 5000,
        search: { (5)
            subject: "Your OTP is enclosed",
            startDate: "2023-08-19",
            endDate: "2026-08-20"
        }
        callback: function(mail){ (6)
            let emailSubject = mailMessage.subject;
            let recivedDate = mailMessage.date;
            let from = mailMessage.from;
            let messageBody = mailMessage.body;

            pvg.rtv.set("subject", emailSubject);
            pvg.rtv.set("recivedDate", recivedDate);
            pvg.rtv.set("from", from);

            const regex = /(\d)+/g;
            const found = messageBody.match(regex);
            pvg.rtv.set("code0", found[0]);
            pvg.rtv.set("code1", found[1]);
            pvg.sucess();
        }
    });

    rtv.assertEq("@{code0}", "0112358")
    rtv.assertEq("@{code1}", "4545")
});

Importing the Email library.
Defining an Email session with server details.
Sending an Email to: "destination@gmail.com", subject: "Your OTP is enclosed", body: "Your code is 0112358 4545".
Reading email from the mailbox.
Search mail that match those conditions.
Callback function that will handle mail content.

Explanation

Let’s break down the usage of the email library functions demonstrated in the above code example:

Creating Email session

Constructs a new cli session.

username: The email account username. (Optional)
password: The app password associated with the account. (Optional)
server: The IMAP and SMTP server for reading and sending emails. (Optional)
imap
- server: The IMAP server for reading emails.
- username: username for IMAP server.
- password: password for IMAP server.
smtp:
- server: The SMTP server for reading emails.
- username: username for SMTP server.
- password: password for SMTP server.

Sending an Email

The emailSession.send function is utilized to send an email with specific details, allowing you to simulate email interactions. Here’s a breakdown of the parameters used:

recipientEmail: The email address of the recipient.
subject: The subject of the email.
body: The content of the email.

Reading an Email

The emailSession.read function enables you to retrieve emails based on specific criteria. Here’s what each parameter represents:

name: name for the read email action. ^optional
search: contains search conditions
- subject: A regular expression pattern to match email content, including named groups for capturing specific values. ^optional
- startDate: The start date for filtering emails.
- endDate: The end date for filtering emails.
callback: Validation function on the found email (that match the search terms).
callback(email) This function can report back to the program using the pvg service object, exposed as a global variable.
email argument:
- email.subject: email subject.
- email.date: email received date.
- email.from: email sender.
- email.body: email body content.

Using the Email library functions, you can effectively simulate email communication and automate testing processes within your system.

Generating an App Password (Gmail with 2FA Enabled)

When using Gmail with Two-Factor Authentication (2FA) enabled, the conventional account password alone may not be sufficient for some applications to access your email account securely. An app password provides an extra layer of security by allowing you to create a specific password for the application, which in this case, is your testing system.

To generate an app password for your Gmail account, you can follow these steps:

Log in to your Gmail account.
Go to your Google Account settings. You can do this by clicking on your profile picture in the top right corner and selecting "Manage your Google Account."
In the left menu, select "Security."
Scroll down to the "Signing in to Google" section and find the "App passwords" option. Click on it.
If prompted, re-enter your Google account password.
Choose the app and device you want to generate the app password for. In this case, you might choose "Mail" and "Other (Custom Name)."
Click "Generate."
Follow the instructions to use the app password in your application.

This app password, which is a randomly generated code, is what you would use as the senderPassword parameter when calling the sendEmail and readEmail functions. It ensures that your main Google account password remains secure while allowing the testing system to interact with your Gmail account.