🌐 API Testing with Testlum

Testlum provides powerful and flexible capabilities for testing various types of APIs, including:

📡 HTTP APIs (RESTful services)

🔓Authorization (for API only)

🔌 WebSocket APIs (real-time communication)

🔷 GraphQL APIs (structured query-based APIs)

http

🌐 `http`

The http command allows you to perform API requests such as GET, POST, PUT, DELETE, PATCH, OPTIONS, TRACE, HEAD within your test scenarios.

⚙️ General Parameters

Parameter	Type	Required	Default	Description
`comment`	String	✅	-	Description of the HTTP 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 HTTP Methods

Each HTTP method block (like <get>, <post>, etc.) may contain the following sections:

📍 Endpoint

<get endpoint="/activity">
endpoint - URL path to the specific resource.

📩 Response Validation

Parameter	Description
`code`	Expected HTTP response code (e.g., 200, 404)
`file`	File with the expected JSON/XML response
`mode`	A mode for response comparison (`lenient` `strict`)

<response code="200" file="expected_1.json"/>

📑 Headers

Parameter	Description
`name`	Name of the header (e.g., `Authorization`)
`data`	Header value (e.g., `Bearer token`)

<header name="Authorization" data="Bearer YOUR_TOKEN"/>

📝 Body (for POST, PUT, PATCH)

You can pass a request body from a file (request_N.json)

Parameter	Description
`file`	json file that contains body of your request. This file must be named "request_N.json", where N is number of your test step

<post endpoint="/jwt/users">
    <body>
        <from file="request_1.json"/>
    </body>
</post>

Or write it raw inside the scenario.

<body>
    <raw>
        {
            "username": "admin",
            "password": "password123"
        }
    </raw>
</body>

Or use param section.

Parameter	Description
`name`	Parameter name (e.g., `userId`)
`data`	Parameter value (e.g., `12345`)

The <param> tag inside <body> allows you to define key-value pairs that will be used to construct the request body.

If the Content-Type is application/json, all parameters are automatically converted into a JSON object.

If the Content-Type is different (e.g., application/x-www-form-urlencoded), parameters are encoded as a URL-encoded form (key=value&key2=value2).

You can define multiple <param> elements inside <body>, and they will be combined appropriately based on the Content-Type.

🧩 Example (application/json)
<body>
    <param name="username" data="admin"/>
    <param name="password" data="secret"/>
</body>
Resulting body:
{
  "username": "admin",
  "password": "secret"
}
🧩 Example (application/x-www-form-urlencoded)
<body>
    <param name="username" data="admin"/>
    <param name="password" data="secret"/>
</body>
Resulting body:
username=admin&password=secret
✅ Tip:
Use <param> when you need to dynamically build a request body without manually creating a full JSON file, especially useful for form submissions or simple API requests.

Also Tesltum supports multipart requests (for file uploads).

Parameter	Description
`file`	Path to the file
`name`	Form field key name
`fileName`	File name to upload as
`contentType`	MIME type (e.g., `image/png`)

<post endpoint="/post">
    <body>
        <multipart>
            <file name="testName" fileName="test.pdf" contentType="text/pdf"/>
            <param name="testParam12!" data="Hello World!12@" contentType="text/plain"/>
            <param name="testParam13!" data="Hello World!13@"/>
        </multipart>
    </body>
</post>

🧠 Execution Sequence Reminder

Inside the methods there should be a sequence:

response

header

body/param

multipart

✅ This ensures maximum clarity and reliability in request validation!

🧪 Real Example

<http alias="BORED" comment="Get activity by type">
    <post endpoint="/api/v1/users">
        <response code="200" file="expected_1.json">
            <header name="Response-Header" data="value"/>
        </response>
        <header name="Content-Type" data="application/json"/>
        <body>
            <from file="request_1.json"/>
        </body>
    </post>
</http>

YouTube Usage Guide

Merge test (WEB/API)

Testlum provides you with ability to conduct different types of testing within one scenario. So that you can easily increase efficiency and coverage level of your tests.

Here is an example of merge test scenario with WEB and API test steps within one scenario.

auth

🔐 Authorization with `<auth>` Command

Testlum provides a unique <auth> command that enables instant authorization by a system user directly within a test script.

Using <auth>, you can perform multiple requests under an authorized session, greatly simplifying API testing — especially for secured endpoints.

⚙️ Setup Overview

In your integration.xml, configure an <api> integration and select the authorization strategy.
In the test script, use the <auth> tag to perform authorization based on that configured strategy.

The <auth> tag is especially useful for REST API testing, allowing seamless switching between users and working with complex permission systems.

📜 Basic Usage Example

<auth comment="Test case for auth command"
      apiAlias="ALIAS"
      credentials="jwt_user.json"
      loginEndpoint="/api/v1/customer/login">
  
    <http comment="Get all stores in system" alias="SHOPIZER">
        <get endpoint="/api/v1/auth/customers/profile">
            <response code="200" file="expected_2.json"/>
        </get>
    </http>
  
</auth>
apiAlias: alias of the API you configured in integration.xml.

