Skip to content

Commit 5349a3a

Browse files
committed
Start on the specification
1 parent 06ac766 commit 5349a3a

2 files changed

Lines changed: 135 additions & 1 deletion

File tree

‎HTTPSpec.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# HTTPSpec Specification
2+
3+
HTTPSpec is a specification format for describing HTTP requests and their expected responses, extending the familiar `.http` file format with a method for assertions. This enables automated testing and validation of HTTP APIs.
4+
5+
## 1. File Extension
6+
7+
Files should use the `.httpspec` extension.
8+
9+
## 2. Request Format
10+
11+
Each request block follows the standard `.http` file format:
12+
13+
```
14+
### Optional comment or test name
15+
<HTTP_METHOD> <URL> [HTTP_VERSION]
16+
<Header-Name>: <Header-Value>
17+
...
18+
19+
<Optional request body>
20+
21+
//# <assertions>
22+
```
23+
24+
**Example:**
25+
```
26+
### Get user by ID
27+
GET https://api.example.com/users/123
28+
Authorization: Bearer {{token}}
29+
Accept: application/json
30+
31+
//# status == 200
32+
//# header["content-length"] = 2345
33+
```
34+
35+
## 3. Variable Substitution
36+
37+
Variables can be defined and referenced using `{{variable}}` syntax.
38+
39+
**Example:**
40+
```
41+
@token = abc123
42+
GET https://api.example.com/users/123
43+
Authorization: Bearer {{token}}
44+
```
45+
46+
## 4. Assertions
47+
48+
Assertions are specified in the final block of a request, and begin with `//#`.
49+
50+
**Syntax:**
51+
```
52+
//# status == 200
53+
//# header["content-length"] = 2345
54+
```
55+
56+
### 4.1 Assertion Types
57+
58+
- **Status Code:**
59+
`status == <code>`
60+
- **Header Value:**
61+
`header["<Header-Name>"] == "<expected value>"`
62+
- **JSON Body:**
63+
`body.<json_path> == <expected value>`
64+
- **Body Contains:**
65+
`body contains "<substring>"`
66+
- **Custom Expressions:**
67+
Use JavaScript-like expressions for advanced checks.
68+
69+
**Example:**
70+
```
71+
GET https://api.example.com/users/123
72+
73+
> assert
74+
status == 200
75+
header["Content-Type"] == "application/json"
76+
body.id == 123
77+
body.name == "John Doe"
78+
body.email contains "@example.com"
79+
> endassert
80+
```
81+
82+
### 4.2 JSON Path
83+
84+
Use dot notation for JSON body assertions. Arrays can be accessed with `[index]`.
85+
86+
**Example:**
87+
```
88+
body.data[0].id == 1
89+
```
90+
91+
## 5. Comments
92+
93+
Lines starting with `#` are comments and ignored by the parser.
94+
95+
## 6. Multiple Requests
96+
97+
Multiple request/assertion blocks can be included in a single file, separated by blank lines. This is intended to support the usecase of a setup/teardown type logic, as well as tests that model a series of requests/responses.
98+
99+
## 7. Example HTTPSpec File
100+
101+
```
102+
@token = abc123
103+
104+
### Get user by ID
105+
GET https://api.example.com/users/123
106+
Authorization: Bearer {{token}}
107+
Accept: application/json
108+
109+
110+
//# status == 200
111+
//# header["Content-Type"] == "application/json"
112+
//# body.id == 123
113+
//# body.email contains "@example.com"
114+
115+
### Create new user
116+
POST https://api.example.com/users
117+
Content-Type: application/json
118+
119+
{
120+
"name": "Alice"
121+
}
122+
123+
//# status == 201
124+
//# body.name == "Alice"
125+
```
126+
127+
---
128+
129+
## 8. Extensibility
130+
131+
Future versions may support:
132+
- More assertion types (e.g., regex, timeouts)
133+
- Setup/teardown hooks
134+
- Response variable extraction
135+
- Non-JSON specific parsing (XML, etc.)

‎src/main.zig‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,6 @@ pub fn main() !void {
3636
// threads.
3737
// var request_files = std.ArrayList([]HttpParser.HttpRequest).init(allocator);
3838
for (res.positionals[0]) |pos| {
39-
std.debug.print("{s}\n", .{pos});
4039
// TODO: Each one gets its own areana?
4140
var items = try HttpParser.parseFile(allocator, pos);
4241
const owned_items = try items.toOwnedSlice();

0 commit comments

Comments
 (0)