REST / GraphQL API

Functional API testing for REST and GraphQL endpoints — request construction, response validation, status codes, and payload assertions.

What this module tests

The API module generates tests that send real HTTP requests to your API endpoints and validate responses. Tests cover:

• HTTP status code assertions (200, 201, 400, 401, 404, etc.)
• Response body field presence and type validation
• Business logic assertions (e.g. returned id matches input, counts are correct)
• Authentication and authorisation flows (token issuance, protected endpoint access)
• Error response structure and message format
• GraphQL query/mutation response shapes and error handling

KB scenario format for APIs

API scenarios work with the standard KB fields. The following optional fields improve generation quality:

# API scenario example
domain: products-api
scenarios:
  - id: PROD-001
    title: "GET /products returns paginated list"
    module: api
    endpoint: /api/v1/products
    method: GET
    steps:
      - Send GET request to /api/v1/products with query params page=1&limit=20
      - Include Authorization header with valid bearer token
    expected: >
      HTTP 200 response.
      Body is JSON object with keys: data (array), total (number), page (number).
      data array contains up to 20 items, each with id, name, price, and category fields.

  - id: PROD-002
    title: "POST /products creates a new product"
    module: api
    endpoint: /api/v1/products
    method: POST
    steps:
      - Send POST to /api/v1/products with valid JSON body (name, price, category)
      - Include Authorization header with admin bearer token
    expected: >
      HTTP 201 response.
      Body includes id (UUID), name matching request, created_at timestamp.

  - id: PROD-003
    title: "POST /products with missing name returns 422"
    module: api
    endpoint: /api/v1/products
    method: POST
    steps:
      - Send POST to /api/v1/products with body missing the name field
    expected: >
      HTTP 422 response.
      Body includes errors array with field "name" and message "is required".

GraphQL support

GraphQL APIs are supported via the same module. ScriptGen generates tests using the standard GraphQL HTTP convention (POST to the GraphQL endpoint with query and variables in the request body). Introspection is used automatically if the endpoint supports it, enabling more precise type-aware assertions.

# GraphQL scenario example
domain: graphql-api
scenarios:
  - id: GQL-001
    title: "Query user by ID returns correct fields"
    module: api
    endpoint: /graphql
    steps:
      - Send GraphQL query { user(id: "test-user-id") { id name email createdAt } }
      - Include Authorization header with valid bearer token
    expected: >
      HTTP 200, no errors array in response.
      data.user.id matches "test-user-id".
      data.user.email is a valid email format.

Authentication configuration

API tests that require authentication use credentials configured in Project Settings → Environments → Credentials. Supported credential types:

• Bearer token — static token or token obtained via a login endpoint call at test setup
• API key — injected as a header (X-API-Key or custom)
• Basic auth — username/password Base64-encoded in the Authorization header
• OAuth 2.0 client credentials — token fetched at test session setup

Generated script structure

Generated API scripts use HTTPX as the HTTP client within pytest. Each test function:

1. Constructs the request using fixtures for the base URL and auth token
2. Sends the request and captures the response
3. Asserts on status code
4. Asserts on response body fields

# Example generated test structure (illustrative)
def test_prod_001_get_products_paginated(api_client, auth_token):
    response = api_client.get(
        "/api/v1/products",
        params={"page": 1, "limit": 20},
        headers={"Authorization": f"Bearer {auth_token}"}
    )
    assert response.status_code == 200
    body = response.json()
    assert "data" in body
    assert isinstance(body["data"], list)
    assert len(body["data"]) <= 20
    assert "total" in body
    assert "page" in body