credentials: filename containing user credentials (must be placed inside the data folder).

loginEndpoint: endpoint for performing the login action.

🛑 Closing the <auth> block automatically logs out the authorized user at the end.

🧩 Credentials File Example (`jwt_user.json`)

{
  "username": "username",
  "password": "password"
}

✅ Key Advantages

No need to manually pass authentication tokens inside every request.

Easily switch between multiple users in a single script.

Ideal for testing complex permission systems and private API workflows.

Tip:
Use <auth> whenever you need to batch test many authenticated API endpoints without handling tokens manually!

websocket

🔗 WebSocket Testing with Testlum

Testlum supports WebSocket testing both for Standard WebSocket and WebSocket with STOMP protocol.
You can easily send, receive, and subscribe to messages in real-time communication scenarios.

🌐 Standard WebSocket API

⚙️ Main `<websocket>` Tag

Parameter	Type	Required	Default	Description
`comment`	String	✅	-	Describes the purpose of the connection
`alias`	String	✅	-	Matches the alias configured in `integration.xml`
`disconnect`	Boolean	❌	`true`	Whether to disconnect after closing `<websocket>`
`condition`	Boolean	❌	-	Conditionally execute this connection block
`threshold`	Integer (ms)	❌	-	Max allowed execution time before timeout

📩 `<receive>` - Receiving Messages

Parameter	Type	Required	Default	Description
`comment`	String	✅	-	Comment for this receive step
`limit`	Integer	❌	-	Maximum number of messages to validate
`timeoutMillis`	Integer	❌	-	Max time to wait for receiving a message
`topic`	String	❌	-	Topic name for receiving a message

Messages can be provided inline via <message>...</message> or from a file using <file>expected_X.json</file>.

Example:

<receive comment="Receive a message" limit="1" timeoutMillis="3000">
    <message>[{"some": "payload"}]</message>
</receive>
<receive comment="Receive a message" limit="1" timeoutMillis="3000">
    <file>expected_2.json</file>
</receive>

📤 `<send>` - Sending Messages

Parameter	Type	Required	Default	Description
`comment`	String	✅	-	Comment for this send step
`endpoint`	String	❌	-	WS endpoint where to send message

Message can be provided inline via <message>...</message> or from a file.

Example:

<send comment="Send a subscription request">
    <message>
        {
            "event": "subscribe",
            "subscription": { "name": "value" }
        }
    </message>
</send>
<send comment="Check ability to send json message"
                 endpoint="/app/test">
    <file>body_9.json</file>
</send>

🛠️ Full Example for Standard WebSocket

<websocket comment="Standard WebSocket communication" alias="myAlias" disconnect="true">
    <receive comment="Wait for empty message" maxRecords="0">
        <message>[]</message>
    </receive>

    <send comment="Subscribe to event">
        <message>
            {
                "event": "subscribe",
                "subscription": { "name": "value" }
            }
        </message>
    </send>
</websocket>

🚀 WebSocket Testing with STOMP Protocol

If your WebSocket server uses STOMP, you must wrap your operations inside a <stomp> block.

⚙️ Main `<stomp>` Block Inside `<websocket>`

Supports the same general parameters and commands, but specialized for STOMP messaging.

📌 `<subscribe>` - Subscribing to Topics

Parameter	Description
`comment`	Describes the subscription
`topic`	Topic you want to subscribe to (e.g., `/topic/server`)

Example:

<subscribe comment="Subscribe to server updates" topic="/topic/server"/>

📩 `<receive>` - Receiving STOMP Messages

Parameter	Description
`comment`	Comment for this receive step
`topic`	Topic you are listening to
`maxRecords`	Number of messages to validate
`timeoutMillis`	Max wait time to receive messages

Use either inline <message> or <file> for expected payload.

Example:

<receive comment="Receive server pings" topic="/topic/ping" maxRecords="1" timeoutMillis="100">
    <message>[{"value": "ping message"}]</message>
</receive>
<receive comment="Receive server pings" topic="/topic/ping" maxRecords="1" timeoutMillis="100">
    <file>expected_2.json</file>
</receive>

📤 `<send>` - Sending STOMP Messages

Parameter	Description
`comment`	Comment for this send step
`endpoint`	Endpoint where you want to send the message (e.g., `/app/ping`)

Example:

<send comment="Send ping request" endpoint="/app/ping">
    <message>ping message</message>
</send>
<send comment="Send ping request" endpoint="/app/ping">
    <file>body_2.json</file>
</send>

🧪 Full Example for STOMP WebSocket

<websocket comment="Connect to stomp websocket api" alias="TESTER" disconnect="false">
    <stomp>
        <subscribe comment="Subscribe to server topic" topic="/topic/server"/>

        <receive comment="Receive server periodic updates" topic="/topic/server" maxRecords="3">
            <file>expected_3.json</file>
        </receive>

        <send comment="Send ping message" endpoint="/app/ping">
            <message>ping message</message>
        </send>
    </stomp>
</websocket>

🚀 Tip:

Always use timeoutMillis smartly to avoid long waits!

Use disconnect="false" if you need persistent open connections during heavy load or multi-step tests.

