120 lines
4.9 KiB
Markdown
120 lines
4.9 KiB
Markdown
# skill-template 测试说明（企业数字员工技能）
|
||
|
||
本目录提供面向 **ERP / TMS / WMS / 船司 / 报关 / 邮件 / 浏览器 / LLM / RPA** 等外联场景的**分层测试骨架**：默认仅内存与本地 SQLite；**真实 API / 真实 RPA** 必须通过环境变量显式授权，且仅以 ``*.sample`` 或复制后的文件提供范式。
|
||
|
||
复制为新技能后，请保留隔离数据根与 profile 策略，再按域扩展用例。
|
||
|
||
---
|
||
|
||
## 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`` 复制件中实现。
|