diff --git a/docs/images/charles-capture-example-postman-echo.png b/docs/images/charles-capture-example-postman-echo.png new file mode 100644 index 00000000..c69f794c Binary files /dev/null and b/docs/images/charles-capture-example-postman-echo.png differ diff --git a/docs/images/charles-export-session.png b/docs/images/charles-export-session.png new file mode 100644 index 00000000..34588539 Binary files /dev/null and b/docs/images/charles-export-session.png differ diff --git a/docs/images/charles-save-har.png b/docs/images/charles-save-har.png new file mode 100644 index 00000000..f9e990a2 Binary files /dev/null and b/docs/images/charles-save-har.png differ diff --git a/docs/user/gen_tests.md b/docs/user/gen_tests.md new file mode 100644 index 00000000..8925fc9a --- /dev/null +++ b/docs/user/gen_tests.md @@ -0,0 +1,327 @@ +# Record & Generate testcase + +## capture HTTP request and response + +Before we write testcases, we should know the details of the API. It is a good choice to use a web debugging proxy tool like `Charles Proxy` to capture the HTTP traffic. + +For example, the image below illustrates post form data to [`postman-echo.com`][postman-echo]. + +![](/images/charles-capture-example-postman-echo.png) + +## export sessions to HAR file + +Then we can select captured request & response and export sessions to HTTP archive (.har) file. + +![](/images/charles-export-session.png) + +![](/images/charles-save-har.png) + +## generate testcase with har2case + +When you get HAR file, you can use builtin command `har2case` to convert it to HttpRunner testcase. + +### help + +```text +$ har2case -h +usage: har2case har2case [-h] [-2y] [-2j] [--filter FILTER] + [--exclude EXCLUDE] + [har_source_file] + +positional arguments: + har_source_file Specify HAR source file + +optional arguments: + -h, --help show this help message and exit + -2y, --to-yml, --to-yaml + Convert to YAML format, if not specified, convert to + pytest format by default. + -2j, --to-json Convert to JSON format, if not specified, convert to + pytest format by default. + --filter FILTER Specify filter keyword, only url include filter string + will be converted. + --exclude EXCLUDE Specify exclude keyword, url that includes exclude + string will be ignored, multiple keywords can be + joined with '|' +``` + +### generate testcase (pytest) + +Since HttpRunner `3.0.7`, `har2case` will convert HAR file to pytest by default, and it is strongly recommended to write and maintain testcases in pytest format instead of former `YAML/JSON` format. + +```text +$ har2case har/postman-echo-post-form.har +2020-06-15 15:08:01.187 | INFO | httprunner.ext.har2case.core:gen_testcase:332 - Start to generate testcase from har/postman-echo-post-form.har +2020-06-15 15:08:01.187 | INFO | httprunner.ext.har2case.core:_make_testcase:323 - Extract info from HAR file and prepare for testcase. +2020-06-15 15:08:01.191 | INFO | httprunner.loader:load_dot_env_file:130 - Loading environment variables from /Users/debugtalk/Desktop/demo/.env +2020-06-15 15:08:01.191 | DEBUG | httprunner.utils:set_os_environ:32 - Set OS environment variable: USERNAME +2020-06-15 15:08:01.191 | DEBUG | httprunner.utils:set_os_environ:32 - Set OS environment variable: PASSWORD +2020-06-15 15:08:01.193 | INFO | httprunner.make:make_testcase:310 - start to make testcase: /Users/debugtalk/Desktop/demo/har/postman-echo-post-form.har +2020-06-15 15:08:01.193 | INFO | httprunner.make:make_testcase:383 - generated testcase: /Users/debugtalk/Desktop/demo/har/postman_echo_post_form_test.py +2020-06-15 15:08:01.194 | INFO | httprunner.make:format_pytest_with_black:147 - format pytest cases with black ... +reformatted /Users/debugtalk/Desktop/demo/har/postman_echo_post_form_test.py +All done! ✨ 🍰 ✨ +1 file reformatted. +2020-06-15 15:08:01.469 | INFO | httprunner.ext.har2case.core:gen_testcase:353 - generated testcase: /Users/debugtalk/Desktop/demo/har/postman_echo_post_form_test.py +``` + +The generated pytest file is a standard Python file shown as below. + +```python +# NOTE: Generated By HttpRunner v3.0.12 +# FROM: har/postman-echo-post-form.har + +from httprunner import HttpRunner, Config, Step, RunRequest, RunTestCase + + +class TestCasePostmanEchoPostForm(HttpRunner): + config = Config("testcase description").verify(False) + + teststeps = [ + Step( + RunRequest("/get") + .get("https://postman-echo.com/get") + .with_params(**{"foo1": "bar1", "foo2": "bar2"}) + .with_headers( + **{ + "User-Agent": "PostmanRuntime/7.24.1", + "Accept": "*/*", + "Cache-Control": "no-cache", + "Postman-Token": "6606343b-10e5-4165-a89f-6c301b762ce0", + "Host": "postman-echo.com", + "Accept-Encoding": "gzip, deflate, br", + "Connection": "keep-alive", + "Cookie": "sails.sid=s%3AQG_EVeNRw8k1xxZ6v_SG401VTpmJDSRu.fTAGx3JnZUT7S0c2%2FrD9cxUhQemIsm78nifYZYHpPCU", + } + ) + .with_cookies( + **{ + "sails.sid": "s%3AQG_EVeNRw8k1xxZ6v_SG401VTpmJDSRu.fTAGx3JnZUT7S0c2%2FrD9cxUhQemIsm78nifYZYHpPCU" + } + ) + .validate() + .assert_equal("status_code", 200) + .assert_equal('headers."Content-Type"', "application/json; charset=utf-8") + .assert_equal( + "body.url", "https://postman-echo.com/get?foo1=bar1&foo2=bar2" + ) + ), + Step( + RunRequest("/post") + .post("https://postman-echo.com/post") + .with_headers( + **{ + "User-Agent": "PostmanRuntime/7.24.1", + "Accept": "*/*", + "Cache-Control": "no-cache", + "Postman-Token": "3e408e9d-25ca-4b31-b04b-7f4898a8cd49", + "Host": "postman-echo.com", + "Accept-Encoding": "gzip, deflate, br", + "Connection": "keep-alive", + "Content-Type": "application/x-www-form-urlencoded", + "Content-Length": "19", + "Cookie": "sails.sid=s%3AQG_EVeNRw8k1xxZ6v_SG401VTpmJDSRu.fTAGx3JnZUT7S0c2%2FrD9cxUhQemIsm78nifYZYHpPCU", + } + ) + .with_cookies( + **{ + "sails.sid": "s%3AQG_EVeNRw8k1xxZ6v_SG401VTpmJDSRu.fTAGx3JnZUT7S0c2%2FrD9cxUhQemIsm78nifYZYHpPCU" + } + ) + .with_data({"foo1": "bar1", "foo2": "bar2"}) + .validate() + .assert_equal("status_code", 200) + .assert_equal('headers."Content-Type"', "application/json; charset=utf-8") + .assert_equal("body.data", "") + .assert_equal("body.url", "https://postman-echo.com/post") + ), + ] + + +if __name__ == "__main__": + TestCasePostmanEchoPostForm().test_start() +``` + +And it can be run with `hrun` command or the native `pytest` command. In fact, `hrun` is only a wrapper of `pytest`, thus the effect is basically the same. + +```text +$ hrun har/postman_echo_post_form_test.py +2020-06-15 15:23:03.502 | INFO | httprunner.loader:load_dot_env_file:130 - Loading environment variables from /Users/debugtalk/Desktop/demo/.env +2020-06-15 15:23:03.502 | DEBUG | httprunner.utils:set_os_environ:32 - Set OS environment variable: USERNAME +2020-06-15 15:23:03.502 | DEBUG | httprunner.utils:set_os_environ:32 - Set OS environment variable: PASSWORD +2020-06-15 15:23:03.503 | INFO | httprunner.make:format_pytest_with_black:147 - format pytest cases with black ... +All done! ✨ 🍰 ✨ +1 file left unchanged. +2020-06-15 15:23:03.662 | INFO | httprunner.cli:main_run:56 - start to run tests with pytest. HttpRunner version: 3.0.12 +====================================================================== test session starts ====================================================================== +platform darwin -- Python 3.7.5, pytest-5.4.2, py-1.8.1, pluggy-0.13.1 +rootdir: /Users/debugtalk/Desktop/demo +plugins: metadata-1.9.0, allure-pytest-2.8.16, html-2.1.1 +collected 1 item + +har/postman_echo_post_form_test.py . [100%] + +======================================================================= 1 passed in 2.60s ======================================================================= +``` + +```text +$ pytest har/postman_echo_post_form_test.py +====================================================================== test session starts ====================================================================== +platform darwin -- Python 3.7.5, pytest-5.4.2, py-1.8.1, pluggy-0.13.1 +rootdir: /Users/debugtalk/Desktop/demo +plugins: metadata-1.9.0, allure-pytest-2.8.16, html-2.1.1 +collected 1 item + +har/postman_echo_post_form_test.py . [100%] + +================================================================= 1 passed, 1 warning in 4.11s ================================================================== +``` + +### generate testcase (YAML/JSON) + +Of course, you can also generate former `YAML/JSON` testcase format. Just add `-2y/--to-yml` or `-2j/--to-json` argument to `har2case`. + +```text +$ har2case har/postman-echo-post-form.har -2j +2020-06-15 15:32:02.955 | INFO | httprunner.ext.har2case.core:gen_testcase:332 - Start to generate testcase from har/postman-echo-post-form.har +2020-06-15 15:32:02.955 | INFO | httprunner.ext.har2case.core:_make_testcase:323 - Extract info from HAR file and prepare for testcase. +2020-06-15 15:32:02.958 | INFO | httprunner.ext.har2case.utils:dump_json:122 - dump testcase to JSON format. +2020-06-15 15:32:02.959 | INFO | httprunner.ext.har2case.utils:dump_json:131 - Generate JSON testcase successfully: har/postman-echo-post-form.json +2020-06-15 15:32:02.959 | INFO | httprunner.ext.har2case.core:gen_testcase:353 - generated testcase: har/postman-echo-post-form.json +``` + +```json +{ + "config": { + "name": "testcase description", + "variables": {}, + "verify": false + }, + "teststeps": [ + { + "name": "/get", + "request": { + "url": "https://postman-echo.com/get", + "params": { + "foo1": "bar1", + "foo2": "bar2" + }, + "method": "GET", + "cookies": { + "sails.sid": "s%3AQG_EVeNRw8k1xxZ6v_SG401VTpmJDSRu.fTAGx3JnZUT7S0c2%2FrD9cxUhQemIsm78nifYZYHpPCU" + }, + "headers": { + "User-Agent": "PostmanRuntime/7.24.1", + "Accept": "*/*", + "Cache-Control": "no-cache", + "Postman-Token": "6606343b-10e5-4165-a89f-6c301b762ce0", + "Host": "postman-echo.com", + "Accept-Encoding": "gzip, deflate, br", + "Connection": "keep-alive", + "Cookie": "sails.sid=s%3AQG_EVeNRw8k1xxZ6v_SG401VTpmJDSRu.fTAGx3JnZUT7S0c2%2FrD9cxUhQemIsm78nifYZYHpPCU" + } + }, + "validate": [ + { + "eq": [ + "status_code", + 200 + ] + }, + { + "eq": [ + "headers.Content-Type", + "application/json; charset=utf-8" + ] + }, + { + "eq": [ + "body.url", + "https://postman-echo.com/get?foo1=bar1&foo2=bar2" + ] + } + ] + }, + { + "name": "/post", + "request": { + "url": "https://postman-echo.com/post", + "method": "POST", + "cookies": { + "sails.sid": "s%3AQG_EVeNRw8k1xxZ6v_SG401VTpmJDSRu.fTAGx3JnZUT7S0c2%2FrD9cxUhQemIsm78nifYZYHpPCU" + }, + "headers": { + "User-Agent": "PostmanRuntime/7.24.1", + "Accept": "*/*", + "Cache-Control": "no-cache", + "Postman-Token": "3e408e9d-25ca-4b31-b04b-7f4898a8cd49", + "Host": "postman-echo.com", + "Accept-Encoding": "gzip, deflate, br", + "Connection": "keep-alive", + "Content-Type": "application/x-www-form-urlencoded", + "Content-Length": "19", + "Cookie": "sails.sid=s%3AQG_EVeNRw8k1xxZ6v_SG401VTpmJDSRu.fTAGx3JnZUT7S0c2%2FrD9cxUhQemIsm78nifYZYHpPCU" + }, + "data": { + "foo1": "bar1", + "foo2": "bar2" + } + }, + "validate": [ + { + "eq": [ + "status_code", + 200 + ] + }, + { + "eq": [ + "headers.Content-Type", + "application/json; charset=utf-8" + ] + }, + { + "eq": [ + "body.data", + "" + ] + }, + { + "eq": [ + "body.url", + "https://postman-echo.com/post" + ] + } + ] + } + ] +} +``` + +The `YAML/JSON` testcase has the same info with `pytest` testcase, and you can run `YAML/JSON` testcase with `hrun` command. + +```text +$ hrun har/postman-echo-post-form.json +2020-06-15 15:37:15.621 | INFO | httprunner.loader:load_dot_env_file:130 - Loading environment variables from /Users/debugtalk/Desktop/demo/.env +2020-06-15 15:37:15.622 | DEBUG | httprunner.utils:set_os_environ:32 - Set OS environment variable: USERNAME +2020-06-15 15:37:15.622 | DEBUG | httprunner.utils:set_os_environ:32 - Set OS environment variable: PASSWORD +2020-06-15 15:37:15.623 | INFO | httprunner.make:make_testcase:310 - start to make testcase: /Users/debugtalk/Desktop/demo/har/postman-echo-post-form.json +2020-06-15 15:37:15.625 | INFO | httprunner.make:make_testcase:383 - generated testcase: /Users/debugtalk/Desktop/demo/har/postman_echo_post_form_test.py +2020-06-15 15:37:15.625 | INFO | httprunner.make:format_pytest_with_black:147 - format pytest cases with black ... +reformatted /Users/debugtalk/Desktop/demo/har/postman_echo_post_form_test.py +All done! ✨ 🍰 ✨ +1 file reformatted, 1 file left unchanged. +2020-06-15 15:37:15.962 | INFO | httprunner.cli:main_run:56 - start to run tests with pytest. HttpRunner version: 3.0.12 +====================================================================== test session starts ====================================================================== +platform darwin -- Python 3.7.5, pytest-5.4.2, py-1.8.1, pluggy-0.13.1 +rootdir: /Users/debugtalk/Desktop/demo +plugins: metadata-1.9.0, allure-pytest-2.8.16, html-2.1.1 +collected 1 item + +har/postman_echo_post_form_test.py . [100%] + +======================================================================= 1 passed in 2.03s ======================================================================= +``` + + +[postman-echo]: https://docs.postman-echo.com/?version=latest diff --git a/mkdocs.yml b/mkdocs.yml index 26a065f7..f79b579e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -55,5 +55,6 @@ nav: - Installation: installation.md - User Guide: - Scaffold: user/scaffold.md + - Record & Generate testcase: user/gen_tests.md - Sponsors: sponsors.md - CHANGELOG: CHANGELOG.md