Basic Concepts

Core rules for writing and running .gctf tests.

What a test contains

--- ADDRESS ---
localhost:4770

--- ENDPOINT ---
package.Service/Method

--- REQUEST ---
{
  "id": 1
}

--- ASSERTS ---
.id == 1

Main sections

• META - file-level metadata (name, summary, tags, owner, links); if present, must be the first section
• ADDRESS - target host and port
• ENDPOINT - gRPC method in package.Service/Method format
• REQUEST - JSON payload (multiple allowed)
• RESPONSE - expected JSON payload (multiple allowed)
• ERROR - expected error payload
• ASSERTS - validation expressions
• EXTRACT - extract values for reuse and advanced checks
• REQUEST_HEADERS - request metadata
• TLS - TLS/mTLS parameters
• PROTO - descriptor/reflection configuration
• OPTIONS - parsed, validated, and used for per-test runtime overrides (timeout, retry, retry-delay, no-retry, compression)

Use Section Reference for exact syntax and section rules.

Required rules

• META is optional, but only one is allowed and it must be first
• ENDPOINT is required
• At least one validation block is required: RESPONSE, ERROR, or ASSERTS
• RESPONSE and ERROR cannot be used in the same test file
• ADDRESS can be omitted if GRPCTESTIFY_ADDRESS is set

META example

--- META ---
name: Say hello returns greeting
summary: Smoke check for unary hello endpoint
tags: [smoke, hello]
owner: qa-platform
links:
  - https://github.com/gripmock/grpctestify-rust

RPC patterns

• Unary: one REQUEST + one RESPONSE
• Client streaming: multiple REQUEST + one RESPONSE
• Server streaming: one REQUEST + multiple RESPONSE or ASSERTS
• Bidirectional streaming: alternating REQUEST and checks

Assertion examples

--- ASSERTS ---
.status == "ok"
@len(.items) > 0
@header("x-request-id") != null
@uuid(.user.id)

Inline response options

Use inline options in the section header when matching needs tuning:

--- RESPONSE with_asserts partial tolerance=0.1 unordered_arrays ---
{
  "price": 9.99,
  "tags": ["a", "b"]
}

• with_asserts - allow additional ASSERTS checks after payload matching
• partial - allow expected payload to be a subset of actual payload
• tolerance - numeric tolerance for floating-point comparisons
• unordered_arrays - ignore array element ordering during comparison

Runtime configuration

Use CLI flags for runtime behavior:

grpctestify tests/ --parallel 4 --timeout 30
grpctestify tests/ --log-format json --log-output results.json

Useful environment variables:

export GRPCTESTIFY_ADDRESS="localhost:4770"
export GRPCTESTIFY_COMPRESSION="gzip"
export GRPCTESTIFY_TLS_CA_FILE="./certs/ca.pem"