From b93fae94756413325e1452146e6bbf6b537ffb7d Mon Sep 17 00:00:00 2001 From: debugtalk Date: Fri, 3 Jan 2020 17:45:00 +0800 Subject: [PATCH] doc: add examples in json schema --- docs/CHANGELOG.md | 5 +- httprunner/loader/schemas/api.schema.json | 24 ++ httprunner/loader/schemas/common.schema.json | 245 +++++++++++++----- .../loader/schemas/testcase.schema.v2.json | 55 ++++ .../loader/schemas/testsuite.schema.v1.json | 4 +- .../loader/schemas/testsuite.schema.v2.json | 42 +++ 6 files changed, 308 insertions(+), 67 deletions(-) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index fb86c893..34e37da3 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -2,11 +2,14 @@ ## 2.5.4 (2020-01-03) +**Added** + +- doc: add examples in json schema + **Fixed** - fix #835: UnicodeDecodeError when loading json schema files - ## 2.5.3 (2020-01-03) **Fixed** diff --git a/httprunner/loader/schemas/api.schema.json b/httprunner/loader/schemas/api.schema.json index cd046fbc..f59b924f 100644 --- a/httprunner/loader/schemas/api.schema.json +++ b/httprunner/loader/schemas/api.schema.json @@ -31,5 +31,29 @@ "required": [ "name", "request" + ], + "examples": [ + { + "name": "demo api", + "variables": { + "var1": "value1", + "var2": "value2" + }, + "request": { + "url": "/api/path/$var1", + "method": "POST", + "headers": { + "Content-Type": "application/json" + }, + "json": { + "key": "$var2" + }, + "validate": [ + { + "eq": ["status_code", 200] + } + ] + } + } ] } \ No newline at end of file diff --git a/httprunner/loader/schemas/common.schema.json b/httprunner/loader/schemas/common.schema.json index ce5a33e4..67a33961 100644 --- a/httprunner/loader/schemas/common.schema.json +++ b/httprunner/loader/schemas/common.schema.json @@ -4,17 +4,29 @@ "definitions": { "name": { "description": "used as api/teststep/testcase/testsuite identification", - "type": "string" + "type": "string", + "examples": [ + "basic test for httpbin" + ] }, "base_url": { "description": "The base_url will be used with relative URI", - "type": "string" + "type": "string", + "examples": [ + "https://httpbin.org" + ] }, "variables": { "description": "define variables for api/teststep/testcase/testsuite", "oneOf": [ { - "type": "object" + "type": "object", + "examples": [ + { + "var1": "value1", + "var2": "value2" + } + ] }, { "type": "array", @@ -22,18 +34,69 @@ "type": "object", "maxProperties": 1, "minProperties": 1 - } + }, + "examples": [ + [ + { + "var1": "value1" + }, + { + "var2": "value2" + } + ] + ] }, { "type": "string", "pattern": "^\\$.*", "examples": [ + "$prepared_variables", "${prepare_variables()}", "${prepare_variables($a, $b)}" ] } ] }, + "verify": { + "description": "whether to verify the server’s TLS certificate", + "type": "boolean", + "examples": [ + true, + false + ] + }, + "hook": { + "description": "used to define setup_hooks/teardown_hooks for api/teststep/testcase", + "type": "array", + "items": { + "oneOf": [ + { + "description": "call setup/teardown hook functions, return nothing", + "type": "string", + "examples": [ + [ + "${sleep(2)}", + "${hook_print(setup)}", + "${modify_request_json($request, android)}", + "${alter_response($response)}" + ] + ] + }, + { + "description": "call setup/teardown hook functions, return value and assign to variable", + "type": "object", + "examples": [ + { + "total": "${sum_two(1, 5)}" + }, + { + "filed_name": "get_decoded_response_field($response)" + } + ] + } + ] + } + }, "config": { "description": "used in testcase/testsuite to configure common fields", "type": "object", @@ -54,28 +117,11 @@ "$ref": "#/definitions/hook" }, "verify": { - "description": "configure verify for current testcase/testsuite", - "oneOf": [ - { - "description": "whether we verify the server’s TLS certificate", - "type": "boolean" - }, - { - "description": "path to a CA bundle to use", - "type": "string" - } - ] + "$ref": "#/definitions/verify" } }, "required": ["name"] }, - "hook": { - "description": "used to define setup_hooks/teardown_hooks for api/teststep/testcase", - "type": "array", - "items": { - "type": "string" - } - }, "request": { "description": "used to define a api request. properties is the same as python package `requests.request`", "type": "object", @@ -95,25 +141,49 @@ }, "url": { "description": "request url, may be absolute or relative URI", - "type": "string" + "type": "string", + "examples": [ + "http://httpbin.org/get?a=1&b=2", + "/get?a=1&b=2", + "get?a=1&b=2" + ] }, "params": { "description": "query string for request url", - "type": "object" + "type": "object", + "examples": [ + { + "a": 1, + "b": 2 + } + ] }, "data": { "anyOf": [ { "description": "request body in json format", - "type": "object" + "type": "object", + "examples": [ + { + "a": 1, + "b": 2 + } + ] }, { - "description": "request body in application/x-www-form-urlencoded format, e.g. a=1&b=2", - "type": "string" + "description": "request body in application/x-www-form-urlencoded format", + "type": "string", + "examples": [ + "a=1&b=2" + ] }, { - "description": "request body in string format, e.g. '${prepare_data($a, $b)}'", - "type": "string" + "description": "request body prepared with function, or reference a variable", + "type": "string", + "examples": [ + "$post_data", + "${prepare_data($a, $b)}" + ] } ] }, @@ -124,7 +194,7 @@ "type": "object" }, { - "description": "request body in string format, e.g. '${prepare_json($a, $b)}'", + "description": "request body prepared with function, or reference a variable", "type": "string", "pattern": "^\\$.*", "examples": [ @@ -136,7 +206,26 @@ }, "headers": { "description": "request headers", - "type": "object" + "oneOf": [ + { + "description": "request headers in json format", + "type": "object", + "examples": [ + { + "User-Agent": "python-requests/2.18.4", + "Content-Type": "application/json" + } + ] + }, + { + "description": "request headers prepared with function, or reference a variable", + "type": "string", + "examples": [ + "$prepared_headers", + "${prepare_headers($a, $b)}" + ] + } + ] }, "cookies": { "description": "request cookies", @@ -152,7 +241,10 @@ }, "timeout": { "description": "How many seconds to wait for the server to send data before giving up", - "type": "number" + "type": "number", + "examples": [ + 120 + ] }, "allow_redirects": { "description": "Enable/disable GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD redirection. Defaults to True", @@ -164,41 +256,21 @@ }, "verify": { "description": "configure verify for current api/teststep", - "oneOf": [ - { - "description": "whether we verify the server’s TLS certificate", - "type": "boolean" - }, - { - "description": "path to a CA bundle to use", - "type": "string" - } - ] + "$ref": "#/definitions/verify" }, "stream": { "description": "if False, the response content will be immediately downloaded.", "type": "boolean" }, - "cert": { - "oneOf": [ - { - "description": "path to ssl client cert file (.pem)", - "type": "string" - }, - { - "description": "('cert', 'key') pair", - "type": "array", - "maxItems": 2, - "minItems": 2, - "items": { - "type": "string" - } - } - ] - }, "upload": { "description": "upload files", - "type": "object" + "type": "object", + "examples": [ + { + "file": "data/file_to_upload", + "md5": "123" + } + ] } }, "required": [ @@ -216,7 +288,16 @@ "description": "extraction rule for session variable, maybe in jsonpath/regex/jmespath", "type": "string" } - } + }, + "examples": [ + { + "code__by_jsonpath": "$.code", + "item_id__by_jsonpath": "$..items.*.id", + "var_name__by_regex": "\"LB[\\d]*(.*)RB[\\d]*\"", + "content_type": "headers.content-type", + "first_name": "content.person.name.first_name" + } + ] }, { "type": "array", @@ -230,7 +311,24 @@ }, "minProperties": 1, "maxProperties": 1 - } + }, + "examples": [ + { + "code__by_jsonpath": "$.code" + }, + { + "item_id__by_jsonpath": "$..items.*.id" + }, + { + "var_name__by_regex": "\"LB[\\d]*(.*)RB[\\d]*\"" + }, + { + "content_type": "headers.content-type" + }, + { + "first_name": "content.person.name.first_name" + } + ] } ] }, @@ -253,7 +351,18 @@ "description": "expected value" } }, - "required": ["check", "expect"] + "required": ["check", "expect"], + "examples": [ + { + "check": "body.code", + "comparator": "gt", + "expect": 0 + }, + { + "check": "status_code", + "expect": 200 + } + ] }, { "type": "object", @@ -264,7 +373,15 @@ "minItems": 2, "maxItems": 2 } - } + }, + "examples": [ + { + "eq": ["status_code", 200] + }, + { + "gt": ["body.code", 0] + } + ] } ] } diff --git a/httprunner/loader/schemas/testcase.schema.v2.json b/httprunner/loader/schemas/testcase.schema.v2.json index 75009f3d..665b1419 100644 --- a/httprunner/loader/schemas/testcase.schema.v2.json +++ b/httprunner/loader/schemas/testcase.schema.v2.json @@ -125,5 +125,60 @@ "required": [ "config", "teststeps" + ], + "examples": [ + { + "config": { + "name": "testcase name" + }, + "teststeps": [ + { + "name": "api 1", + "api": "/path/to/api1" + }, + { + "name": "api 2", + "api": "/path/to/api2" + } + ] + }, + { + "config": { + "name": "demo testcase", + "variables": { + "device_sn": "ABC", + "username": "${ENV(USERNAME)}", + "password": "${ENV(PASSWORD)}" + }, + "base_url": "http://127.0.0.1:5000" + }, + "teststeps": [ + { + "name": "demo step 1", + "api": "path/to/api1.yml", + "variables": { + "user_agent": "iOS/10.3", + "device_sn": "$device_sn" + }, + "extract": [ + { + "token": "content.token" + } + ], + "validate": [ + { + "eq": ["status_code", 200] + } + ] + }, + { + "name": "demo step 2", + "api": "path/to/api2.yml", + "variables": { + "token": "$token" + } + } + ] + } ] } \ No newline at end of file diff --git a/httprunner/loader/schemas/testsuite.schema.v1.json b/httprunner/loader/schemas/testsuite.schema.v1.json index af9fda01..85a8a72a 100644 --- a/httprunner/loader/schemas/testsuite.schema.v1.json +++ b/httprunner/loader/schemas/testsuite.schema.v1.json @@ -53,11 +53,11 @@ }, "testcases": { "testcase 1": { - "name": "xxx", + "name": "testcase 1", "testcase": "/path/to/testcase1" }, "testcase 2": { - "name": "xxx", + "name": "testcase 2", "testcase": "/path/to/testcase2" } } diff --git a/httprunner/loader/schemas/testsuite.schema.v2.json b/httprunner/loader/schemas/testsuite.schema.v2.json index f4dd1f5a..5eb7eff2 100644 --- a/httprunner/loader/schemas/testsuite.schema.v2.json +++ b/httprunner/loader/schemas/testsuite.schema.v2.json @@ -42,5 +42,47 @@ "required": [ "config", "testcases" + ], + "examples": [ + { + "config": { + "name": "testsuite name" + }, + "testcases": [ + { + "name": "testcase 1", + "testcase": "/path/to/testcase1" + }, + { + "name": "testcase 2", + "testcase": "/path/to/testcase2" + } + ] + }, + { + "config": { + "name": "demo testsuite", + "variables": { + "device_sn": "XYZ" + }, + "base_url": "http://127.0.0.1:5000" + }, + "testcases": [ + { + "name": "call demo_testcase with data 1", + "testcase": "path/to/demo_testcase.yml", + "variables": { + "device_sn": "$device_sn" + } + }, + { + "name": "call demo_testcase with data 2", + "testcase": "path/to/demo_testcase.yml", + "variables": { + "device_sn": "$device_sn" + } + } + ] + } ] } \ No newline at end of file