新增完善测试模板

tests/README.md

@@ -1,8 +1,119 @@
-# tests
+# skill-template 测试说明（企业数字员工技能）
 
-这里放模板复制后的单元测试或最小回归测试。
+本目录提供面向 **ERP / TMS / WMS / 船司 / 报关 / 邮件 / 浏览器 / LLM / RPA** 等外联场景的**分层测试骨架**：默认仅内存与本地 SQLite；**真实 API / 真实 RPA** 必须通过环境变量显式授权，且仅以 ``*.sample`` 或复制后的文件提供范式。
 
-模板仓库本身不强制附带业务测试，但建议新 skill 至少补：
+复制为新技能后，请保留隔离数据根与 profile 策略，再按域扩展用例。
 
-- `health` / `version` 最小冒烟测试
-- 关键 `service` 层函数的单元测试
+---
+
+## 1. 默认必跑（unittest）
+
+在**技能仓库根目录**执行：
+
+```powershell
+$env:PYTHONDONTWRITEBYTECODE = "1"
+python tests/run_tests.py
+python tests/run_tests.py -v
+python tests/run_tests.py cli_smoke
+python tests/run_tests.py test_cli_smoke
+```
+
+### 1.1 收集范围
+
+- ``run_tests.py`` **只**发现 ``tests/`` **根目录**下 ``test_*.py``。
+- **不递归**：``tests/samples/``、``tests/integration/``、``tests/desktop/``（其中文件为 ``*.sample`` 或需 pytest 单独跑）。
+- 启动时把 ``scripts/`` 与 ``tests/`` 加入 ``sys.path``。
+- Windows 下将 **stdout/stderr** 包装为 **UTF-8**。
+
+### 1.2 默认套件覆盖
+
+| 能力 | 文件 |
+|------|------|
+| CLI 冒烟（import ``cli.app.main``） | ``test_cli_smoke.py`` |
+| **subprocess 真实入口** ``python scripts/main.py`` | ``test_entrypoint_subprocess.py`` |
+| 运行路径与 **CLAW_*/JIANGCHANG_*** 隔离 | ``test_runtime_paths.py`` |
+| ``SKILL.md`` slug 与 ``constants.SKILL_SLUG`` | ``test_skill_metadata.py`` |
+| DB / ``publish_logs`` 骨架冒烟 | ``test_db_smoke.py`` |
+| **adapter profile / 外呼授权策略** | ``test_adapter_profile_policy.py`` + ``adapter_test_utils.py``（非 ``test_`` 前缀，不自动当用例收集） |
+
+### 1.3 数据隔离（``_support.IsolatedDataRoot``）
+
+同时设置（进入同一临时目录 / 用户）：
+
+| ``CLAW_DATA_ROOT`` | ``JIANGCHANG_DATA_ROOT`` |
+|--------------------|---------------------------|
+| 同一 ``tempfile.mkdtemp(prefix="skill-test-")`` | 同上 |
+
+| ``CLAW_USER_ID`` | ``JIANGCHANG_USER_ID`` |
+|------------------|-------------------------|
+| ``_test`` | ``_test`` |
+
+退出时四个键均恢复（原不存在则 ``pop``），并删除临时目录。
+
+### 1.4 产物与密钥
+
+- ``tests/.gitignore`` 忽略 ``__pycache__``、``.pytest_cache``、``*.pyc``、``desktop/artifacts/``、``integration/artifacts/``、``.env`` 等。
+- 推荐运行前设置 ``PYTHONDONTWRITEBYTECODE=1`` 减少 ``.pyc``。
+
+---
+
+## 2. 可选：Service / Golden（``tests/samples/*.sample``）
+
+- 展示 **service 契约** 与 **fixture 回归** 写法；**默认不执行**。
+- 启用：复制 ``tests/samples/test_service_contract.py.sample`` 等为 ``tests/test_*.py``（去掉 ``.sample``），按业务修改后再 ``python tests/run_tests.py``。
+- 脱敏样例数据见 ``tests/fixtures/README.md`` 与 ``sample_request.json`` / ``expected_response.json``；profile 结构见 ``adapter_profiles.sample.yaml``。
+
+---
+
+## 3. 可选：Integration（``tests/integration/*.sample``）
+
+- **默认不跑**；文件均为 ``*.py.sample``。
+- 说明与开关见 **`tests/integration/README.md`**。
+- **禁止**在样例中硬编码真实 token、密码、生产 URL；凭证须来自密钥库或受控环境变量。
+
+---
+
+## 4. 可选：Desktop E2E（pytest）
+
+见 **`tests/desktop/README.md`**。示例为 `test_desktop_smoke.py.sample`，需复制为 `test_desktop_smoke.py` 后用 pytest 运行。
+
+---
+
+## 5. 环境变量：测试档位与授权
+
+### 5.1 测试档位（二选一变量名，后者为历史拼写兼容）
+
+- ``OPENCLAW_TEST_TARGET`` 或 ``OPENCLOW_TEST_TARGET``
+
+**合法取值**（非法值将使 ``get_test_target()`` 抛 ``ValueError``）：
+
+| 取值 | 含义 |
+|------|------|
+| ``unit`` | **默认**：单元 / 内存 / mock，不跑仿真与真实外联 |
+| ``mock`` | 与 ``unit`` 类似的安全档位（显式语义） |
+| ``simulator_api`` | 仅允许 **仿真 HTTP** 类集成（如 localhost） |
+| ``simulator_rpa`` | 仅允许 **仿真页面 / 录播 RPA** |
+| ``real_api`` | 真实 API（另需 ``ALLOW_REAL_API=1``） |
+| ``real_rpa`` | 真实 RPA（另需 ``ALLOW_REAL_RPA=1``） |
+
+未设置时等价 ``unit``。
+
+### 5.2 授权开关（显式 ``1``）
+
+| 变量 | 作用 |
+|------|------|
+| ``ALLOW_REAL_API=1`` | 允许 ``real_api`` profile 访问真实 HTTP 通道 |
+| ``ALLOW_REAL_RPA=1`` | 允许 ``real_rpa`` profile 驱动真实浏览器/RPA |
+| ``ALLOW_WRITE_ACTIONS=1`` | 在 ``real_*`` 下允许**写**操作（提交表单、下单等） |
+
+### 5.3 默认安全策略（``adapter_test_utils``）
+
+- 默认 ``unit``：不访问真实 API、不跑真实 RPA、不做写操作、不读取真实密钥、不写真实数据根。
+- ``assert_no_real_network_env()`` 断言默认未误开 ``ALLOW_REAL_*``（用于必跑用例自检）。
+
+---
+
+## 6. 与 content-manager 的关系
+
+- **未**复制 article / media / prompt / NotebookLM 等业务测试。
+- 本骨架面向**通用外联技能**；业务契约请放在各自技能的 ``tests/samples`` / ``tests/integration`` 复制件中实现。