From 58ac2c4733b4064bfce64de7958c792797cf9543 Mon Sep 17 00:00:00 2001
From: debugtalk <mail@debugtalk.com>
Date: Thu, 30 Jul 2020 13:33:46 +0800
Subject: [PATCH 1/2] docs: add concept of variables priority

---
 docs/user/concepts.md | 72 +++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml            |  1 +
 2 files changed, 73 insertions(+)
 create mode 100644 docs/user/concepts.md

diff --git a/docs/user/concepts.md b/docs/user/concepts.md
new file mode 100644
index 00000000..e74b202d
--- /dev/null
+++ b/docs/user/concepts.md
@@ -0,0 +1,72 @@
+
+## variables priority
+
+There are several different types of `variables`, and the priory can be confusing. The best way to avoid confusion is to use different variable names. However, if you must use the same variable names, you should understand the priority strategy.
+
+### testcase
+
+```yaml
+config:
+    name: xxx
+    variables:              # config variables
+        varA: "configA"
+        varB: "configB"
+        varC: "configC"
+    parameters:             # parameter variables
+        varA: ["paramA1"]
+        varB: ["paramB1"]
+
+teststeps:
+-
+    name: step 1
+    variables:              # step variables
+        varA: "step1A"
+    request:
+        url: /$varA/$varB/$varC # varA="step1A", varB="paramB1", varC="configC"
+        method: GET
+    extract:                # extracted variables
+        varA: body.data.A   # suppose varA="extractVarA"
+        varB: body.data.B   # suppose varB="extractVarB"
+-
+    name: step 2
+    varialbes:
+        varA: "step2A"
+    request:
+        url: /$varA/$varB/$varC # varA="step2A", varB="extractVarB", varC="configC"
+        method: GET
+```
+
+In a testcase, variables priority are in the following order:
+
+- step variables > extracted variables, e.g. step 2, varA="step2A"
+- parameter variables > config variables, e.g. step 1, varB="paramB1"
+- extracted variables > parameter variables > config variables, e.g. step 2, varB="extractVarB"
+- config variables are in the lowest priority, e.g. step 1/2, varC="configC"
+
+### testsuite
+
+```yaml
+config:
+    name: xxx
+    variables:                  # testsuite config variables
+        varA: "configA"
+        varB: "configB"
+        varC: "configC"
+
+testcases:
+-
+    name: case 1
+    variables:                  # testcase variables
+        varA: "case1A"
+    testcase: /path/to/testcase1
+    export: ["varA", "varB"]    # export variables
+-
+    name: case 2
+    varialbes:                  # testcase variables
+        varA: "case2A"
+    testcase: /path/to/testcase2
+```
+
+In a testsuite, variables priority are in the following order:
+
+- testcase variables > export variables > testsuite config variables > referenced testcase config variables
diff --git a/mkdocs.yml b/mkdocs.yml
index 4b2ed4b5..dbab26df 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -54,6 +54,7 @@ nav:
     - Introduction: index.md
     - Installation: installation.md
     - User Guide:
+        - Concepts: user/concepts.md
         - Scaffold: user/scaffold.md
         - Record & Generate testcase: user/gen_tests.md
         - Write Testcase: user/write_testcase.md

From a360c8f2809d90f5c1893fcbdf6c9e2d102ff8b6 Mon Sep 17 00:00:00 2001
From: debugtalk <mail@debugtalk.com>
Date: Thu, 30 Jul 2020 13:45:01 +0800
Subject: [PATCH 2/2] docs: add concept of debugtalk.py

---
 docs/user/concepts.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/docs/user/concepts.md b/docs/user/concepts.md
index e74b202d..a7c32fdd 100644
--- a/docs/user/concepts.md
+++ b/docs/user/concepts.md
@@ -1,4 +1,11 @@
 
+## debugtalk.py
+
+Based on the philosophy of `Convention over configuration`, each project should and could only have one `debugtalk.py` file. This file has multiple functions.
+
+- As the root path anchor of the project, the relative paths in testcase, such as referencing testcases or CSV files, are all based on this root path
+- Store custom python functions, the functions called in the testcase are all defined in this file
+
 ## variables priority
 
 There are several different types of `variables`, and the priory can be confusing. The best way to avoid confusion is to use different variable names. However, if you must use the same variable names, you should understand the priority strategy.