catalyst 0.2.2

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
98
99
100
101
102
103
104

# 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

For cookie-based authentication, you can use the `auth_method` set to "Cookie":

```toml
[config]
base_url = "https://api.example.com"
auth_method = "Cookie"
default_headers = { "Content-Type" = "application/json" }
```

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

To use Bearer token authentication:

```toml
[config]
base_url = "https://api.example.com"
auth_method = "Bearer"
auth_token = "your-jwt-token"
```

This will add an `Authorization: Bearer your-jwt-token` header to all requests.

## 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:

- [Test File Structure](./test_file_structure.md) - Details on the overall structure of test files
- [Complete Reference](../reference/test_specification.md) - Comprehensive reference with examples for all features, including advanced assertions and response time validation