From bf5bc00dcc00422f594b7e5bee003acd6007dc51 Mon Sep 17 00:00:00 2001 From: debugtalk Date: Thu, 31 Aug 2017 15:01:51 +0800 Subject: [PATCH] update docs for debugtalk.py plugin --- README.md | 11 ++++++----- docs/quickstart.md | 16 ++++++---------- examples/quickstart-demo-rev-2.yml | 2 -- examples/quickstart-demo-rev-3.yml | 2 -- 4 files changed, 12 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index ca4b42c2..bc1d2b9f 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@ Take full reuse of Python's existing powerful libraries: [`Requests`][requests], - Inherit all powerful features of [`Requests`][requests], just have fun to handle HTTP in human way. - Define testcases in YAML or JSON format in concise and elegant manner. - Supports `function`/`variable`/`extract`/`validate` mechanisms to create full test scenarios. +- With `debugtalk.py` plugin, module functions can be auto-discovered in recursive upward directories. - Testcases can be run in diverse ways, with single testset, multiple testsets, or entire project folder. - Test report is concise and clear, with detailed log records. See [`PyUnitReport`][PyUnitReport]. - Perfect combination with [Jenkins][Jenkins], running continuous integration test and production environment monitoring. Send mail notification with [`jenkins-mail-py`][jenkins-mail-py]. @@ -38,7 +39,7 @@ To ensure the installation or upgrade is successful, you can execute command `at ```text $ ate -V -ApiTestEngine version: 0.5.4 +ApiTestEngine version: 0.6.0 ``` Execute the command `ate -h` to view command help. @@ -74,7 +75,7 @@ To install mail helper, run this command in your terminal: $ pip install -U git+https://github.com/debugtalk/jenkins-mail-py.git#egg=jenkins-mail-py $ ate -V jenkins-mail-py version: 0.2.5 -ApiTestEngine version: 0.5.4 +ApiTestEngine version: 0.6.0 ``` With [`jenkins-mail-py`][jenkins-mail-py] installed, you can see more optional arguments. @@ -127,13 +128,11 @@ optional arguments: It is recommended to write testcases in `YAML` format. -And here is testset example of typical scenario: get token at the beginning, and each subsequent requests should take the token in the headers. +And here is testset example of typical scenario: get `token` at the beginning, and each subsequent requests should take the `token` in the headers. ```yaml - config: name: "create user testsets." - import_module_functions: - - tests.data.debugtalk variable_binds: - user_agent: 'iOS/10.3' - device_sn: ${gen_random_string(15)} @@ -178,6 +177,8 @@ And here is testset example of typical scenario: get token at the beginning, and - {"check": "content.success", "comparator": "eq", "expected": true} ``` +Function invoke is supported in `YAML/JSON` format testcases, such as `gen_random_string` and `get_sign` above. This mechanism relies on the `debugtak.py` hot plugin, with which we can define functions in `debugtak.py` file, and then functions can be auto discovered and invoked in runtime. + For detailed regulations of writing testcases, you can read the [`QuickStart`][quickstart] documents. ## Run testcases diff --git a/docs/quickstart.md b/docs/quickstart.md index 376e6cae..59f58cd2 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -152,11 +152,11 @@ Let's look back to our test set `quickstart-demo-rev-1.yml`, and we can see the In actual scenarios, each user's `device_sn` is different, so we should parameterize the request parameters, which is also called `parameterization`. In the meanwhile, the `sign` field is calculated with other header fields, thus it may change significantly if any header field changes slightly. -However, the test cases are only `YAML` documents, it is impossible to generate parameters dynamically in such text. Fortunately, we can combine `Python` scripts with `YAML` test cases in `ApiTestEngine`. +However, the test cases are only `YAML` documents, it is impossible to generate parameters dynamically in such text. Fortunately, we can combine `Python` scripts with `YAML/JSON` test cases in `ApiTestEngine`. -To achieve this goal, we can utilize `import_module_functions` and `variable_binds` mechanisms. +To achieve this goal, we can utilize `debugtalk.py` plugin and `variable_binds` mechanisms. -To be specific, we can create a Python file (`examples/utils.py`) and implement the related algorithm in it. Since we want to import this file, so we should put a `__init__.py` in this folder to make it as a Python module. +To be specific, we can create a Python file (`examples/debugtalk.py`) and implement the related algorithm in it. The `debugtalk.py` file can not only be located beside `YAML/JSON` testset file, but also can be in any upward recursive folder. Since we want `debugtalk.py` to be importable, we should put a `__init__.py` in its folder to make it as a Python module. ```python import hashlib @@ -187,8 +187,6 @@ And then, we can revise our demo test case and reference the functions. Suppose ```yaml - test: name: get token - import_module_functions: - - examples.utils variable_binds: - user_agent: 'iOS/10.3' - device_sn: ${gen_random_string(15)} @@ -226,9 +224,9 @@ And then, we can revise our demo test case and reference the functions. Suppose - {"check": "content.success", "comparator": "eq", "expected": true} ``` -In this revised test case, we firstly import module functions in `import_module_functions` block by specifying the Python module path, which is relative to the current working directory. +In this revised test case, `variable reference` and `function invoke` mechanisms are both used. -To make fields like `device_sn` can be used more than once, we also bind values to variables in `variable_binds` block. When we bind variables, we can not only bind exact value to a variable name, but also can call a function and bind the evaluated value to it. +To make fields like `device_sn` can be used more than once, we bind values to variables in `variable_binds` block. When we bind variables, we can not only bind exact value to a variable name, but also can call a function and bind the evaluated value to it. When we want to reference a variable in the test case, we can do this with a escape character `$`. For example, `$user_agent` will not be taken as a normal string, and `ApiTestEngine` will consider it as a variable named `user_agent`, search and return its binding value. @@ -246,8 +244,6 @@ To handle this case, overall `config` block is supported in `ApiTestEngine`. If # examples/quickstart-demo-rev-3.yml - config: name: "smoketest for CRUD users." - import_module_functions: - - examples.utils variable_binds: - device_sn: ${gen_random_string(15)} request: @@ -291,7 +287,7 @@ To handle this case, overall `config` block is supported in `ApiTestEngine`. If - {"check": "content.success", "comparator": "eq", "expected": true} ``` -As you see, we import public `Python` modules and variables in `config` block. Also, we can set `base_url` in `config` block, thereby we can only specify relative path in each API request url. Besides, we can also set common fields in `config` `request`, such as `device_sn` in headers. +As you see, we define variables in `config` block. Also, we can set `base_url` in `config` block, thereby we can specify relative path in each API request url. Besides, we can also set common fields in `config` `request`, such as `device_sn` in headers. Until now, the test cases are finished and each detail is handled properly. diff --git a/examples/quickstart-demo-rev-2.yml b/examples/quickstart-demo-rev-2.yml index 4380e047..100bf942 100644 --- a/examples/quickstart-demo-rev-2.yml +++ b/examples/quickstart-demo-rev-2.yml @@ -1,7 +1,5 @@ - test: name: get token - import_module_functions: - - examples.debugtalk variable_binds: - user_agent: 'iOS/10.3' - device_sn: ${gen_random_string(15)} diff --git a/examples/quickstart-demo-rev-3.yml b/examples/quickstart-demo-rev-3.yml index 3b3f81d0..30064ed5 100644 --- a/examples/quickstart-demo-rev-3.yml +++ b/examples/quickstart-demo-rev-3.yml @@ -1,7 +1,5 @@ - config: name: "smoketest for CRUD users." - import_module_functions: - - examples.debugtalk variable_binds: - device_sn: ${gen_random_string(15)} request: