diff --git a/README.md b/README.md index 18bc6ba..f7a6761 100644 --- 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 index 514e957..0f69054 100644 --- a/docs/docs/overview.md +++ b/docs/docs/overview.md @@ -6,8 +6,6 @@ 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 @@ -15,5 +13,8 @@ It is designed to be simple but powerful. - **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 new file mode 100644 index 0000000..a60e9e4 --- /dev/null +++ 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` \ No newline at end of file diff --git a/docs/docs/raxtest/guide/output.md b/docs/docs/raxtest/guide/output.md new file mode 100644 index 0000000..00f6c70 --- /dev/null +++ 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` \ No newline at end of file diff --git a/docs/docs/raxtest/guide/required_options.md b/docs/docs/raxtest/guide/required_options.md index b38189e..eb39e31 100644 --- 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 index 53205f1..0ceed4f 100644 --- 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: