Skip to content

API Commands

Jump to bottom
Bohdan Shakhov edited this page Jun 2, 2025 · 8 revisions

🌐 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:

  1. response
  2. header
  3. body/param
  4. 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

Watch the video

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.

Watch the video

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>

Watch the video

🚀 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>

Watch the video

🚀 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:

  1. <response>
  2. <header>
  3. <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.
Clone this wiki locally