catalyst 0.2.9

A lightweight API testing tool
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# Security Configuration

This section explains how to configure authentication and security-related aspects when testing APIs with Catalyst.

## Authentication Methods

Catalyst supports several authentication methods that can be configured in the global configuration section or per test.

### Cookie-based Authentication

The typical workflow for cookie-based authentication is:

1. Perform a login request
2. Extract the session cookie
3. Use the cookie in subsequent requests

Example:

```toml
[[tests]]
name = "Login"
method = "POST"
endpoint = "/auth/login"
body = { "username" = "test", "password" = "password" }
expected_status = 200
get_cookie = { "session_id" = "session_cookie" }

[[tests]]
name = "Access Protected Resource"
method = "GET"
endpoint = "/protected"
headers = { "Cookie" = "session_id={{session_cookie}}" }
expected_status = 200
```

### Bearer Token Authentication

Add an Authorization header via `default_headers` (global) or per-test `headers`:

```toml
[config]
base_url = "https://api.example.com"
default_headers = { 
  "Content-Type" = "application/json",
  "Authorization" = "Bearer {{API_TOKEN}}" 
}
```

You can pass `API_TOKEN` via `--var API_TOKEN=...` or use an environment variable with `${{API_TOKEN}}` in values.

## Handling API Keys

You can include API keys in headers or query parameters:

```toml
[[tests]]
name = "API Key in Header"
method = "GET"
endpoint = "/protected"
headers = { "X-API-Key" = "your-api-key" }
expected_status = 200

[[tests]]
name = "API Key in Query Parameter"
method = "GET"
endpoint = "/protected"
query_params = { "api_key" = "your-api-key" }
expected_status = 200
```

## Chaining Authentication

You can chain authentication by extracting tokens from responses:

```toml
[[tests]]
name = "Create User Token"
method = "POST"
endpoint = "/user/tokens"
headers = { "Cookie" = "{{session_cookie}}" }
expected_status = 200
store = { "data.token" = "token" }

[[tests]]
name = "Access Protected Resource"
method = "GET"
endpoint = "/protected"
headers = { "x-api-token" = "{{token}}" }
expected_status = 200
```

## Next Steps

For more information about test configuration and advanced features, see:

- [Schema Reference](../reference/schema.md)
- [Test Reference Index](../reference/references.md)