Skip to content

Commit d76a559

Browse files
arifsznarifszn
committed
Add More Examples page
1 parent 0df2fda commit d76a559

1 file changed

Lines changed: 323 additions & 0 deletions

File tree

‎docs/4.-more-examples.md‎

Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
---
2+
title: More Examples
3+
hide_title: true
4+
---
5+
6+
**Note:**
7+
8+
- This page should be use as reference for specification files.
9+
- This page is subject to change. It is requested to check this page frequently.
10+
11+
---
12+
13+
This page describes some key concepts before you use **chkware**. There are two parts to this tool.
14+
15+
1. The command line tool that you can run as `chk`
16+
2. The test specification files: those you write in YAML, in supported DSL.
17+
18+
### Test specifications
19+
20+
Test specification files are written in YAML. So, before you start writing any specs, you should have a proper introduction to YAML, if you do not have already. Here is a fine [YAML cheatsheet](https://quickref.me/yaml) to grasp some knowledge.
21+
22+
> In the future evolution path of **chkware** we are going to introduce more and more specification options and specification types and versions.
23+
24+
Let’s first get you introduced to the (till now) only specification format supported by **chkware**, the Http specification format. As mentioned in the introduction page **_Create reusable offline http request specification._**, the Http specification format is how you express a Http request format. Following are some examples by case to write Http specification file.
25+
26+
---
27+
28+
### Reference
29+
30+
Following yaml blocks can be used to identify different section of a Http specification file.
31+
32+
```yaml
33+
---
34+
request:
35+
# valid URL
36+
url: https://reqres.in/api/users/2
37+
38+
# for query string or url parameters
39+
url_params:
40+
one: 1
41+
two: true
42+
43+
# http method to use
44+
method: GET # or POST, PUT, PATCH, DELETE, OPTIONS, HEAD
45+
46+
# send requst headers
47+
# add any numbers of headers
48+
# Causion: some values or keys need to be wrapped with single (') or double (") quote
49+
headers:
50+
User-Agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36'
51+
'Accept-Encoding': 'gzip, deflate'
52+
accept: '*/*'
53+
54+
# send authentication header.
55+
# two supported type: auth[bearer], auth[basic]:
56+
57+
# auth[bearer] example
58+
auth[bearer]:
59+
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
60+
61+
# auth[basic] example
62+
auth[basic]:
63+
username: Some_USER
64+
password: 'Some-P@$$W03D'
65+
66+
# send request body with the request
67+
68+
# no body to send
69+
body[none]: ~
70+
71+
# to send application/x-www-form-urlencoded form enctype
72+
body[form]:
73+
'var 1': 'var str 1'
74+
var-2: 'var str 2'
75+
# note: this will just pass filepath as value
76+
var_3: file:///home/username/.vimrc
77+
78+
# to upload file as part of body use multipart/form-data like
79+
body[form-data]:
80+
'var 1': 'var str 1'
81+
var-2: 'var str 2'
82+
# note this will actually upload a file
83+
# we use file protocol (file://) scheme to identify a file
84+
var_3: file:///home/username/.vimrc
85+
var4: file:///home/username/Documents/CID-25601.IpPhone.rtf
86+
87+
# to send plain text
88+
body[text]: 'Plain text here'
89+
90+
# to pass as json to body pass a yaml object like
91+
body[json]: { user_id: 32, roll_no: 1, class: 2, name: 'Student name' }
92+
93+
# to pass a xml as body use a yaml literal block
94+
body[xml]: |
95+
<?xml version="1.0"?>
96+
<catalog>
97+
<book id="bk101">
98+
<author>Gambardella, Matthew</author>
99+
<title>XML Developer's Guide</title>
100+
<genre>Computer</genre>
101+
<price>44.95</price>
102+
<publish_date>2000-10-01</publish_date>
103+
<description>An in-depth look at creating applications
104+
with XML.</description>
105+
</book>
106+
<book id="bk102">
107+
<author>Ralls, Kim</author>
108+
<title>Midnight Rain</title>
109+
<genre>Fantasy</genre>
110+
<price>5.95</price>
111+
<publish_date>2000-12-16</publish_date>
112+
<description>A former architect battles corporate zombies,
113+
an evil sorceress, and her own childhood to become queen
114+
of the world.</description>
115+
</book>
116+
</catalog>
117+
```
118+
119+
---
120+
121+
### Examples
122+
123+
Following are the examples with HTTP GET method. Although all these example are still valied for POST, PUT, PATCH, DELETE, OPTIONS, HEAD method as well.
124+
125+
#### Minimal request
126+
127+
```yaml
128+
---
129+
request:
130+
url: https://example.org/api/path
131+
method: GET
132+
```
133+
134+
#### Request with query string
135+
136+
```yaml
137+
---
138+
# put variables on the path
139+
request:
140+
url: https://example.org/api/path?foo=bar&two=2
141+
method: GET
142+
```
143+
144+
or you can also do like:
145+
146+
```yaml
147+
---
148+
# put variables as url_params entry
149+
request:
150+
url: https://example.org/api/path
151+
method: GET
152+
url_params:
153+
foo: bar
154+
two: 2
155+
```
156+
157+
#### Request with query string and header
158+
159+
```yaml
160+
---
161+
request:
162+
url: https://example.org/api/resource/action
163+
method: GET
164+
165+
url_params:
166+
foo: bar
167+
two: 2
168+
169+
headers:
170+
User-Agent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/97.0.4692.71 Safari/537.36'
171+
Accept-Encoding: gzip, deflate
172+
```
173+
174+
#### Request with basic authentication header
175+
176+
```yaml
177+
---
178+
request:
179+
url: https://example.org/api/resource/id
180+
method: GET
181+
182+
headers:
183+
Accept-Encoding: gzip, deflate
184+
Content-Type: application/json
185+
186+
auth[basic]:
187+
username: Some_USER
188+
password: 'Some-P@$$W03D'
189+
```
190+
191+
`username` and `password` will be automatically transformed to secret string as per [Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme) scheme.
192+
193+
#### Request with bearer authentication header
194+
195+
```yaml
196+
---
197+
request:
198+
url: https://example.org/api/resource/id
199+
method: GET
200+
201+
headers:
202+
Accept-Encoding: gzip, deflate
203+
Content-Type: application/json
204+
205+
auth[bearer]:
206+
token: eyJhbGciOiJIU...4fwpMeJf36POk6yJV_adQssw5c
207+
```
208+
209+
#### Request without a body
210+
211+
```yaml
212+
---
213+
request:
214+
url: https://example.org/api/resource/action
215+
method: POST
216+
217+
headers:
218+
Accept-Encoding: gzip, deflate
219+
Content-Type: application/json
220+
221+
auth[bearer]:
222+
token: eyJhbGciOiJIU...4fwpMeJf36POk6yJV_adQssw5c
223+
224+
body[none]: ~
225+
```
226+
227+
#### Request with JSON body
228+
229+
```yaml
230+
---
231+
request:
232+
url: https://example.org/api/resource/action
233+
method: POST
234+
235+
headers:
236+
Accept-Encoding: gzip, deflate
237+
Content-Type: application/json
238+
239+
auth[bearer]:
240+
token: eyJhbGciOiJIU...4fwpMeJf36POk6yJV_adQssw5c
241+
242+
body[json]: { user_id: 32, roll_no: 1, class: 2, name: 'Student name' }
243+
```
244+
245+
#### Request with form
246+
247+
Following example will submit a plain html form POST with encoding type `application/x-www-form-urlencoded`
248+
249+
```yaml
250+
---
251+
request:
252+
url: https://example.org/api/resource/action
253+
method: POST
254+
255+
headers:
256+
Accept-Encoding: gzip, deflate
257+
Content-Type: application/json
258+
259+
auth[bearer]:
260+
token: eyJhbGciOiJIU...4fwpMeJf36POk6yJV_adQssw5c
261+
262+
body[form]:
263+
user_id: 32,
264+
roll_no: 1,
265+
class: 2,
266+
name: 'Student name'
267+
photo: file:///home/username/student-photo-01.png # note: this will just pass filepath as string, not the actual file
268+
```
269+
270+
#### Request with file upload
271+
272+
Following example will submit a plain html form POST with encoding type `multipart/form-data`
273+
274+
```yaml
275+
---
276+
request:
277+
url: https://example.org/api/resource/id
278+
method: PUT
279+
280+
headers:
281+
Accept-Encoding: gzip, deflate
282+
Content-Type: application/json
283+
284+
auth[bearer]:
285+
token: eyJhbGciOiJIU...4fwpMeJf36POk6yJV_adQssw5c
286+
287+
body[form-data]:
288+
user_id: 32,
289+
roll_no: 1,
290+
class: 2,
291+
name: 'Student name'
292+
photo: file:///home/username/student-photo-01.png # note: this will actually upload the file
293+
cover_photo: file:///home/username/student-cvphoto-01.png
294+
```
295+
296+
#### Request with XML in body
297+
298+
Following example will submit a plain html form POST with encoding type `multipart/form-data`
299+
300+
```yaml
301+
---
302+
request:
303+
url: https://example.org/api/resource/action
304+
method: POST
305+
306+
headers:
307+
Accept-Encoding: gzip, deflate
308+
Content-Type: application/xml
309+
310+
body[xml]: |
311+
<?xml version="1.0"?>
312+
<catalog>
313+
<book id="bk101">
314+
<author>Gambardella, Matthew</author>
315+
<title>XML Developer's Guide</title>
316+
<genre>Computer</genre>
317+
<price>44.95</price>
318+
<publish_date>2000-10-01</publish_date>
319+
<description>An in-depth look at creating applications
320+
with XML.</description>
321+
</book>
322+
</catalog>
323+
```

0 commit comments

Comments
 (0)