Merge pull request #8 from calloc134/docs/20230907-docs

Docs/20230907 docs
calloc134 · Sep 8, 2023 · 0c1d370 · 0c1d370
2 parents 1de0976 + 50ba633
commit 0c1d370
Show file tree

Hide file tree

Showing 6 changed files with 116 additions and 240 deletions.
diff --git a/README.md b/README.md
@@ -5,245 +5,13 @@
 
 ![image](raxtest.output.svg)
 
-## 概要 / general
+## general
 
-raxtestは、apiのテストを行うための、Rustで書かれた非同期で動作する軽量なツールです。
+Raxtest is an **asynchronous** api testing tool for RESTful APIs.
 
-## インストール / install
+## docs
 
-```bash
-$ cargo install --git https://github.com/calloc134/raxtest.git
-```
+See [docs](https://calloc134.github.io/raxtest/).
 
-## 使い方 / usage
-
-```bash
-$ raxtest -i (index.ymlのパス) -o (output.jsonのパス)
-```
-
- - index.yml: テストの設定を格納するyaml形式のファイル
- - output.json: テストの結果を保存するjson形式のファイル
-
-## 特徴 / features
-
- - 非同期で動作  
-テストステップは全て非同期で動作します。
- - テストの初期化処理を行うことができる  
-ログイン処理など、テスト前に発声する初期化処理を自動化することができます。
- - テストの結果をjson形式で出力することができる  
-json形式で出力することができるため、CI/CDツールに組み込みやすくなっています。
-
-## index.ymlの書き方 / how to write index.yml
-
-以下に例を示します。
-```yaml 
-base_url: http://localhost
-data: json://data.json
-init:
-- name: ApiAuthLogin(POST)
-  path: /api/auth/login
-  method: POST
-  ref_data: ApiAuthLogin(POST)
-  option:
-    query: false
-    body: true
-
-categories:
-  no_loginStep:
-    - name: ApiUserMe(GET)
-      path: /api/user/me
-      method: GET
-      ref_data: no_login/ApiUserMe(GET)
-      option:
-        query: false
-        body: false
-
-  loginStep:
-    login: ApiAuthLogin(POST)
-    - name: ApiUserMe(PUT)
-      path: /api/user/me
-      method: PUT
-      ref_data: ApiAuthLogin(POST)/ApiUserMe(PUT)
-      option:
-        query: false
-        body: true
-    - name: ApiUserMe(DELETE)
-      path: /api/user/me
-      method: DELETE
-      ref_data: ApiAuthLogin(POST)/ApiUserMe(DELETE)
-      option:
-        query: false
-        body: false
-    - name: ApiProfileScreenName_GET
-      path: /api/profile/@{screenName}
-      method: GET
-      ref_data: ApiAuthLogin(POST)/ApiUserMe(DELETE)
-      option:
-        query: true
-        body: false
-
-```
-それぞれの項目の意味を以下に示します。
-
- - base_url  
-テスト対象のサーバのベースURLを指定します。
- -  data  
-テストに使用するデータを格納したファイルのパスを指定します。  
-json形式のファイルを指定することができます。  
-パスは相対パスで指定できますが、index.ymlと同じディレクトリに配置することを推奨します。
- -  init  
-テストの初期化を行うステップを指定します。  
-ここではシーケンスを用いて、複数のステップを指定することができます。
- -  categories  
-テストを行うステップのカテゴリを指定します。 
-
-カテゴリのオプションは以下の通りです。
-
-  - login: init内の参照するログイン情報のステップの名前
-  - steps: テストを行うステップのシーケンス
-
-loginで、init内からログイン情報(クッキー)を参照するステップの名前を指定します。
-stepsで、複数のステップを指定できます。
-
-ステップのオプション項目は以下の通りです。
-
-  - name: ステップの名前    
-ステップの名前は、他のステップから参照する際に使用します。  
-そのため、ステップの名前は一意である必要があります。
-
-  - path: リクエストのパス  
-リクエストのパスは、base_urlと結合されてリクエストのURLとなります。  
-また、pathには、queryオプションで指定したファイル内のデータを参照することができます。  
-その際は、`{name}`のように、`{}`で囲んで指定します。
-この場合、dataで指定したファイル内に、`name`というキーが存在する必要があります。
-
-  - method: リクエストのメソッド  
-リクエストのメソッドは、GET, POST, PUT, DELETEなどを指定できます。
-
- - ref_data: リクエストのデータを参照する際のタグ  
-リクエストのデータを参照する際に使用するタグを指定します。
-ここで指定したタグは、bodyやqueryで使用することができます。
-
-  - option: リクエストのオプション  
-ここでは、queryとbodyをデータから参照するかどうかを指定できます。
-
-
-## data.jsonの書き方 / how to write data.json
-
-以下に例を示します。
-
-```json
-{
-  "ApiAuthLogin(POST)": [
-    {
-      "body": {
-        "handle": "johndoe2",
-        "password": "Password123@"
-      },
-      "expect_status": 0
-    }
-  ],
-  "ApiAuthLogin(POST)/ApiUserMe(GET)": [
-    {
-      "expect_status": 200
-    }
-  ],
-  "ApiAuthLogin(POST)/ApiUserMe(PUT)": [
-    {
-      "body": {
-        "bio": "じょんどえじょんどえ"
-      },
-      "expect_status": 200
-    },
-    {
-      "body": {
-        "screen_name": "じょんどえ2"
-      },
-      "expect_status": 200
-    },
-    {
-      "body": {
-        "hidden_comment": "じょんどえhidden"
-      },
-      "expect_status": 400
-    },
-    ...
-  ],
-}
-
-```
-
-data.jsonは、json形式のファイルです。  
-このファイル内に、テストに使用するデータを格納します。  
-プロパティはbody, query, expect_statusが対応しており、使用するデータは複数格納することが可能です。  
-bodyオプションでは、`body`キーの値を、queryオプションでは、`query`キーの値を参照します。
-また、expect_statusオプションでは、`expect_status`キーの値を参照します。
-
-## output.jsonの構成 / structure of output.json
-
-出力されるoutput.jsonは以下の通りです。
-
-```json
-{
-  "base_url": "http://localhost",
-  "results": [
-    {
-      "name": "no_login/ApiUserMe(DELETE)[0]",
-      "category": "no_login",
-      "status": "success",
-      "duration": 0.0126284,
-      "message": "success (status: 401 Unauthorized, expect status: 401)"
-    },
-    {
-      "name": "no_login/ApiUserMe(GET)[0]",
-      "category": "no_login",
-      "status": "success",
-      "duration": 0.0099064,
-      "message": "success (status: 401 Unauthorized, expect status: 401)"
-    },
-    {
-      "name": "no_login/ApiUserMe(PUT)[0]",
-      "category": "no_login",
-      "status": "success",
-      "duration": 0.007595,
-      "message": "success (status: 401 Unauthorized, expect status: 401)"
-    },
-    ...
-  ]
-}
-```
-
-これらのオプションは以下の通りです。
-
-  - base_url  
-テスト対象のサーバのベースURLを指定します。
-
-  - results  
-テスト結果を格納する配列です。
-
-また、results配列内の各要素は以下の通りです。
-
-  - name  
-ステップの名前です。
-
- - category
-ステップの所属するカテゴリです。
-
-  - status  
-ステップの結果を示します。
-`success`または`failure`のいずれかの値を取ります。
-
-  - duration  
-ステップの実行時間を示します。
-
-  - message  
-ステップの詳細結果を示します。  
-テストが成功した場合は、`passed`となります。  
-テストが失敗した場合は、`failed (status: XXX Bad Request, expect status: XXX)`のように、ステータスコードと期待するステータスコードを示します。
-
-## 注意事項 / caution
-このプログラムは現在開発中のため、バグが含まれている可能性があります。  
-また、バグを発見した場合は、PRを送っていただけると幸いです。
-
-## 姉妹プロジェクト / sister projects
- - [openapi2raxtest](https://github.com/calloc134/openapi2raxtest) : OpenAPIからRaxTestのテストケースを生成するツール
+## license 
+  - MIT
diff --git a/docs/docs/overview.md b/docs/docs/overview.md
@@ -6,14 +6,15 @@ sidebar_position: 1
 
 Raxtest is an **asynchronous** api testing tool for RESTful APIs. 
 
-Here is the [github repo](https://github.com/calloc134/raxtest).
-
 It is designed to be simple but powerful.
 
  - Support for **init steps** such as login
  - **Asynchronous** api testing
  - **JSON Data** import and export
  - Generate test cases from **openapi documents** in `openapi2raxtest` command
 
+## License
+  - MIT
+
 
 
diff --git a/docs/docs/raxtest/guide/data.md b/docs/docs/raxtest/guide/data.md
@@ -0,0 +1,40 @@
+---
+sidebar_position: 4
+---
+
+# Data Structure
+
+
+Data file is a json file that contains the data used in the test cases.  
+Each data supports multiple test cases.
+
+```json
+{
+  "no_login/ApiUserMe(GET)": [
+    {
+      "body": {
+        "handle": "johndoe2",
+        "password": "Password123@"
+      },
+      "query": {
+        "handle": "johndoe2"
+      },
+      "expect_status": 200
+    }
+  ],
+  (...)
+}
+```
+
+### body
+The body of the request.  
+Type: `object`
+
+### query
+The query of the request.  
+Type: `object`
+
+### expect_status
+The expected status code of the response.  
+This status code is used to determine whether the test case is passed or failed.  
+Type: `number`
diff --git a/docs/docs/raxtest/guide/output.md b/docs/docs/raxtest/guide/output.md
@@ -0,0 +1,59 @@
+---
+sidebar_position: 5
+---
+
+# Output
+
+```json
+{
+  "base_url": "http://localhost",
+  "results": [
+    {
+      "name": "no_login/ApiUserMe(DELETE)[0]",
+      "category": "no_login",
+      "status": "success",
+      "duration": 0.0126284,
+      "message": "success (status: 401 Unauthorized, expect status: 401)"
+    },
+    (...)
+  ]
+}
+```
+
+## base_url
+
+The base url of the api server.  
+Type: `string`
+
+## results
+
+An array that stores the test results.  
+Type: `array`
+
+Each element in the results array is as follows.
+
+### name
+
+The name of the step.  
+Type: `string`
+
+### category
+
+The category to which the step belongs.  
+Type: `string`
+
+### status
+
+Indicates the result of the step.  
+Takes one of the values `success` or `failure`.  
+Type: `string`
+
+### duration
+
+Indicates the execution time of the step.  
+Type: `float`
+
+### message
+
+Indicates the message of the step.  
+Type: `string`
diff --git a/docs/docs/raxtest/guide/required_options.md b/docs/docs/raxtest/guide/required_options.md
@@ -4,6 +4,12 @@ sidebar_position: 1
 
 # Required Options
 
+```yaml 
+base_url: http://localhost
+data: json://data.json
+(...)
+```
+
 ## base_url
 
 The base url of the api server.  

diff --git a/docs/docs/raxtest/overview.md b/docs/docs/raxtest/overview.md
@@ -6,6 +6,8 @@ sidebar_position: 1
 
 Raxtest is an **asynchronous** api testing tool for RESTful APIs.
 
+Here is the [github repo](https://github.com/calloc134/raxtest).
+
 ## Acknowledgements
 
 Raxtest relies on the following open source projects: