From 4ab0c5f3bc143198a64c23b7b48e2efd7d61129d Mon Sep 17 00:00:00 2001
From: debugtalk <mail@debugtalk.com>
Date: Wed, 23 Aug 2017 12:23:40 +0800
Subject: [PATCH] add docs: extraction-and-validation

---
 docs/extraction-and-validation.md | 50 +++++++++++++++++++++++++++++++
 docs/quickstart.md                |  3 +-
 2 files changed, 52 insertions(+), 1 deletion(-)
 create mode 100644 docs/extraction-and-validation.md

diff --git a/docs/extraction-and-validation.md b/docs/extraction-and-validation.md
new file mode 100644
index 00000000..d76b80a2
--- /dev/null
+++ b/docs/extraction-and-validation.md
@@ -0,0 +1,50 @@
+# Extraction and Validation
+
+Suppose we get the following HTTP response.
+
+```text
+# status code: 200
+
+# response headers
+{
+    "Content-Type": "application/json"
+}
+
+# response body content
+{
+    "success": False,
+    "person": {
+        "name": {
+            "first_name": "Leo",
+            "last_name": "Lee",
+        },
+        "age": 29,
+        "cities": ["Guangzhou", "Shenzhen"]
+    }
+}
+```
+
+In `extract_binds` and `validators`, we can do chain operation to extract data field in HTTP response.
+
+For instance, if we want to get `Content-Type` in response headers, then we can specify `headers.content-type`; if we want to get `first_name` in response content, we can specify `content.person.name.first_name`.
+
+There might be slight difference on list, cos we can use index to locate list item. For example, `Guangzhou` in response content can be specified by `content.person.cities.0`.
+
+```text
+{"resp_status_code": "status_code"},
+{"resp_headers_content_type": "headers.content-type"},
+{"resp_content_body_success": "body.success"},
+{"resp_content_content_success": "content.success"},
+{"resp_content_text_success": "text.success"},
+{"resp_content_person_first_name": "content.person.name.first_name"},
+{"resp_content_cities_1": "content.person.cities.1"}
+```
+
+```yaml
+validators:
+    - {"check": "status_code", "comparator": "eq", "expected": 200}
+    - {"check": "headers.content-type", "expected": "application/json"}
+    - {"check": "headers.content-length", "comparator": "gt", "expected": 40}
+    - {"check": "content.success", "comparator": "eq", "expected": True}
+    - {"check": "content.token", "comparator": "len_eq", "expected": 16}
+```
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 7e240b39..9b626d99 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -327,12 +327,13 @@ Great! The test case runs successfully and generates a `HTML` test report.
 This is just a starting point, see the `advanced guide` for the advanced features.
 
 - templating
-- data extraction and validation
+- [`data extraction and validation`](extraction-and-validation)
 - [`comparator`][comparator]
 
 [requests]: http://docs.python-requests.org/en/master/
 [requests.request]: http://docs.python-requests.org/en/master/api/#requests.request
 [comparator]: docs/comparator.md
+[extraction-and-validation]: docs/extraction-and-validation.md
 [quickstart-demo-rev-0]: examples/quickstart-demo-rev-0.yml
 [quickstart-demo-rev-1]: examples/quickstart-demo-rev-1.yml
 [quickstart-demo-rev-2]: examples/quickstart-demo-rev-2.yml