Skip to content

Messaging Commands

Jump to bottom
Bohdan Shakhov edited this page May 6, 2025 · 6 revisions

📬 Messaging Services Commands

Testlum supports direct interaction with messaging services such as SendGrid, SES, SMTP, and Twilio.
You can send emails, SMS, or perform messaging actions as part of your automated scenarios.

Each service has a dedicated command with simple, intuitive parameters for configuration and usage.

Supported Messaging Services

📧 Sendgrid

SendGrid

The sendgrid command allows you to interact with the SendGrid API inside your test scenarios.
You can send emails, retrieve statistics, manage templates, and more.

⚙️ General Parameters

Parameter Type Required Default Description
comment String ✅ - Description of the SendGrid request
alias String ✅ - Unique name from your integration.xml setup
condition Boolean ❌ - Condition to execute this step
threshold Integer (ms) ❌ - Max allowed time for execution (failure if exceeded)

🛠️ Inside SendGrid Methods

Each SendGrid method block (<get>, <post>, <put>, <delete>, <patch>) may contain the following sections:

📍 Endpoint

<post endpoint="/templates">
  • endpoint — API endpoint for your SendGrid request.

📩 Response Validation

Parameter Description
code Expected HTTP response code (e.g., 200, 201).
file File with the expected JSON/XML response. 
<response code="201" file="expected_1.json"/>

📑 Headers

Parameter Description
name Header name (e.g., Authorization)
data Header value (e.g., Bearer YOUR_TOKEN) 
<header name="Authorization" data="Bearer YOUR_TOKEN"/>

📝 Body (for POST, PUT, PATCH)

1. From file

You can pass a request body from a JSON file:

<body>
  <from file="request_1.json"/>
</body>

2. Raw inline body

Or, you can write the request body directly:

<body>
  <raw>
    {
      "name": "example_name",
      "generation": "legacy"
    }
  </raw>
</body>

3. Body Parameters

Parameter Description
name Field name (e.g., subject)
data Field value (e.g., Test Email)

Use <param> inside <body> to define key-value pairs dynamically.
They are auto-converted based on your request Content-Type.

🧩 Multipart (for file uploads)

Parameter Description
file Path to the file
name Form field key (e.g., file)
fileName File name to upload as
contentType MIME type of the file 
<body>
  <multipart>
    <file name="uploadFile" fileName="doc.pdf" contentType="application/pdf"/>
  </multipart>
</body>

🔎 Query Parameters (optional)

You can also specify URL query parameters:

Parameter Description
key Query parameter name
value Query parameter value 
<queryParam key="limit" value="10"/>

🧠 Execution Sequence Reminder

Inside SendGrid methods, always follow this sequence:

  1. response
  2. header
  3. body (from, raw, param)
  4. multipart
  5. queryParam

✅ This ensures correct request building and predictable validation!

🧪 Real Example

<sendgrid comment="Testing post method" alias="ALIAS">
    <post endpoint="/templates">
        <response code="201" file="expected_1.json"/>
        <body>
            <raw>
                {
                "name": "example_name",
                "generation": "legacy"
                }
            </raw>
        </body>
    </post>
</sendgrid>

<var comment="Create variable for templates id token" name="template_id">
    <path value="$.id"/>
</var>

<sendgrid comment="Testing get method" alias="ALIAS">
    <get endpoint="/templates/{{template_id}}">
        <response code="200" file="expected_3.json"/>
        <header name="Content-Type" data="application/json"/>
    </get>
</sendgrid>

🚀 Tip:
Use variables ({{template_id}}) to dynamically pass data between requests inside your test scenarios!

✉️ SES Command

SES

🛠️ Overview

Description:
The <ses> command allows you to send emails using Amazon SES (Simple Email Service) in your Testlum scenarios. It supports sending both HTML and plain-text email content to one or more recipients.

⚙️ Command: <ses>

This tag is used to send an email using SES.

⚙️ Parameters

Parameter Type Required Description
comment String ✅ Description of the email action being performed
alias String ✅ Unique alias for the SES connection configured in integration.xml
destination String ✅ Recipient email(s) for the message
source String ✅ Sender's verified email address in SES
message Object ✅ Contains the email body (html, text) and the subject
body Object ✅ The body content, which can include both html and text formats
html String ❌ HTML body content for the email
text String ❌ Plain-text content for the email
subject String ✅ Subject line of the email
condition Boolean ❌ Optional condition to determine when this test step will execute
threshold Integer (ms) ❌ Optional time limit for execution (in milliseconds).

🧪 Example Usage

<ses comment="Sending a message to the email" alias="ALIAS">
    <destination>example@gmail.com</destination>
    <source>examplehello@gmail.com</source>
    <message>
        <body>
            <html>Amazon SES test</html>
            <text>Hello World</text>
        </body>
        <subject>TITLE</subject>
    </message>
</ses>

✅ Tips:

  • Use destination to specify multiple recipients by separating emails with commas.
  • Ensure source is a verified SES email address.
  • Always validate the subject, html, and text content to ensure proper email delivery formatting.

📤 SMTP Command

SMTP

🛠️ Overview

Description:
The <smtp> command sends an email via SMTP protocol in your Testlum scenarios.

⚙️ Command: <smtp>

This tag is responsible for sending SMTP emails with specified parameters.

⚙️ Parameters

Parameter Type Required Description
alias String ✅ Unique alias for the SMTP connection configured in integration.xml
comment String ✅ Description of the email action being performed
recipientEmail String ✅ The recipient email address
subject String ✅ Subject of the email
text String ✅ Content of the email
condition Boolean ❌ Optional condition to determine when this test step will be executed
threshold Integer (ms) ❌ Maximum allowed execution time for this step

🧪 Example Usage

<smtp comment="Testing smtp work" alias="ALIAS" recipientEmail="testlum.test@gmail.com">
    <subject>Test subject</subject>
    <text>Test text</text>
</smtp>

✅ Tips:

  • Ensure that the recipientEmail is valid.
  • If the condition is used, set it for conditional execution of the step.
  • Use threshold to define how long the system should wait for the email sending process.

📱 Twilio Command

Twilio

🛠️ Overview

Description:
The <twilio> command allows you to send SMS messages via Twilio in your Testlum scenarios.

⚙️ Command: <twilio>

This tag is responsible for sending text messages through Twilio’s API.

⚙️ Parameters

Parameter Type Required Description
alias String ✅ Unique alias for the Twilio API configuration in integration.xml
comment String ✅ Description of the SMS sending action
destinationPhoneNumber String ✅ The recipient’s phone number (in E.164 format, e.g., +380631111111)
message String ✅ Content of the SMS message
condition Boolean ❌ Optional condition for executing the step
threshold Integer (ms) ❌ Maximum allowed execution time for the step (in milliseconds)

🧪 Example Usage

<twilio comment="Test how Twilio works" alias="ALIAS" destinationPhoneNumber="+380631111111">
    <message>Testlum!</message>
</twilio>

✅ Tips:

  • Use destinationPhoneNumber to specify the phone number for the message (ensure it's in E.164 format).
  • Set the threshold for defining the maximum time allowed for sending the message.
  • Use condition for conditional execution of the test step.

Clone this wiki locally