Messaging Commands - TestlumFramework/Testlum GitHub Wiki

πŸ“¬ 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>[email protected]</destination>
    <source>[email protected]</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="[email protected]">
    <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.
⚠️ **GitHub.com Fallback** ⚠️