Configuration

Catalyst uses a TOML configuration file to define your API tests. This section explains the structure and options available in the configuration file.

Configuration File Location

By default, Catalyst looks for a configuration file at .catalyst/tests.toml in your project directory.

Configuration Structure

The configuration file has two main sections:

1. Global Configuration - Settings that apply to all tests
2. Test Definitions - Individual test cases

Global Configuration

The global configuration is defined in a [config] section at the top of the file:

[config]
base_url = "https://api.example.com"
auth_method = "Bearer"  # Optional
auth_token = "your-token"  # Optional
default_headers = { "Content-Type" = "application/json" }  # Optional

Available Options

Test Definitions

Test definitions are specified using [[tests]] sections:

[[tests]]
name = "Get Users"
method = "GET"
endpoint = "/users"
query_params = { "limit" = "10" }  # Optional
headers = { "X-Custom-Header" = "value" }  # Optional
body = { "key" = "value" }  # Optional
expected_status = 200
expected_body = { "success" = true }  # Optional
expected_headers = [["Content-Type", "application/json"]]  # Optional
store = { "$.token" = "auth_token" }  # Optional
get_cookie = { "session" = "session_cookie" }  # Optional
max_response_time = 500  # Maximum response time in milliseconds (Optional)

# Advanced assertions (Optional)
assertions = [
  # Exact match (same as expected_body)
  { type = "Exact", value = { "success" = true } },

  # Partial match - checks if response contains these fields
  { type = "Contains", value = { "data" = { "users" = [] } } },

  # Regex match on the entire response body
  { type = "Regex", value = "\\{.*\"success\"\\s*:\\s*true.*\\}" },

  # Regex match on a specific JSON path
  { type = "PathRegex", value = ["$.user.email", ".*@example\\.com"] }
]

Available Test Options

Advanced Assertions

Catalyst 0.2 introduces advanced assertions for more flexible response validation. You can use the assertions field to define multiple validation rules for a single test.

Types of Assertions

Exact Match

Validates that the response body exactly matches the expected value. This is equivalent to using expected_body.

assertions = [
  { type = "Exact", value = { "success" = true, "data" = { "id" = 1 } } }
]

Contains Match

Validates that the response body contains all the fields specified in the expected value, but may contain additional fields.

assertions = [
  { type = "Contains", value = { "success" = true } }
]

This will pass if the response contains {"success": true, "data": {...}} or any other JSON that includes the success field with a value of true.

Regex Match

Validates that the string representation of the response body matches the specified regular expression pattern.

assertions = [
  { type = "Regex", value = "\\{.*\"success\"\\s*:\\s*true.*\\}" }
]

Path Regex Match

Validates that a specific value in the response body, identified by a JSON path, matches the specified regular expression pattern.

assertions = [
  { type = "PathRegex", value = ["$.user.email", ".*@example\\.com"] }
]

This will pass if the value at $.user.email in the response matches the pattern .*@example\.com.

Combining Assertions

You can combine multiple assertions for a single test:

assertions = [
  { type = "Contains", value = { "success" = true } },
  { type = "PathRegex", value = ["$.data.id", "\\d+"] }
]

This test will pass only if both assertions are satisfied.

Response Time Validation

Catalyst 0.2 introduces response time validation and tracking. This feature allows you to:

1. Set maximum allowed response times for your API endpoints
2. Access and use the measured response times in subsequent tests

Setting Maximum Response Time

You can use the max_response_time field to specify the maximum allowed response time in milliseconds:

[[tests]]
name = "Fast API Response"
method = "GET"
endpoint = "/api/fast-endpoint"
expected_status = 200
max_response_time = 100  # Must respond within 100ms

If the API response takes longer than the specified time, the test will fail with a message indicating that the response time exceeded the maximum allowed time.

Automatic Response Time Tracking

Important: After each test execution, Catalyst automatically measures and stores the response time. This value is stored in a special variable named response_time_ms that becomes available to all subsequent tests.

This happens automatically for every test, whether or not you've specified a max_response_time value.

Using the Response Time Variable

You can reference the stored response time using the standard variable syntax {{response_time_ms}} in any subsequent test:

# First test - response time will be measured
[[tests]]
name = "Get User Profile"
method = "GET"
endpoint = "/users/profile"
expected_status = 200

# Second test - uses the response time from the first test
[[tests]]
name = "Log Response Time"
method = "POST"
endpoint = "/metrics/log"
body = {
  "endpoint" = "/users/profile",
  "response_time_ms" = "{{response_time_ms}}",
  "timestamp" = "{{current_timestamp}}"
}
expected_status = 200

This feature is particularly useful for:

• Performance logging and monitoring
• Creating tests that validate performance metrics
• Debugging performance issues across different API endpoints

Next Steps

For more detailed information about specific aspects of configuration, see:

• Test File Structure
• Security
• Complete Reference - Comprehensive reference with examples for all features