Requests

Define HTTP requests to test your APIs.

Overview

Requests are the foundation of your tests. Each request defines an HTTP call with optional headers, body, and response validation.

Basic Request

requests:
  get-users:
    method: GET
    url: https://api.example.com/users
    expect:
      status: 200

Request Structure

Required Fields

method

HTTP method for the request.

Type: string Values: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

requests:
  get-data:
    method: GET
    url: /api/data

  create-user:
    method: POST
    url: /api/users

  update-user:
    method: PUT
    url: /api/users/123

  partial-update:
    method: PATCH
    url: /api/users/123

  delete-user:
    method: DELETE
    url: /api/users/123

url

Full URL or path. Supports template variables.

Type: string

requests:
  # Full URL
  get-users:
    method: GET
    url: https://api.example.com/users

  # With template variables
  get-user:
    method: GET
    url: "{{.vars.baseUrl}}/users/{{.vars.userId}}"

  # Path only (requires baseUrl in HTTP client)
  list-posts:
    method: GET
    url: /api/v1/posts

Optional Fields

description

Human-readable description of what this request does.

Type: string

requests:
  get-users:
    description: Fetch all active users from the database
    method: GET
    url: /api/users

headers

HTTP headers to include in the request.

Type: object

requests:
  authenticated-request:
    method: GET
    url: /api/protected
    headers:
      Authorization: "Bearer {{.vars.token}}"
      Content-Type: application/json
      X-Request-ID: "{{uuidv4}}"
      X-Client-Version: "1.0.0"

body

Request body. Can be a string or YAML object.

Type: string or object

String body:

requests:
  create-user-json:
    method: POST
    url: /api/users
    headers:
      Content-Type: application/json
    body: |
      {
        "name": "John Doe",
        "email": "john@example.com",
        "age": 30
      }

  create-user-xml:
    method: POST
    url: /api/users
    headers:
      Content-Type: application/xml
    body: |
      <user>
        <name>John Doe</name>
        <email>john@example.com</email>
      </user>

Object body (converted to JSON):

requests:
  create-user:
    method: POST
    url: /api/users
    body:
      name: John Doe
      email: john@example.com
      age: 30
      active: true
      tags: [admin, vip]

With templates:

requests:
  dynamic-body:
    method: POST
    url: /api/data
    body:
      timestamp: "{{now | date \"2006-01-02T15:04:05Z\"}}"
      requestId: "{{uuidv4}}"
      userId: "{{.vars.userId}}"

Multipart File Uploads

Use file prefix for file uploads:

requests:
  upload-avatar:
    method: POST
    url: /api/users/avatar
    body:
      avatar: file ./images/avatar.png
      name: John Doe

  upload-multiple:
    method: POST
    url: /api/documents
    body:
      title: My Documents
      files:
        - file ./doc1.pdf
        - file ./doc2.pdf
        - file ./doc3.pdf

labels

Labels for categorizing and filtering requests.

Type: string or array of strings

requests:
  login:
    method: POST
    url: /auth/login
    labels: [auth, smoke, critical]

  get-users:
    method: GET
    url: /api/users
    labels: api

  admin-action:
    method: POST
    url: /admin/reset
    labels: [admin, dangerous]

Use labels with scenarios to run specific test groups.

client

HTTP client configuration to use for this request.

Type: string Default: default

requests:
  slow-request:
    method: GET
    url: /api/slow-endpoint
    client: patient-client  # Uses patient-client config

  fast-request:
    method: GET
    url: /api/fast-endpoint
    client: default

See HTTP Clients for client configuration.

dependsOn

Request dependencies that must run before this request.

Type: string or array of strings

requests:
  login:
    method: POST
    url: /auth/login
    body:
      username: admin
      password: secret

  get-profile:
    method: GET
    url: /api/profile
    dependsOn: login  # login runs first

  update-settings:
    method: PUT
    url: /api/settings
    dependsOn: [login, get-profile]  # Both run first

expect

Response validation using Compact DSL.

Type: object

requests:
  get-users:
    method: GET
    url: /api/users
    expect:
      status: 200
      headers:
        Content-Type: contains application/json
      body:
        $: type array
        $.length: "> 0"
        $[0].id: exists
        $[0].email: !empty
      responseTime: "< 500ms"

See Assertions for complete Compact DSL reference.

Comprehensive Example

This request demonstrates using almost every available feature:

requests:
  complex-request:
    description: Comprehensive example with all features
    method: POST
    url: "{{.vars.baseUrl}}/api/v1/resources"
    labels: [api, integration, critical]
    client: production-client
    dependsOn: setup-auth
    headers:
      Authorization: "Bearer {{.session.auth.body.token}}"
      Content-Type: application/json
      X-Request-ID: "{{uuidv4}}"
      X-Timestamp: "{{now | unixEpoch}}"
    body:
      name: "{{.vars.resourceName}}"
      type: premium
      metadata:
        createdBy: "{{.session.auth.body.userId}}"
        tags: [production, verified]
      settings:
        enabled: true
        maxLimit: 1000
    expect:
      status: [201, 200]
      headers:
        Location: exists
        X-Request-ID: exists
      body:
        $.id: exists
        $.id: type number
        $.name: "{{.vars.resourceName}}"
        $.type: premium
        $.status: in [active, pending]
        $.createdAt: exists
        $.metadata: type object
        $.metadata.createdBy: "{{.session.auth.body.userId}}"
      responseTime: "< 1s"

Working with Different Content Types

JSON

requests:
  json-request:
    method: POST
    url: /api/data
    headers:
      Content-Type: application/json
    body: |
      {"key": "value"}

XML

requests:
  xml-request:
    method: POST
    url: /api/data
    headers:
      Content-Type: application/xml
    body: |
      <?xml version="1.0"?>
      <data>
        <key>value</key>
      </data>

Form URL Encoded

requests:
  form-request:
    method: POST
    url: /api/login
    headers:
      Content-Type: application/x-www-form-urlencoded
    body: "username=admin&password=secret"

Plain Text

requests:
  text-request:
    method: POST
    url: /api/text
    headers:
      Content-Type: text/plain
    body: |
      This is plain text content
      Multiple lines are preserved

Common Patterns

API Authentication

requests:
  login:
    method: POST
    url: /auth/login
    body:
      username: "{{.vars.username}}"
      password: "{{.vars.password}}"
    expect:
      status: 200
      body:
        $.token: exists

CRUD Operations

requests:
  # Create
  create:
    method: POST
    url: /api/resources
    body:
      name: New Resource

  # Read
  read:
    method: GET
    url: /api/resources/123

  # Update
  update:
    method: PUT
    url: /api/resources/123
    body:
      name: Updated Resource

  # Delete
  delete:
    method: DELETE
    url: /api/resources/123

Pagination

requests:
  page-1:
    method: GET
    url: /api/items?page=1&limit=20

  page-2:
    method: GET
    url: /api/items?page=2&limit=20