Merge pull request #57 from chkware/release/v0.4.2-site

Release: v0.4.2 site documentation update

Author: 0hsn

README.md

@@ -1,119 +1,8 @@
-# `chkware` website
+# CHKware website
 
-This repository holds source code and publishable website for [**`chkware`**](https://github.com/chkware/cli#readme). Please access using https://chkware.github.io.
+This repository holds source code and publishable website for [CHKware](https://github.com/chkware/cli).
 
-### Installation
+### Install and setup
 
-Clone the repo:
-
-```sh
-git clone https://github.com/chkware/chkware.github.io.git
-cd chkware.github.io
-```
-
-Install dependencies:
-
-```sh
-npm install
-```
-
-### Local Development
-
-```
-$ npm start
-```
-
-This command starts a local development server and opens up a browser window. You can also follow `http://localhost:3000/` URL in any browser.
-
-Most changes are reflected live reload without having to restart the server.
-
-### Build
-
-```
-$ npm run build
-```
-
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
-
-### Guides
-
-Learn how to contribute to this website.
-
-### Configs
-
-All the configs can be found in `docusaurus.config.js`.
-
-#### Create a doc page
-
-Create a Markdown file, `example.md`, and place it under the `docs` directory. Any markdown file will render into the site without needing any extra configuration. It will be displayed alphabetically on the sidebar.
-
-```bash
-root
-├── docs
-│   └── example.md
-├── docusaurus.config.js
-├── ...
-```
-
-Markdown documents can use the Markdown front matter metadata fields, enclosed by a line `---` on either side. At the top of the file, you can optionally specify attributes in the front matter, so that Docusaurus will pick them up correctly when generating the site. Accepted fields can be found [here](https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter).
-
-#### Create a doc category
-
-Creating a `example.md` in a sub folder will create a category in the sidebar.
-
-```bash
-root
-├── docs
-│   └── sub-folder
-│       └── example.md
-```
-
-To change the category name or other category meta data, an optional file `_category_.json` can be created in the respective sub folder. More [here](https://docusaurus.io/docs/next/sidebar/autogenerated#autogenerated-sidebar-metadata).
-
-```json
-{
-  "label": "Tutorial"
-}
-```
-
-#### Static Assets
-
-The Static Assets can be found in the `static` folder. More [here](https://docusaurus.io/docs/next/static-assets).
-
-#### Change theme color
-
-Generate the variables from [here](https://docusaurus.io/docs/next/styling-layout#styling-your-site-with-infima). Then replace the variables in `src/css/custom.css` with these new variables. Don't forget variables for dark mode.
-
-#### Change codeBlock theme
-
-Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer) to highlight code blocks. All configuration are in the `prism` object of `docusaurus.config.js`. You can specify a custom theme from the [list of available themes](https://github.com/FormidableLabs/prism-react-renderer/tree/master/src/themes).
-
-#### Syntax highlighting
-
-To add syntax highlighting for any of the other [Prism-supported languages](https://prismjs.com/#supported-languages), define it in an array of additional languages. More [here](https://docusaurus.io/docs/next/markdown-features/code-blocks#supported-languages).
-
-#### Change footer
-
-You can add logo and a copyright to the footer via `themeConfig.footer`. More [here](https://docusaurus.io/docs/next/api/themes/configuration#footer-1).
-
-#### Blog
-
-To set up blog, start by creating a `blog` directory. More [here](https://docusaurus.io/docs/next/blog).
-
-#### Admonitions
-
-In addition to the basic Markdown syntax, Docusaurus use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons. More [here](https://docusaurus.io/docs/next/markdown-features/admonitions).
-
-#### Update Docusaurus version
-
-To update Docusaurus version, manually change the version number in `package.json` to the desired version. Then run `npm run install`.
-
-Any required change/depricated message will be shown on the terminal when running the command `npm run start`. More [here](https://docusaurus.io/docs/next/installation#updating-your-docusaurus-version).
-
-### Status
-
-The current status of the website is **under construction**. Please follow us on Twitter [@chkware](https://twitter.com/chkware) for update. Thank you for your patience.
-
----
-
-`chkware` website uses [docusaurus v2.0.0-beta.17](https://github.com/facebook/docusaurus/releases/tag/v2.0.0-beta.17) as CMS backend.
+- Head to [CHKware website](https://chkware.github.io/setup), for documentation, if you want to use *CHKware* in your project.
+- Jump to the [setup for website developer](http://chkware.github.io/setup/setup-site-dev) if you want to contribute to this repository.

docs/assets/http-resp-xkcdcom.png

@@ -51,7 +51,8 @@ request:
     two: 2
 
   # get only response code
-  return: .code
+expose: 
+  - $_response.code
 ```
 
 ### Request with query string and header
@@ -149,8 +150,9 @@ request:
 
   body[json]: { user_id: 32, roll_no: 1, class: 2, name: 'Student name' }
   
-  # get every thing out of response received
-  return: ~
+# get every thing out of response received
+# not writing the following statement also does similar behavior
+expose: ~
 ```
 
 ### Request with form
@@ -185,8 +187,8 @@ request:
     # but will not upload the actual file
     photo: file:///home/username/student-photo-01.png
 
-  # get only response body; response headers, code, etc will be dropped
-  return: .body
+# get only response body; response headers, code, etc will be dropped
+expose: $_response.body
 ```
 
 ### Request with file upload

docs/assets/testcase-eximg-01.png

@@ -13,37 +13,114 @@ Case-wise more example can be found in [https://github.com/chkware/cli](https://
 
 [Testcase specification document reference](/references/testcase-reference)
 
-Testcase is an experimental feature, in _`PRE_ALPHA`_ stage.
+### A minimal Testcase with in-file request
 
-### Testcase with in-file request
+```yaml
+---
+version: 'default:testcase:0.7.2'
+
+request:
+  url: "https://reqres.in/api/users"
+  method: POST
+  body[json]: {
+    'name': My Name,
+    'job': My Job,
+  }
+
+spec:
+  asserts:
+    - {type: AssertEqual, actual: $_response.code, expected: 201}
+    - {type: AssertIsMap, actual: $_response.body}
+```
+
+The above testcase spec. doc define a request that makes a `POST` call to `https://reqres.in/api/users` URL with a body `{"name": "My Name", "job": "My Job"}`.
+
+After the request server responses with following:
+
+![reqres.in response](../assets/testcase-eximg-01.png)
+
+On the `asserts`, we are asserting that
+
+- The response code is 201, or the resource was created
+- The response if a map / dictionary
+
+Assertion [reference with examples](/references/testcase-reference#assertions) can be found here.
+
+### A minimal Testcase with out-file request
+
+A http spec. doc can be written on separate file, that does same as above request. Let's call it `same-request.chk`. The http spec. doc by default exposes `$_response` object.
 
 ```yaml
+# file: same-request.chk
+---
+version: 'default:http:0.7.2'
+
+request:
+  url: "https://reqres.in/api/users"
+  method: POST
+  body[json]: {
+    'name': My Name,
+    'job': My Job,
+  }
+```
+
+Now we can point out above file to execute before make assertions like below (assuming both file lives on same directory).
+
+```yaml
+# file: same-testcase.chk
 ---
 version: 'default:testcase:0.7.2'
 
+spec:
+  execute:
+    file: "./same-request.chk"
+  asserts:
+    - {type: AssertEqual, actual: $_response.code, expected: 201}
+    - {type: AssertIsMap, actual: $_response.body}
+```
+
+Please notice the `$_response` in the testcase doc. This variable is available after the request gets executed as local variable.
+
+### A Testcase with out-file request passing data
+
+To pass data from a testcase spec. doc to a http spec. doc, we first need to add some variables. These variables can also have some default value. Say in the following case, we defined `name` and `job` variables with default value. So, if no value passed these values will be passed to server as part of request body.
+
+```yaml
+# file: same-request.chk
+---
+version: 'default:http:0.7.2'
+
 variables:
-  Name: 'Morpheus'
-  Job: 'leader'
-  Response: ~
-  Server: https://reqres.in/api/v1
+  name: My Name
+  job: My Job
 
 request:
-  url: "{$Server}/users"
+  url: "https://reqres.in/api/users"
   method: POST
   body[json]: {
-    'name': $Name,
-    'job': $Job,
+    'name': $name,
+    'job': $job,
   }
-  return: ~
+```
+
+Now we can point out which value we want to pass using `with` statement in `execute` block.
+
+```yaml
+# file: same-testcase.chk
+---
+version: 'default:testcase:0.7.2'
 
 spec:
   execute:
-    file: ~
-    result: $Response
-
+    file: "./same-request.chk"
+    with:
+      name: Her Name
+      job: Her Job
   asserts:
-    - {type: AssertEqual, actual: $Response.code, expected: 201}
-    - {type: AssertIsMap, actual: $Response.body}
+    - {type: AssertEqual, actual: $_response.code, expected: 201}
+    - {type: AssertIsMap, actual: $_response.body}
 ```
 
-Assertion [reference with examples](/references/testcase-reference#assertions) can be found here.
+Please notice that if we do not set a `with` then request will be sent with default value.
+
+Assertion [reference with examples](/references/testcase-reference#assertions) can be found here.

docs/examples/http-examples.md

@@ -2,32 +2,31 @@
 slug: /
 title: Home
 hide_title: true
----
 
-![chkware | Test management for api era](./assets/github-readme-01.png)
+---
+![CHKware | Low-code API quality testing, and automation toolbox](./assets/github-readme-01.png)
 
 [![PyPI version](https://badge.fury.io/py/chk.svg)](https://badge.fury.io/py/chk)
-[![Python 3.8](https://img.shields.io/badge/python-3.10-red.svg)](https://www.python.org/downloads/release/python-3102/)
+[![Python 3.11](https://img.shields.io/badge/python-3.11-red.svg)](https://www.python.org/downloads/)
 [![Twitter](https://img.shields.io/twitter/url/https/twitter.com/chkware.svg?style=social&label=Follow%20%40chkware)](https://twitter.com/chkware)
-> Test management for API era.
 
 ### Introduction
 
-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***.
+API quality test, and automation 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***. 
 
-***chkware*** (pronounced as */check:ware/*) helps you write accurate, robust, and expressive feature tests for your API in less time.
+***CHKware*** (pronounced as */tʃek-wer/*, i.e. *check-ware*) is a low-code API quality testing, and automation toolbox. It helps you write accurate, robust, and expressive feature tests for your API in less time than usual.
 
-Read [more value propositions](/introduction) here. Find [changelog](https://github.com/chkware/cli/blob/main/docs/CHANGELOG.md) here.
+Read [about the problems](/introduction) *CHKware* addresses. Find [changelog](https://github.com/chkware/cli/blob/main/docs/CHANGELOG.md).
 
 ### Setup
 
-With [**Python 3.10**](https://www.python.org/downloads/) and [**Pipx**](https://pypa.github.io/pipx/installation/#install-pipx) preinstalled, run following in your terminal to get ***chkware*** installed.
+With [**Python 3.11**](https://www.python.org/downloads/) and [**Pipx**](https://pypa.github.io/pipx/installation/#install-pipx) preinstalled, run following in your terminal to get *CHKware* installed.
 
 ```bash
-$ pipx install chk
+pipx install chk
 ```
 
-Jump to the [setup guide](/setup) for different ways to install ***chkware***.
+Jump to the [setup guide](/setup) for different ways to install ***CHKware***.
 
 ### Usage
 

docs/examples/testcase-examples.md

@@ -2,19 +2,19 @@
 title: Introduction
 ---
 
-![chkware | Test management for api era](./assets/github-hero-01.png)
+![CHKware | Low-code API quality testing, and automation toolbox](./assets/github-hero-01.png)
 
-**chkware** (pronounced as */check:ware/*) is an API testing tool, a scriptable HTTP client, and a test specification management tool for the API era.
+
+*CHKware* (pronounced as */check:ware/*) is a low-code API testing tool, a script-able HTTP client, and an API test automation tool for the API era.
 
 It is available as a command-line application. You write test specification files in a [YAML](https://yaml.org/)-based [DSL](https://en.wikipedia.org/wiki/Domain-specific_language). In that specification file you will define some structured configurations to be used for the following purpose:
 
 - Create reusable http request specification. [alpha]
-- Create reusable test specifications. [TBD]
+- Create reusable test specifications. [alpha]
 
-Afterward, you run those test specification files with **chkware**, and get test results or even reuse them.
+Afterward, you run those test specification files with *CHKware*, and get test results or even reuse them.
 
 ---
-
 ### Motivation
 
 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.
@@ -29,13 +29,13 @@ For these reasons, the solutions are less scaling for actual use-cases. With add
 2. Added complexity of maintaining supporting software stack, so there are side effects 
 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.
 
-So, clearly enough I think this situation needs to be improved. This is the motivation for **chkware**.
+So, clearly enough I think this situation needs to be improved. This is the motivation for *CHKware*.
 
 ---
 
 ### Audiences
 
-The focused users of **chkware** are everyone involved in an API project, given they have some testing basics. 
+The focused users of **CHKware** are everyone involved in an API project, given they have some testing basics. 
 
 - People with zero programming knowledge need a tool that does not get in their way. 
 - We need a tool that is relatively easy to write specifications, expressive, and customizable to the very core. 
@@ -44,7 +44,7 @@ The focused users of **chkware** are everyone involved in an API project, given
 In practical cases, software testers / QAs, developers, PM/POs, are the people who should be able to use it rigorously.
 
 - This project is particularly helpful if you are developing an API oriented project.
-- Test websites or web interfaces are not in the project focus for now.
+- Writing specification to test websites, or web interfaces are not in the project focus for now.
 - Also, seeding data, validating data in DB is out of this project scope for now.
 
 ---
@@ -59,9 +59,9 @@ There is no native binary dependency, therefore it is expected on all the platfo
 
 ### Stability
 
-`chkware` is a tool collection. Followings are stability by tools:
+`CHKware` is a tool collection. Followings are stability by tools:
 
 Command name | Specification document | Stability
 ---|---|---
-`http`| Http | _`Alpha`_
-`testcase`| Testcase | _`Pre-Alpha`_
+`http`| Http | _alpha_
+`testcase`| Testcase | _alpha_