With STOMP, subscription must happen before sending or receiving!

GraphQL

🔮 GraphQL Testing with Testlum

GraphQL is a powerful query language that allows APIs to serve exactly the data the client requests — no more, no less.
Testlum makes testing GraphQL APIs intuitive and flexible!

⚙️ Main `<graphql>` Command

Parameter	Type	Required	Default	Description
`comment`	String	✅	-	Description of the GraphQL test
`alias`	String	✅	-	Unique alias defined in your `integration.xml`
`condition`	Boolean	❌	-	Condition to execute the command
`threshold`	Integer (ms)	❌	-	Max allowed time before failing due to timeout

🛠️ Inside `<post>` and `<get>` Methods

📍 Endpoint

Endpoint defines the URL where your GraphQL server is accessible.

<post endpoint="/graphql">

📩 Response Validation

Parameter	Description
`code`	Expected HTTP response code (default is 200)
`file`	File containing the expected response body
`mode`	A mode for response comparison (`lenient` `strict`)
`header`	Expected headers (optional, name + data)

Example:

<response code="200" file="expected_1.json">
    <header name="Content-Type" data="application/json"/>
</response>

📝 Body (for POST)

You can provide the body either from a file or as raw text:

Parameter	Description
`from`	Load body from a file like `request_1.json`
`raw`	Write the query manually inside the scenario file

Example using file:

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

Example using raw:

<body>
    <raw>
        {
          "query": "{ getAllBooks { id author title number } }"
        }
    </raw>
</body>

📑 Parameters (for GET)

In the <get> method you use param to pass the GraphQL query string.

Parameter	Description
`name`	Usually `query`
`data`	The GraphQL query itself

Example:

<param name="query" data="{ getAllBooks { id author title number } }"/>

🧠 Sequence Reminder

Inside <post> or <get> the elements should be ordered as:

<response>

<header>

<body> (for POST) / <param> (for GET)

✅ This ensures logical and reliable validation flow.

🧪 Real Examples

➡️ Testing with POST method

<graphql comment="Check list of books via POST" alias="ALIAS">
    <post endpoint="/graphql">
        <response code="200" file="expected_1.json"/>
        <header name="Content-Type" data="application/json"/>
        <body>
            <from file="request_1.json"/>
        </body>
    </post>
</graphql>

➡️ Testing with GET method

<graphql comment="Check list of books via GET" alias="ALIAS">
    <get endpoint="/graphql">
        <response code="200" file="expected_2.json"/>
        <param name="query" data="{ getAllBooks { id author title number } }"/>
    </get>
</graphql>

🚀 Best Practices

Use GET for simple queries and POST for complex/mutated data.

Always validate the status code and response file to ensure full verification.

When using raw, be careful with escaping special characters.

Prefer file-based body and response when working with big queries.

API Commands - TestlumFramework/Testlum GitHub Wiki

🌐 API Testing with Testlum

🌐 http

⚙️ General Parameters

🛠️ Inside HTTP Methods

📍 Endpoint

📩 Response Validation

📑 Headers

📝 Body (for POST, PUT, PATCH)

🧩 Example (application/x-www-form-urlencoded)

🧠 Execution Sequence Reminder

🧪 Real Example

YouTube Usage Guide

Merge test (WEB/API)

🔐 Authorization with <auth> Command

⚙️ Setup Overview

📜 Basic Usage Example

🧩 Credentials File Example (jwt_user.json)

✅ Key Advantages

🔗 WebSocket Testing with Testlum

🌐 Standard WebSocket API

⚙️ Main <websocket> Tag

📩 <receive> - Receiving Messages

📤 <send> - Sending Messages

🛠️ Full Example for Standard WebSocket

🚀 WebSocket Testing with STOMP Protocol

⚙️ Main <stomp> Block Inside <websocket>

📌 <subscribe> - Subscribing to Topics

📩 <receive> - Receiving STOMP Messages

📤 <send> - Sending STOMP Messages

🧪 Full Example for STOMP WebSocket

🔮 GraphQL Testing with Testlum

⚙️ Main <graphql> Command

🛠️ Inside <post> and <get> Methods

📍 Endpoint

📩 Response Validation

📝 Body (for POST)

📑 Parameters (for GET)

🧠 Sequence Reminder

🧪 Real Examples

➡️ Testing with POST method

➡️ Testing with GET method

🚀 Best Practices

⚠️ **GitHub.com Fallback** ⚠️

🌐 `http`

🔐 Authorization with `<auth>` Command

🧩 Credentials File Example (`jwt_user.json`)

⚙️ Main `<websocket>` Tag

📩 `<receive>` - Receiving Messages

📤 `<send>` - Sending Messages

⚙️ Main `<stomp>` Block Inside `<websocket>`

📌 `<subscribe>` - Subscribing to Topics

📩 `<receive>` - Receiving STOMP Messages

📤 `<send>` - Sending STOMP Messages

⚙️ Main `<graphql>` Command

🛠️ Inside `<post>` and `<get>` Methods

⚠️ GitHub.com Fallback ⚠️