Skip to content

Commit 285a33d

Browse files
0hsn0hsn
authored
Merge pull request #17 from chkware/update-site
docs: refactor current POC with add / remove feature
2 parents 0d617e9 + 5c5028d commit 285a33d

18 files changed

Lines changed: 573 additions & 508 deletions

docs/intro.md renamed to docs/1.-introduction.md

Lines changed: 22 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,10 @@
11
---
2-
sidebar_position: 1
32
slug: /
3+
title: Introduction
4+
hide_title: true
45
---
56

6-
# Intro
7-
8-
API tests management is not easy to develop, and maintain. It requires multitude of knowledge of programming libraries, business scenarios, infrastructure details, etc - unless you use ***chkware***.
9-
10-
***chkware*** (pronounced as */check:ware/*) helps you write accurate, robust, and expressive feature tests for your API in less time.
11-
12-
## What it is
13-
14-
![Hero banner](./assets/github-hero-01.png)
7+
![Chkware | Test management for api era](./assets/github-hero-01.png)
158

169
**Chkware** is an API testing tool, a scriptable HTTP client, and a test specification management tool for the API era.
1710

@@ -24,29 +17,34 @@ It is available as a command-line application. You write test specification file
2417

2518
Afterward, you run those test specification files with **chkware**, and get test results or even reuse them.
2619

27-
## Motivation
20+
---
21+
22+
### Motivation
23+
24+
In today's world, API is one of the key fuels that drive business. It is the way web applications consume services from self-hosted or 3rd-party vendors. Recent technology movements are going to a fluid internet direction, where _vendor_A_ have one API, _vendor_B_ is another API provider, while we are the consumers (e-commerce, fin-tech) of those vendor APIs. We use those APIs to host our contents based on those APIs. Maybe we are _vendor_U_ hosting more complex APIs on top of those. So, with the upcoming complexity of integration we need better tooling for API testing. Testing tools for modularize api testing.
2825

29-
In today's world, API is one of the key fuels that drive business. It is the way web applications consume services from self-hosted or 3rd-party vendors. Recent technology movements are going to a fluid internet direction, where *vendor_A* have one API, *vendor_B* is another API provider, while we are the consumers (e-commerce, fin-tech) of those vendor APIs. We use those APIs to host our contents based on those APIs. Maybe we are *vendor_U* hosting more complex APIs on top of those. So, with the upcoming complexity of integration we need better tooling for API testing. Testing tools for modularize api testing.
30-
3126
API automation is playing a key role in this era. The benefits of API automation are clearly visible. There are plenty of tools to support all kinds of test automation. However, the complexity to create and maintain automated test cases using available tools is inescapable. No way it's quick to get started, or pick up without further education on the corresponding tools ecosystem. Furthermore, knowledge of the programming language that was used to develop the tools is also needed for advanced customization of test cases.
3227

33-
API testing tools are costly as well, in-term of licensing, setup and maintenance. Some of the tools you are available for free for simple use-cases, have complex licensing for increased usage, most of the time that aren't worth user usage. Also, commercial applications have limited community support, and knowledge exchange medium. Above that, of course, there are less and less open-source tools to cover these scenarios.
28+
API testing tools are costly as well, in-term of licensing, setup and maintenance. Some of the tools you are available for free for simple use-cases, have complex licensing for increased usage, most of the time that aren't worth user usage. Also, commercial applications have limited community support, and knowledge exchange medium. Above that, of course, there are less and less open-source tools to cover these scenarios.
3429

3530
For these reasons, the solutions are less scaling for actual use-cases. With additional business knowledge (that is ever growing) required to start and maintain tests, you also need:
36-
1) specific programming language knowledge, so it is not easy to jump-in quick
37-
2) added complexity of maintaining supporting software stack, so there are side-effects
38-
3) Above all, maintaining test cases based on code is more complex if you don't design your test code architecture well in the early days.
39-
31+
32+
1. specific programming language knowledge, so it is not easy to jump-in quick
33+
2. added complexity of maintaining supporting software stack, so there are side-effects
34+
3. Above all, maintaining test cases based on code is more complex if you don't design your test code architecture well in the early days.
35+
4036
So, clearly enough I think this situation needs to be improved. This is the motivation for **Chkware**.
4137

42-
## Audiences
38+
---
39+
40+
### Audiences
41+
42+
The focused users of chkware are everyone involved in an API project, given they have some testing basics.
4343

44-
The focused users of chkware are everyone involved in an API project, given they have some testing basics.
45-
46-
- People with zero programming knowledge need a tool that does not get in their way.
47-
- We need a tool that is relatively easy to write specifications, expressive, and customizable to the very core.
44+
- People with zero programming knowledge need a tool that does not get in their way.
45+
- We need a tool that is relatively easy to write specifications, expressive, and customizable to the very core.
4846
- We need a tool that is very easy to learn, and fun to use.
49-
47+
5048
In practical cases, software testers / QAs, developers, PM/POs, are the people who should be able to use it rigorously.
5149

5250
- This project is particularly helpful if you are developing an API oriented project.

docs/setup.md renamed to docs/2.-setup.md

Lines changed: 62 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,62 @@
1-
---
2-
sidebar_position: 2
3-
sidebar_label: Setup
4-
hide_title: true
5-
---
6-
7-
### Installation
8-
9-
The currently supported python version is ***Python 3.8.**** You need to have this version of python in your OS to continue any of the following steps.
10-
11-
**Method 1: with pipx**
12-
13-
The best way to setup any python app is manage it via [pipx](https://pypa.github.io/pipx/). Pipx is a standred pypi python application manager.
14-
15-
First, [Install pipx](https://pypa.github.io/pipx/installation/). Then run
16-
17-
```bash
18-
$ pipx install chk
19-
```
20-
21-
**Method 2: with pip (globally)**
22-
23-
Alternatively you can install with `pip` like other regular python package following these step. However, it will install the package globally.
24-
25-
```bash
26-
$ python3 -m pip install -U pip # upgrade pip
27-
$ python3 -m pip install -U chk
28-
```
29-
30-
**Method 3: with pip (locally)**
31-
32-
To install under a seperate environment, that don't change your global package space. Install under a virtual env.
33-
34-
```bash
35-
$ python3 -m venv .venv # create virtual environemnt
36-
$ source .venv/bin/activate # active virtual environemnt
37-
$ pip install -U pip # upgrade pip
38-
$ pip install -U chk
39-
```
40-
41-
---
42-
### Upgrade
43-
44-
If you have installed with **pipx** then use following to upgrade to latest released version.
45-
46-
```bash
47-
$ pipx upgrade chk
48-
```
49-
50-
Otherwise, if **pip** was used to install then same process given above should work for upgrade as well.
51-
52-
---
53-
### Platform support
54-
55-
For now this tool is developed and tested on **macOS** only. We are working hard to make it available on Linux platform.
56-
57-
---
58-
### Stability
59-
60-
Current stability for this tool is _Pre - Alpha_
1+
---
2+
title: Setup
3+
hide_title: true
4+
---
5+
6+
### Installation
7+
8+
The currently supported python version is **\*Python 3.8.\*\*** You need to have this version of python in your OS to continue any of the following steps.
9+
10+
**Method 1: with pipx**
11+
12+
The best way to setup any python app is manage it via [pipx](https://pypa.github.io/pipx/). Pipx is a standred pypi python application manager.
13+
14+
First, [Install pipx](https://pypa.github.io/pipx/installation/). Then run
15+
16+
```bash
17+
$ pipx install chk
18+
```
19+
20+
**Method 2: with pip (globally)**
21+
22+
Alternatively you can install with `pip` like other regular python package following these step. However, it will install the package globally.
23+
24+
```bash
25+
$ python3 -m pip install -U pip # upgrade pip
26+
$ python3 -m pip install -U chk
27+
```
28+
29+
**Method 3: with pip (locally)**
30+
31+
To install under a seperate environment, that don't change your global package space. Install under a virtual env.
32+
33+
```bash
34+
$ python3 -m venv .venv # create virtual environemnt
35+
$ source .venv/bin/activate # active virtual environemnt
36+
$ pip install -U pip # upgrade pip
37+
$ pip install -U chk
38+
```
39+
40+
---
41+
42+
### Upgrade
43+
44+
If you have installed with **pipx** then use following to upgrade to latest released version.
45+
46+
```bash
47+
$ pipx upgrade chk
48+
```
49+
50+
Otherwise, if **pip** was used to install then same process given above should work for upgrade as well.
51+
52+
---
53+
54+
### Platform support
55+
56+
For now this tool is developed and tested on **macOS** only. We are working hard to make it available on Linux platform.
57+
58+
---
59+
60+
### Stability
61+
62+
Current stability for this tool is _Pre - Alpha_

‎docs/3.-quick-start.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: Quick Start
3+
hide_title: true
4+
---
5+
6+
To quickly start, let's try something live online.. [REQ|RES](https://reqres.in) is a hosted demo REST api service. Let's call a simple API endpoint from here.
7+
8+
> First [setup chkware](2.-Setup).
9+
10+
Go to https://reqres.in, and find there is an endpoint like **_GET_ SINGLE USER** we'll call this API with Chkware. So, follow these steps:
11+
12+
1. Create a file called `User.chk`.
13+
2. Put following content
14+
15+
```yaml
16+
---
17+
request:
18+
url: https://reqres.in/api/users/2
19+
method: GET
20+
```
21+
22+
3. from terminal run following
23+
24+
```bash
25+
$ chk User.chk
26+
```
27+
28+
See the output like
29+
30+
```text
31+
HTTP/1.1 200 OK
32+
Date: Sat, 29 Jan 2022 16:46:26 GMT
33+
Content-Type: application/json; charset=utf-8
34+
Transfer-Encoding: chunked
35+
...truncated-headers...
36+
alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400
37+
38+
{'data': {'id': 2, 'email': 'janet.weaver@reqres.in', 'first_name': 'Janet', 'last_name': 'Weaver', 'avatar': 'https://reqres.in/img/faces/2-image.jpg'}, 'support': {'url': 'https://reqres.in/#support-heading', 'text': 'To keep ReqRes free, contributions towards server costs are appreciated!'}}
39+
```
40+
41+
:wink::tada::confetti_ball:
42+
43+
---
44+
45+
Now let's try a more complex API. Let's call COVID-19 data from RapidAPI. You can call this api for any country with a two letter country code. Let's do the following to fetch covid-19 data for Bangladesh:
46+
47+
1. Register or login to https://rapidapi.com
48+
2. Subscribe to https://rapidapi.com/Gramzivi/api/covid-19-data/ this source.
49+
3. Create a directory called `~/project` and `covid-19.chk` in it
50+
4. Now open `covid-19.chk` file and add following data
51+
52+
```yaml
53+
---
54+
request:
55+
url: https://covid-19-data.p.rapidapi.com/report/country/code
56+
url_params:
57+
code: bd
58+
date: '2020-04-01'
59+
method: GET
60+
headers:
61+
X-RapidAPI-Host: 'covid-19-data.p.rapidapi.com'
62+
X-RapidAPI-Key: '<your X-RapidAPI-Key>'
63+
```
64+
65+
1. hit enter writing following command on terminal
66+
67+
```bash
68+
$ cd ~/project
69+
$ chk covid-19.chk
70+
```
71+
72+
1. You'll get output like this
73+
74+
```text
75+
HTTP/1.1 200 OK
76+
Cache-Control: no-cache, private
77+
Content-Type: application/json
78+
Date: Sun, 23 Jan 2022 04:28:35 GMT
79+
ETag: "69236d0ee4cbd7e37314028f0a8b01be"
80+
Server: RapidAPI-1.2.8
81+
Vary: Accept
82+
X-RapidAPI-Region: AWS - ap-southeast-1
83+
X-RapidAPI-Version: 1.2.8
84+
X-RateLimit-Requests-Limit: 50000
85+
X-RateLimit-Requests-Remaining: 49988
86+
X-RateLimit-Requests-Reset: 2175151
87+
Content-Length: 182
88+
Connection: keep-alive
89+
90+
[{'country': 'Bangladesh', 'provinces': [{'province': 'Bangladesh', 'confirmed': 54, 'recovered': 25, 'deaths': 6, 'active': 23}], 'latitude': 23.684994, 'longitude': 90.356331, 'date': '2020-04-01'}]
91+
```
92+
93+
:wink::tada::confetti_ball:
94+
95+
You just fetch a live API. Going further, you should save these `.chk` files in git repo, so that you can run it later, from anywhere where **chkware** is installed. Cheers.

0 commit comments

Comments
 (0)