init: move from httprunner/httprunner

httprunner/README.md

@@ -0,0 +1,115 @@
+# 代码阅读指南（python 部分）
+
+## 核心数据结构
+
+HttpRunner 以 `TestCase` 为核心，将任意测试场景抽象为有序步骤的集合。
+
+```py
+class TestCase(BaseModel):
+    config: TConfig
+    teststeps: List[TStep]
+```
+
+针对每种测试步骤，统一继承自 `IStep`，并要求必须至少实现如下 4 个方法；步骤内容统一在 `run` 方法中进行实现。
+
+```py
+class IStep(object):
+
+    def name(self) -> str:
+        raise NotImplementedError
+
+    def type(self) -> str:
+        raise NotImplementedError
+
+    def struct(self) -> TStep:
+        raise NotImplementedError
+
+    def run(self, runner) -> StepData:
+        # runner: HttpRunner
+        raise NotImplementedError
+```
+
+我们只需遵循 `IStep` 的接口定义，即可实现各种类型的测试步骤类型。当前 python 版本已支持的步骤类型包括：
+
+- [request](step_request.py)：发起单次 HTTP 请求
+- [testcase](step_testcase.py)：引用执行其它测试用例文件
+
+基于该机制，我们可以扩展支持新的协议类型，例如 HTTP2/WebSocket/RPC 等；同时也可以支持新的测试类型，例如 UI 自动化。甚至我们还可以在一个测试用例中混合调用多种不同的 Step 类型，例如实现 HTTP/RPC/UI 混合场景。
+
+## 用例编写
+
+## 运行主流程
+
+### 整体控制器 pytest
+
+不同于 golang 版本，python 版本的控制逻辑都基于 `pytest` 的用例发现和执行机制。
+
+- 如果是运行 JSON/YAML 格式的用例，hrp 会将用例转换为 pytest 支持的用例格式
+- 如果是要自行编写 pytest 测试用例，需要遵循 HttpRunner 的格式要求
+
+### pytest 用例格式要求
+
+所有测试用例要求都继承自 `HttpRunner`，然后
+
+结构如下所示：
+
+```py
+class TestCaseRequestWithFunctions(HttpRunner):
+
+    config = (
+        Config("request methods testcase with functions")
+    )
+
+    teststeps = [
+        Step(
+            RunRequest("get with params")...
+        ),
+        Step(
+            RunRequest("post raw text")...
+        ),
+        Step(
+            RunRequest("post form data")...
+        ),
+    ]
+```
+
+完整案例可参考：
+
+- [request_with_functions_test.py](../examples/postman_echo/request_methods/request_with_functions_test.py)：用例中包含了 requests 的情况
+- [request_with_testcase_reference_test.py](../examples/postman_echo/request_methods/request_with_testcase_reference_test.py)：用例中包含了引用其它测试用例的情况
+
+### 用例执行器 SessionRunner
+
+测试用例的具体执行都由 `SessionRunner` 完成，每个 TestCase 对应一个实例，在该实例中除了包含测试用例自身内容外，还会包含测试过程的 session 数据和最终测试结果 summary。
+
+```py
+class SessionRunner(object):
+	config: Config
+    teststeps: List[object]     # list of Step
+    ...
+```
+
+重点关注一个方法：
+
+- test_start：该方法将被 pytest 发现，作为启动执行入口，依次执行所有测试步骤
+
+```go
+def test_start(self, param: Dict = None) -> "SessionRunner":
+    """main entrance, discovered by pytest"""
+    self.__start_at = time.time()
+    try:
+        # run step in sequential order
+        for step in self.teststeps:
+            self.__run_step(step)
+    finally:
+        logger.info(f"generate testcase log: {self.__log_path}")
+
+    self.__duration = time.time() - self.__start_at
+```
+
+在主流程中，SessionRunner 并不需要关注 step 的具体类型，统一都是调用 `step.run(self)`，具体实现逻辑都在对应 step 的 `run` 方法中。
+
+```py
+def run(self, runner: HttpRunner) -> StepData:
+    return self.__step.run(runner)
+```