Share test reports via email in Katalon Studio
An active Katalon Studio license.
After a test suite or test suite collection execution, you might want to automatically send summary reports to your own email or other stakeholders to notify them about the test result. This document shows you how to set up your mail server and customize email reports to automatically send out a summary report email whenever a test execution finishes.
AI Failure Analysis is included in email test reports. It provides instant, plain-language explanations for test failures. Learn how to enable and use this time-saving feature here: Katalon AI Assistant Failure Analysis.
Email settings
In Katalon Studio, go to Project > Settings > Email to configure email notifications for test executions. On this page, you can:
- Configure the mail server, sender, recipients, and email templates.
- Select the report files to include as email attachments, such as HTML, CSV, PDF, log, and PNG files.
- Enable AI-powered failed reason analysis for the email report when Katalon AI Assistant is enabled.
- Enable email reports for Test Suite executions and choose whether to send them for all executions or only executions that contain failed test cases.
- Enable email reports for Test Suite Collection executions and, if needed, skip email reports for the individual Test Suites in the collection.
Mail server settings
Mail Server Settings defines the mail server Katalon Studio uses for sending emails. To set up your mail server, fill in your mail server host, port, credentials, and choose a protocol option.
- Host: The domain name of the mail server.
- Port: The port to be used for that server.
Below is a list of some common outgoing mail (SMTP) server configurations:
| Email server | Host | Port | Reference |
|---|---|---|---|
| Gmail | smtp.gmail.com | 465 or 587 | Check Gmail through other email platforms |
| Outlook | smtp.office365.com | 587 or 25 | How to set up a multifunction device or application to send email using Microsoft 365 or Office 365 |
| Yahoo! Mail | smtp.mail.yahoo.com | 465 | POP access settings and instructions for Yahoo Mail |
- Microsoft retired SMTP server's basic authentication for personal accounts - configurations for Microsoft's personal accounts no longer work.
- Microsoft planned to retire basic authentication for Microsoft 365 for Business by April 2026. Until then, make sure to also use an Admin Account to check and enable SMTP Auth for individual accounts.
- Username and Password:
- Username: Your full email account to authenticate with the server (for example,
yourusername@gmail.com). - Password: Your email password to authenticate with the server. This could be a password generated from App Passwords.
- Username: Your full email account to authenticate with the server (for example,
For Gmail users:
- If your email accounts are using two-step authentication, you can use Google App Passwords to set up a Gmail account in Katalon Studio. An App Password is a 16-digit passcode that gives Katalon Studio permission to access your Google Account. In the Select app dropdown of App Passwords, select Other (Custom name) to generate an app password for Katalon Studio. Then, use the generated password in Mail Server Settings. For details, see Sign in with App Passwords.
- If you do not use two-step authentication, you can allow less secure apps to access your account. However, to help keep your account secure, starting May 30, 2022, Google no longer supports the use of third-party apps or devices which ask you to sign in to your Google Account using only your username and password. For details, see Less secure apps & your Google Account.
For Yahoo! Mail, make sure to allow less secure apps to access your account. Follow this guide: Ways to securely access Yahoo Mail.
As some SMTP servers do not require authentication and username in email address format, Katalon Studio does not validate usernames and passwords.
- Protocol: The protocol to communicate with the mail server. There are three options:
- None
- SSL (Secure Sockets Layer)
- TLS (Transport Layer Security)
- Encrypt authentication data: For sensitive data protection, we recommend enabling Encrypt authentication data.
After you fill in your mail server information, you can send a test email to check if the mail server is set up correctly. Input an email in the Recipients field, then click Send Test Email. The Send Test Email button is only enabled once Mail Server Settings and Recipients are filled correctly.
Email template
You can define the sender, recipients (the list of emails to receive reports), email subject, and body template in this section.
Katalon Studio supports adding Test Suite and Test Suite Collection names in your email subject with the placeholders ${suiteName} and ${suiteCollectionName}, respectively.
Report format
Choose whether to include a test execution report as an email attachment. This includes selecting specific log files and configuring the report format (HTML, CSV, or PDF) to be attached.
You can specify custom file types for the report to be sent as email attachments. Select the checkbox for Custom files, then enter specific file extensions (such as .txt, .xlsx).
- For an HTML format, when you enable the Link screenshots instead of embedding them, to reduce report file size option in Project > Settings > Plugins > Report, only screenshots saved in the
Reportsfolder are included in the report. If you want to save screenshots outside theReportsfolder, do not select this option to avoid missing screenshots in your email report.
- Attachment scope: Only custom files located at the same folder level as the Test Suite report are attached; files in sub-folders are not attached.
- Unsupported file types: Some executable or script-based file types are not supported as custom email attachments. For example,
.jsfiles are not supported. - Size limit: When the total attachment size is close to the email provider’s size limit (Gmail direct attachment limit is 25MB), some report content may not be included in the email attachments.
Body template
Customize email template for test suite
To customize the email body template used for a Test Suite, do one of the following:
-
Go to Project > Settings > Email > Template, then select Test Suite from the dropdown.
-
Or click Edit Template for Test Suite Execution from the Email Settings screen.
The Test Suite email report template is displayed and is editable. Use the main navigation bar above the template, or click within the email body to reveal the quick edit menu.
Use the following supported variables to customize the content of the Test Suite email template:
| Variable | Description |
|---|---|
${hostName} | Name of the host machine where the test was executed. |
${os} | Operating system used during test execution. |
${browser} | Browser name and version used (for Web tests). |
${deviceId} | ID of the device used for test execution. |
${deviceName} | Name of the device used for test execution. |
${suiteName} | Name of the test suite executed. |
${executionProfile} | Execution profile used during the test run. |
${startTime} | Timestamp indicating when the test execution started. |
${duration} | Total duration of the test execution. |
${totalPassed} | Number of test cases that passed. |
${totalFailed} | Number of test cases that failed. |
${totalError} | Number of test cases that encountered errors. |
${totalIncomplete} | Number of test cases that did not complete. |
${totalSkipped} | Number of test cases that were skipped. |
${executedBy} | Username or identity that initiated the test execution. |
${projectName} | Name of the Katalon Studio project. |
${failedReason} | Describes the failure reason if the test suite did not pass. |
${status} | Overall status of the test suite (for example, Passed, Failed). |
For projects created in Katalon Studio version 10.1.0 or later, you can include a test case result table in the email body.
To display a test case result table in your email report, manually insert one of the following variables into your Test Suite email template where you want the table to appear. Refer to the table below to choose the appropriate variable for your reporting needs:
| Variable | Description | When to Use |
|---|---|---|
${test_case_result_table} | Displays the test case ID and status for all test cases. Only available for Test Suite email template. | Use for comprehensive reports intended for debugging, QA reviews, or audit documentation. |
${test_case_result_table_minimal} | Displays only the test case ID and status for failed and error test cases. | Use for lightweight reports such as CI/CD notifications, stakeholder summaries, or quick overviews. |
Before saving your changes, click Preview to see how the Test Suite Execution report will appear in the email.
Click Apply or Apply and Close when you have finished your customization.
Customize email template for test suite collection
To customize the email body template used for a Test Suite Collection, do one of the following:
-
Go to Project > Settings > Email > Template, then select Test Suite Collection from the dropdown.
-
Or click Edit Template for Test Suite Collection Execution from the Email Settings screen.
Use the following variables to customize the content of the Test Suite Collection email template:
| Variable | Description |
|---|---|
hostName | Host's name |
os | Operating system |
suiteCollectionName | Name of the Test Suite Collection |
startTime | When the Test Suite Collection started running |
duration | Duration of the test execution |
totalPassed | Total passed test cases across all executed test suites |
totalFailed | Total failed test cases across all executed test suites |
totalError | Total error test cases across all executed test suites |
totalIncomplete | Total incomplete test cases across all executed test suites |
totalSkipped | Total skipped test cases across all executed test suites |
totalTestCases (11.1.2+ required) | Total of all test cases across all suites in the TSC |
totalTestSuitesPassed (11.1.2+ required) | Total passed test suites |
totalTestSuitesFailed (11.1.2+ required) | Total failed test suites |
totalTestSuitesError (11.1.2+ required) | Total error test suites |
totalTestSuitesSkipped (11.1.2+ required) | Total skipped test suites |
totalTestSuitesIncomplete (11.1.2+ required) | Total incomplete test suites |
${tsc_case_result_table} | Displays the test case ID and status for all test suites in the test suite collection. |
${tsc_case_result_table_minimal} | Displays only the test case ID and status for failed or error test cases in the test suite collection. |
${test_suite_result_table} | Displays the test suite ID and status for all test suites in the test suite collection. |
- From 10.4.3 to 11.0.0, the Test Suite Collection email template counts results based on the Test Suite instead of the Test Case.
Before saving your changes, click Preview to see how the Test Suite Collection Execution report will appear in the email.
Click Apply or Apply and Close when you have finished your customization.
Use global variables for emails
Use global variables to customize email fields and override their default values from the command line.
Global variable scope
The execution profile used for the email report determines which global variable values are applied:
| Email report | Applied global variables |
|---|---|
| Test Suite | Variables from the selected execution profile. |
| Test Suite Collection | Variables from the default profile for the collection report; variables from each Test Suite's selected execution profile for the individual Test Suite reports. |
Global variables in email reports must be defined in the project profile. Values updated at runtime, such as in a Listener class, are not applied to the email body.
- Define a global variable in your execution profile. See Create a profile.
- In a supported email field, use
${GlobalVariable.name}to reference it. Supported fields include Sender, Recipients, Cc, Bcc, Subject, and Body Template. - Click Send Test Email to verify the result.
When running a Test Suite or Test Suite Collection in console mode, use -g_<variableName>=<variableValue> to override a default value. For example: -g_subject=<Release 7.7>.