symtest-cli 1.3.1__tar.gz → 1.3.2__tar.gz

{symtest_cli-1.3.1/src/symtest_cli.egg-info → symtest_cli-1.3.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: symtest-cli
-Version: 1.3.1
+Version: 1.3.2
 Summary: Regression testing for CLI applications, with multi-step workflows and numerical file comparison.
-Home-page: https://github.com/ozil111/cli-test-framework
+Home-page: https://github.com/ozil111/symtest-cli
 Author: Xiaotong Wang
 Author-email: xiaotongwang98@gmail.com
-Project-URL: Documentation, https://github.com/ozil111/cli-test-framework/blob/main/docs/user_manual.md
-Project-URL: Source, https://github.com/ozil111/cli-test-framework
-Project-URL: Tracker, https://github.com/ozil111/cli-test-framework/issues
+Project-URL: Documentation, https://github.com/ozil111/symtest-cli/blob/main/docs/user_manual.md
+Project-URL: Source, https://github.com/ozil111/symtest-cli
+Project-URL: Tracker, https://github.com/ozil111/symtest-cli/issues
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -298,6 +298,9 @@ requirement for using the framework.
 - [User manual](docs/user_manual_en.md)
 - [Design document](docs/design_en.md)
 - [Plugin examples](examples/plugins/README.md)
+- [AI Skill template](examples/skill/) — import framework knowledge into AI coding
+  assistants so they can author test cases, acceptance criteria,
+  and TDD workflows directly
 
 ## Development
 

{symtest_cli-1.3.1 → symtest_cli-1.3.2}/README.md

@@ -249,6 +249,9 @@ requirement for using the framework.
 - [User manual](docs/user_manual_en.md)
 - [Design document](docs/design_en.md)
 - [Plugin examples](examples/plugins/README.md)
+- [AI Skill template](examples/skill/) — import framework knowledge into AI coding
+  assistants so they can author test cases, acceptance criteria,
+  and TDD workflows directly
 
 ## Development
 

{symtest_cli-1.3.1 → symtest_cli-1.3.2}/docs/design.md

@@ -259,7 +259,7 @@ load_test_cases() → _apply_test_case_filter() → setup_manager.setup_all()
 支持三种过滤方式（可组合）：
 - `test_case_filter`：按名称精确匹配
 - `test_case_tag_filter`：按 tags 匹配（交集逻辑）
-- `last_failed`：从 `.cli-test/last_run.json` 读取上次失败的用例名
+- `last_failed`：从 `.symtest/last_run.json` 读取上次失败的用例名
 
 **xfail 机制 `_apply_xfail_status()`**：
 
@@ -318,6 +318,8 @@ class TestCase:
     expected_failure: bool = False
     xfail_reason: str = ""
     xfail_quiet: bool = False
+    depends_on: List[str] = field(default_factory=list)
+    env: Dict[str, str] = field(default_factory=dict)
 ```
 
 两种模式：
@@ -328,6 +330,8 @@ class TestCase:
 - `tags`：标签过滤
 - `retry_count`：失败重试次数
 - `expected_failure` / `xfail_reason` / `xfail_quiet`：预期失败标记
+- `depends_on`：用例级依赖声明，支持 DAG 拓扑调度
+- `env`：case 级环境变量，注入该 case（序列模式为所有 step）的子进程，优先级高于 `setup` 与调度器注入
 
 ### 4.3 Assertions
 
@@ -426,7 +430,7 @@ class PathResolver:
 `--last-failed` 状态存储模块（`core/last_run_store.py`）：
 
 ```python
-# 存储位置: <workspace>/.cli-test/last_run.json
+# 存储位置: <workspace>/.symtest/last_run.json
 # {
 #   "case_name": {"status": "passed"},
 #   ...
@@ -448,8 +452,8 @@ class PathResolver:
 `--resume` 断点续跑模块（`core/sequence_state.py`）：
 
 ```python
-# 状态文件: <workspace>/.cli-test/sequence_state/<case_name>.json
-# 输出缓存: <workspace>/.cli-test/sequence_state/cache/<case_name>.step<N>.log
+# 状态文件: <workspace>/.symtest/sequence_state/<case_name>.json
+# 输出缓存: <workspace>/.symtest/sequence_state/cache/<case_name>.step<N>.log
 ```
 
 核心接口：
@@ -684,7 +688,7 @@ CaseManagerApp (Textual App)
   _update_history()          # 回归检测 + 更新 .symtest
        │
        ▼
-  _save_last_run()           # 写入 .cli-test/last_run.json
+  _save_last_run()           # 写入 .symtest/last_run.json
        │
        ▼
   setup_manager.teardown_all() # 逆序清理
@@ -699,14 +703,14 @@ CaseManagerApp (Textual App)
 ParallelConfigRunner.run_tests()
        │
        ▼
-  LPT 排序 (历史 avg_duration 优先，fallback 到 estimated_time 降序)
+  拓扑 LPT 排序 (depends_on 约束 + 历史 avg_duration 降序)
        │
        ▼
   _assign_relative_cpu_cores()  # 按权重比例分配 CPU 核心
        │
        ▼
   ┌──────────────────────────────────────┐
-  │  ThreadPoolExecutor.map():           │
+  │  DAG 调度 / 或直接并行 (无依赖时)    │
   │    AtomicSemaphore.acquire(cores)    │
   │    注入 OMP/MKL/NPROC 环境变量       │
   │    execute_single_test_case()        │
@@ -715,7 +719,45 @@ ParallelConfigRunner.run_tests()
   └──────────────────────────────────────┘
 ```
 
-### 7.3 文件比较流
+### 7.3 DAG 依赖调度流
+
+当 `TestCase.depends_on` 非空时，并行 runner 自动切换为 DAG 拓扑调度：
+
+```
+ParallelRunner.run_tests()
+       │
+       ▼
+  has_deps? ──No──► _run_tests_flat() (fast path)
+       │
+      Yes
+       ▼
+  _run_dag()
+       │
+       ├── 构建 dependents 邻接表 + in_degree 入度表
+       ├── 入度=0 的用例 → 就绪队列 → executor.submit()
+       │
+       ▼
+  ┌────────────────────────────────────────┐
+  │  as_completed() 循环:                   │
+  │    完成一个 future                       │
+  │    │                                     │
+  │    ├── passed/xfailed → 后继入度-1      │
+  │    │   └── 入度=0 → submit(后继)        │
+  │    │                                     │
+  │    └── failed/xpassed → cascade_skip    │
+  │        └── BFS 标记下游全部 skipped      │
+  └────────────────────────────────────────┘
+```
+
+**调度语义**：
+- 依赖"满足" = 状态为 `passed` 或 `xfailed`
+- 依赖"不满足" = 状态为 `failed` 或 `xpassed` → 下游全部 skip
+- `skipped` 不计入 `failed` 计数，报告中单独列出
+- 级联 skip：若 B 被 skip，则依赖 B 的 C 也自动 skip
+
+**顺序 runner**（`BaseRunner.run_tests()`）同样支持拓扑排序：`_topological_order()` 使用 Kahn 算法生成拓扑序列，按序执行，依赖失败时自动跳过下游。
+
+### 7.4 文件比较流
 
 ```
 symtest compare file1 file2 [options]
@@ -737,7 +779,7 @@ symtest compare file1 file2 [options]
   format_result(result, --output-format)  # text / json / html
 ```
 
-### 7.4 --resume 断点续跑流
+### 7.5 --resume 断点续跑流
 
 ```
 序列测试用例执行
@@ -781,14 +823,16 @@ symtest compare file1 file2 [options]
 | LPT 调度策略 | 长任务先启动，减少尾延迟；优先使用 `.symtest` 历史数据 |
 | 累计平均更新历史 | 直觉简单，随运行次数增多单次异常自然稀释 |
 | 回归检测在更新前执行 | 先与旧均值比较再更新，确保对比的是"历史基线" |
-| `.symtest` 隐藏文件 + `.cli-test/` 目录 | 不干扰用户目录视图，JSON 格式便于调试；状态文件统一管理 |
+| `.symtest/` 目录 | 不干扰用户目录视图，JSON 格式便于调试；状态文件统一管理 |
 | 环境变量注入 | 科学计算求解器常忽略 Python 级线程控制 |
+| case 级 env 通过 subprocess 注入 | 不改进程全局 `os.environ`，进程隔离、并行线程安全；优先级 `os.environ` < 调度器 < case env |
 | Comparator 工厂 + 插件发现 | 按文件类型创建比较器，workspace `comparators/` 目录自动发现插件 |
 | subprocess 隔离执行 | 每个 test case 独立子进程，保证测试间互不影响 |
 | xfail 机制 | 支持预期失败的测试（CI 中不阻塞流水线），意外通过时告警 |
 | --last-failed 覆写策略 | 只覆写本次执行的用例状态，避免子集运行时丢失未执行用例的状态 |
 | --resume 纯信任模型 | 不验证 artifact，由用户保证 workspace 未被修改，简化实现 |
 | retry_count 重试机制 | 应对偶发性网络抖动或竞态条件，首次失败后自动重试 |
+| DAG 依赖调度 | 基于 Kahn 拓扑 + 就绪队列，依赖满足后立即提交；依赖失败级联 skip 下游；无依赖时走 fast path 零开销 |
 | --update-baseline | 比较失败时自动将实际输出覆盖 baseline，适合批量更新基准 |
 | next_action_hint 结构化建议 | 失败结果附带下一步操作建议（update_baseline / update_expected / increase_timeout / investigate），便于 AI 消费 |
 | TUI 基于 Textual | 利用成熟的终端 UI 框架，提供交互式用例管理 |

{symtest_cli-1.3.1 → symtest_cli-1.3.2}/docs/design_en.md

@@ -259,7 +259,7 @@ load_test_cases() → _apply_test_case_filter() → setup_manager.setup_all()
 Supports three filter modes (combinable):
 - `test_case_filter`: exact name match
 - `test_case_tag_filter`: tag-based match (intersection logic)
-- `last_failed`: reads previously failed case names from `.cli-test/last_run.json`
+- `last_failed`: reads previously failed case names from `.symtest/last_run.json`
 
 **xfail mechanism `_apply_xfail_status()`**:
 
@@ -318,6 +318,7 @@ class TestCase:
     expected_failure: bool = False
     xfail_reason: str = ""
     xfail_quiet: bool = False
+    depends_on: List[str] = field(default_factory=list)
 ```
 
 Two modes:
@@ -426,7 +427,7 @@ Core interfaces:
 `--last-failed` state storage module (`core/last_run_store.py`):
 
 ```python
-# Storage location: <workspace>/.cli-test/last_run.json
+# Storage location: <workspace>/.symtest/last_run.json
 # {
 #   "case_name": {"status": "passed"},
 #   ...
@@ -448,8 +449,8 @@ Each run **overwrites** the status of executed cases; unexecuted cases retain th
 `--resume` step-level resume module (`core/sequence_state.py`):
 
 ```python
-# State file: <workspace>/.cli-test/sequence_state/<case_name>.json
-# Output cache: <workspace>/.cli-test/sequence_state/cache/<case_name>.step<N>.log
+# State file: <workspace>/.symtest/sequence_state/<case_name>.json
+# Output cache: <workspace>/.symtest/sequence_state/cache/<case_name>.step<N>.log
 ```
 
 Core interfaces:
@@ -684,7 +685,7 @@ Config file (JSON/YAML)
   _update_history()          # Regression detection + update .symtest
        │
        ▼
-  _save_last_run()           # Write .cli-test/last_run.json
+  _save_last_run()           # Write .symtest/last_run.json
        │
        ▼
   setup_manager.teardown_all() # Reverse cleanup
@@ -699,14 +700,14 @@ Config file (JSON/YAML)
 ParallelConfigRunner.run_tests()
        │
        ▼
-  LPT sort (historical avg_duration preferred, fallback to estimated_time desc)
+  Topology-constrained LPT sort (depends_on + historical avg_duration desc)
        │
        ▼
   _assign_relative_cpu_cores()  # Proportional CPU core assignment by weight
        │
        ▼
   ┌──────────────────────────────────────┐
-  │  ThreadPoolExecutor.map():           │
+  │  DAG scheduling / flat (no deps)     │
   │    AtomicSemaphore.acquire(cores)    │
   │    Inject OMP/MKL/NPROC env vars     │
   │    execute_single_test_case()        │
@@ -715,7 +716,47 @@ ParallelConfigRunner.run_tests()
   └──────────────────────────────────────┘
 ```
 
-### 7.3 File Comparison Flow
+### 7.3 DAG Dependency Scheduling Flow
+
+When `TestCase.depends_on` is non-empty, the parallel runner switches to DAG topology scheduling:
+
+```
+ParallelRunner.run_tests()
+       │
+       ▼
+  has_deps? ──No──► _run_tests_flat() (fast path)
+       │
+      Yes
+       ▼
+  _run_dag()
+       │
+       ├── Build dependents adjacency + in_degree table
+       ├── in_degree=0 cases → ready queue → executor.submit()
+       │
+       ▼
+  ┌────────────────────────────────────────┐
+  │  as_completed() loop:                   │
+  │    Complete one future                  │
+  │    │                                     │
+  │    ├── passed/xfailed → decrement       │
+  │    │   successor in-degree              │
+  │    │   └── in_degree=0 → submit()       │
+  │    │                                     │
+  │    └── failed/xpassed → cascade_skip    │
+  │        └── BFS mark all downstream      │
+  │            as skipped                    │
+  └────────────────────────────────────────┘
+```
+
+**Scheduling semantics**:
+- Dependency "satisfied" = status is `passed` or `xfailed`
+- Dependency "unsatisfied" = status is `failed` or `xpassed` → all downstream skipped
+- `skipped` is NOT counted as `failed`; listed separately in reports
+- Cascade skip: if B is skipped, C (which depends on B) is also skipped
+
+**Sequential runner** (`BaseRunner.run_tests()`) also supports topological ordering: `_topological_order()` uses Kahn's algorithm to generate a topological sequence, runs in order, and auto-skips downstream on dependency failure.
+
+### 7.4 File Comparison Flow
 
 ```
 symtest compare file1 file2 [options]
@@ -737,7 +778,7 @@ symtest compare file1 file2 [options]
   format_result(result, --output-format)  # text / json / html
 ```
 
-### 7.4 --resume Checkpoint Flow
+### 7.5 --resume Checkpoint Flow
 
 ```
 Sequence test case execution
@@ -781,7 +822,7 @@ Sequence test case execution
 | LPT scheduling strategy | Long tasks start first, reducing tail latency; prioritizes `.symtest` historical data |
 | Cumulative average history update | Simple and intuitive; single anomalies are naturally diluted over many runs |
 | Regression check before update | Compare against old average first, then update; ensures comparison is against the "historical baseline" |
-| `.symtest` hidden file + `.cli-test/` directory | Non-intrusive to the user's directory view; JSON format for easy debugging; state files centrally managed |
+| `.symtest/` directory | Non-intrusive to the user's directory view; JSON format for easy debugging; state files centrally managed |
 | Environment variable injection | Scientific computing solvers often ignore Python-level thread control |
 | Comparator factory + plugin discovery | Creates comparators by file type; workspace `comparators/` directory for auto-discovered plugins |
 | subprocess isolated execution | Each test case runs in an independent subprocess, ensuring tests don't affect each other |
@@ -789,6 +830,7 @@ Sequence test case execution
 | --last-failed overwrite strategy | Only overwrites status of executed cases; avoids losing state of unexecuted cases during subset runs |
 | --resume pure trust model | No artifact validation; user guarantees workspace is unchanged, simplifying implementation |
 | retry_count retry mechanism | Handles transient network glitches or race conditions; auto-retries on first failure |
+| DAG dependency scheduling | Kahn topology + ready queue; submits dependents immediately once deps are satisfied; cascade-skips downstream on dep failure; zero-overhead fast path when no deps declared |
 | --update-baseline | Automatically overwrites baseline files with actual output on comparison failure; ideal for batch baseline updates |
 | next_action_hint structured suggestions | Failed results include actionable suggestions (update_baseline / update_expected / increase_timeout / investigate), convenient for AI consumption |
 | TUI based on Textual | Leverages a mature terminal UI framework for interactive case management |

{symtest_cli-1.3.1 → symtest_cli-1.3.2}/docs/user_manual.md

@@ -4,6 +4,7 @@
 
 - [安装](#安装)
 - [测试用例定义](#测试用例定义)
+- [Case 级环境变量](#case-级环境变量env)
 - [配置拆分机制](#配置拆分机制)
 - [配置继承](#配置继承)
 - [配置校验](#配置校验)
@@ -159,6 +160,78 @@ test_cases:
 }
 ```
 
+### 测试依赖（depends_on）
+
+当测试用例之间存在先后依赖时（例如 D 需要 A、B、C 先生成数据），通过 `depends_on` 声明依赖关系，框架会自动按 DAG 拓扑顺序调度：
+
+**并行模式**：A、B、C 并行执行，全部通过后 D 才被提交。依赖失败的用例会自动 skip 其下游（级联 skip）。
+
+**顺序模式**：框架按拓扑序重排用例，保证依赖在前的先执行，依赖失败时同样跳过下游。
+
+**JSON 示例**：
+
+```json
+{
+    "test_cases": [
+        { "name": "A", "command": "python", "args": ["gen_a.py"], "expected": {"return_code": 0} },
+        { "name": "B", "command": "python", "args": ["gen_b.py"], "expected": {"return_code": 0} },
+        { "name": "C", "command": "python", "args": ["gen_c.py"], "expected": {"return_code": 0} },
+        {
+            "name": "D", "command": "python", "args": ["merge.py"],
+            "depends_on": ["A", "B", "C"],
+            "expected": {"return_code": 0, "compare_files": [{"file": "output.h5", "type": "hdf5"}]}
+        }
+    ]
+}
+```
+
+**YAML 示例**：
+
+```yaml
+test_cases:
+  - name: A
+    command: python
+    args: ["gen_a.py"]
+    expected: { return_code: 0 }
+
+  - name: B
+    command: python
+    args: ["gen_b.py"]
+    expected: { return_code: 0 }
+
+  - name: C
+    command: python
+    args: ["gen_c.py"]
+    expected: { return_code: 0 }
+
+  - name: D
+    command: python
+    args: ["merge.py"]
+    depends_on: [A, B, C]
+    expected:
+      return_code: 0
+      compare_files:
+        - file: output.h5
+          type: hdf5
+```
+
+**调度语义**：
+
+| 依赖状态 | 下游行为 |
+|---|---|
+| `passed` 或 `xfailed` | 依赖"满足"，下游正常执行 |
+| `failed` 或 `xpassed` | 依赖"不满足"，下游标记为 `skipped`，并级联 skip |
+| 存在循环依赖 | 配置校验阶段报错，禁止运行 |
+
+`skipped` 不计入 `failed` 计数，在报告摘要中单独显示 `Skipped: N`。
+
+**约束**：
+- 依赖名称必须在同配置文件的 `test_cases` 中存在
+- 不允许自依赖（`depends_on: ["self"]`）
+- 不允许循环依赖（A → B → A）
+- 与 `steps` 模式互不影响——`depends_on` 是用例级概念，`steps` 是用例内步骤级概念
+- 无依赖时走 fast path，调度开销为零
+
 ### 字段说明
 
 | 字段 | 必填 | 说明 |
@@ -174,11 +247,69 @@ test_cases:
 | `expected_failure` | 否 | 标记为预期失败（xfail）。设为 `true` 时，失败计为 XFailed（不影响退出码），意外通过计为 XPassed（视作失败） |
 | `xfail_reason` | 否 | xfail 的原因说明，报告中将展示此文本（如 "Bug #42 尚未修复"） |
 | `xfail_quiet` | 否 | 设为 `true` 时，xfailed 状态下报告中不输出 Command Output（stdout/stderr 大段输出），仅保留命令、返回码、失败原因等元信息 |
+| `depends_on` | 否 | 依赖的测试用例名称列表（如 `["A", "B"]`）。当前用例必须等待所有依赖用例通过后才执行。依赖失败时自动 skip 当前用例及下游。支持并行和顺序两种 runner |
+| `env` | 否 | case 级环境变量字典（如 `{"UEL_SYSID_SCALE": "1.0"}`），仅在执行该 case（序列模式为所有 step）时注入子进程，见 [Case 级环境变量](#case-级环境变量env) |
 | `expected.return_code` | 否 | 期望返回码 |
 | `expected.output_contains` | 否 | 输出需包含的字符串列表 |
 | `expected.output_matches` | 否 | 输出需匹配的正则表达式（单个字符串） |
 | `expected.compare_files` | 否 | 文件比较断言列表，见下文 |
 
+## Case 级环境变量（env）
+
+通过 case 下与 `name` 同级的 `env` 字段，可为单个用例注入环境变量，仅在该用例（序列模式为所有 step）的子进程内生效，不影响其他用例。
+
+### JSON
+
+```json
+{
+    "name": "UEL 缩放测试",
+    "command": "solver",
+    "args": ["-i", "input.dat"],
+    "env": {
+        "UEL_SYSID_SCALE": "1.0",
+        "OMP_NUM_THREADS": "8"
+    },
+    "expected": { "return_code": 0 }
+}
+```
+
+### YAML
+
+```yaml
+- name: UEL 缩放测试
+  command: solver
+  args: ["-i", "input.dat"]
+  env:
+    UEL_SYSID_SCALE: "1.0"
+  expected: { return_code: 0 }
+```
+
+### 序列模式
+
+`env` 定义在 case 级（与 `steps` 同级），对该 case 的**所有 step** 生效：
+
+```json
+{
+    "name": "多步骤+环境变量",
+    "env": { "UEL_SYSID_SCALE": "1.0" },
+    "steps": [
+        { "command": "python", "args": ["./step1.py"], "expected": { "return_code": 0 } },
+        { "command": "python", "args": ["./step2.py"], "expected": { "return_code": 0 } }
+    ]
+}
+```
+
+### 语义
+
+| 决策点 | 行为 |
+|---|---|
+| 生效方式 | 通过子进程 `env` 注入，不修改进程全局 `os.environ`，天然进程隔离、线程安全 |
+| 优先级 | `os.environ`（含 `setup.environment_variables`）< 调度器注入（`OMP/MKL/NPROC`）< **case `env`（最高）**，即 case env 可覆盖调度器的 `OMP_NUM_THREADS` |
+| 作用范围 | 仅当前 case，不污染其他 case（区别于全局 `setup.environment_variables`） |
+| 占位符 | 自动支持，`"env": {"SCALE": "{scale}"}` 会被 `variables`/`--var` 替换 |
+| 继承（extends） | 自动支持，`env` 为 dict，深合并、子类覆盖父类同名 key |
+| 值类型 | 字符串；数字/布尔在解析时自动 `str()` 化 |
+
 ### 文件比较断言（compare_files）
 
 在 `expected` 中通过 `compare_files` 可声明一条或多条文件比较规则，框架会在命令执行后自动用对应的比较器对比实际产出文件与基线文件。所有比较通过才算用例通过，可与 `return_code`、`output_contains` 等断言共存。
@@ -702,7 +833,7 @@ symtest run test_cases.json --error-analysis
 **xfail 语义**：标记为 `expected_failure` 的用例如果失败（`xfailed`），是预期行为，**不会**被 `--last-failed` 选中重跑。但如果 xfail 标记的用例意外通过（`xpassed`），则被视为真正失败，**会**被选中。
 
 **工作原理**：
-- 每次运行结束后，框架在 `<workspace>/.cli-test/last_run.json` 中记录每个用例的状态
+- 每次运行结束后，框架在 `<workspace>/.symtest/last_run.json` 中记录每个用例的状态
 - 记录采用**覆盖式更新**：本次跑到的用例用新结果覆盖旧结果，没跑到的保留原状态
 - 这意味着修好的 case 在下一次显示中不再是"failed"
 - 如果文件不存在（首次运行），`--last-failed` 会提示并正常运行全部用例
@@ -725,7 +856,7 @@ symtest run config.json
 `--resume` 针对**顺序步骤测试（sequence）**，跳过上次运行中已通过的步骤，直接从失败步骤继续执行。适合耗时长的多步骤用例——例如有限元分析中 step 1-3 通过了（各耗时几十秒甚至分钟），只有 step 4 的断言失败，`--resume` 可以跳过 1-3、只重跑 step 4。
 
 **工作原理**：
-- 每个步骤通过后，框架在 `<workspace>/.cli-test/sequence_state/<case_name>.json` 中记录步骤状态，并将输出缓存到 `cache/` 子目录
+- 每个步骤通过后，框架在 `<workspace>/.symtest/sequence_state/<case_name>.json` 中记录步骤状态，并将输出缓存到 `cache/` 子目录
 - 下次 `--resume` 时，计算配置哈希（所有步骤的 command/args/expected/timeout/retry_count 及 case 级 expected 的 SHA256）与已保存状态比对
 - 哈希匹配 → 跳过已通过的步骤，从缓存重建 `combined_output`（确保 case 级 `expected` 断言能正常执行）
 - 用例全部通过 → 自动删除状态文件和缓存，避免残留影响后续运行

{symtest_cli-1.3.1 → symtest_cli-1.3.2}/docs/user_manual_en.md

@@ -4,6 +4,7 @@
 
 - [Installation](#installation)
 - [Test Case Definition](#test-case-definition)
+- [Case-Level Environment Variables](#case-level-environment-variables-env)
 - [Configuration Splitting](#configuration-splitting)
 - [Configuration Inheritance](#configuration-inheritance)
 - [Configuration Validation](#configuration-validation)
@@ -159,6 +160,78 @@ When xfailed case output is extremely verbose (e.g., hundreds of lines of solver
 }
 ```
 
+### Test Dependencies (depends_on)
+
+When test cases have ordering dependencies (e.g., D requires A, B, and C to generate data first), declare them via `depends_on`. The framework automatically schedules execution in DAG topological order:
+
+**Parallel mode**: A, B, and C run concurrently. D is submitted only after all three pass. If a dependency fails, its downstream cases are auto-skipped (cascade skip).
+
+**Sequential mode**: The framework reorders cases topologically, ensuring dependencies run first. Downstream cases are skipped on dependency failure.
+
+**JSON example**:
+
+```json
+{
+    "test_cases": [
+        { "name": "A", "command": "python", "args": ["gen_a.py"], "expected": {"return_code": 0} },
+        { "name": "B", "command": "python", "args": ["gen_b.py"], "expected": {"return_code": 0} },
+        { "name": "C", "command": "python", "args": ["gen_c.py"], "expected": {"return_code": 0} },
+        {
+            "name": "D", "command": "python", "args": ["merge.py"],
+            "depends_on": ["A", "B", "C"],
+            "expected": {"return_code": 0, "compare_files": [{"file": "output.h5", "type": "hdf5"}]}
+        }
+    ]
+}
+```
+
+**YAML example**:
+
+```yaml
+test_cases:
+  - name: A
+    command: python
+    args: ["gen_a.py"]
+    expected: { return_code: 0 }
+
+  - name: B
+    command: python
+    args: ["gen_b.py"]
+    expected: { return_code: 0 }
+
+  - name: C
+    command: python
+    args: ["gen_c.py"]
+    expected: { return_code: 0 }
+
+  - name: D
+    command: python
+    args: ["merge.py"]
+    depends_on: [A, B, C]
+    expected:
+      return_code: 0
+      compare_files:
+        - file: output.h5
+          type: hdf5
+```
+
+**Scheduling semantics**:
+
+| Dependency Status | Downstream Behavior |
+|---|---|
+| `passed` or `xfailed` | Dependency "satisfied", downstream runs normally |
+| `failed` or `xpassed` | Dependency "unsatisfied", downstream marked `skipped` with cascade skip |
+| Circular dependency | Configuration validation error, execution blocked |
+
+`skipped` is NOT counted as `failed`; shown separately as `Skipped: N` in the report summary.
+
+**Constraints**:
+- Dependency names must exist in the same config file's `test_cases`
+- Self-dependency is not allowed (`depends_on: ["self"]`)
+- Circular dependencies are not allowed (A → B → A)
+- `depends_on` and `steps` are independent—`depends_on` is a case-level concept, `steps` is an intra-case step-level concept
+- Zero-overhead fast path when no dependencies are declared
+
 ### Field Descriptions
 
 | Field | Required | Description |
@@ -174,6 +247,8 @@ When xfailed case output is extremely verbose (e.g., hundreds of lines of solver
 | `expected_failure` | No | Mark as expected failure (xfail). When `true`, failure is counted as XFailed (no exit code impact); unexpected pass is counted as XPassed (treated as failure) |
 | `xfail_reason` | No | Reason text for xfail, displayed in the report (e.g., "Bug #42 not yet fixed") |
 | `xfail_quiet` | No | When `true`, suppress Command Output (stdout/stderr) for xfailed cases in the report; only command, return code, and failure reason metadata retained |
+| `depends_on` | No | List of test case names this case depends on (e.g., `["A", "B"]`). The case will wait until all dependencies pass before executing. On dependency failure, the case and its downstream are auto-skipped. Works with both parallel and sequential runners |
+| `env` | No | Case-level environment variable mapping (e.g. `{"UEL_SYSID_SCALE": "1.0"}`), injected into the subprocess only when this case runs (all steps in sequence mode). See [Case-Level Environment Variables](#case-level-environment-variables-env) |
 | `expected.return_code` | No | Expected return code |
 | `expected.output_contains` | No | List of strings the output must contain |
 | `expected.output_matches` | No | Regex pattern the output must match (single string) |
@@ -216,6 +291,62 @@ Fields for each comparison rule:
 }
 ```
 
+## Case-Level Environment Variables (env)
+
+Use the `env` field (same level as `name`) to inject environment variables into a single case's subprocess. The variables apply only to that case (all steps in sequence mode) and do not affect other cases.
+
+### JSON
+
+```json
+{
+    "name": "UEL scale test",
+    "command": "solver",
+    "args": ["-i", "input.dat"],
+    "env": {
+        "UEL_SYSID_SCALE": "1.0",
+        "OMP_NUM_THREADS": "8"
+    },
+    "expected": { "return_code": 0 }
+}
+```
+
+### YAML
+
+```yaml
+- name: UEL scale test
+  command: solver
+  args: ["-i", "input.dat"]
+  env:
+    UEL_SYSID_SCALE: "1.0"
+  expected: { return_code: 0 }
+```
+
+### Sequence Mode
+
+`env` is defined at the case level (same level as `steps`) and applies to **all steps** of that case:
+
+```json
+{
+    "name": "multi-step with env",
+    "env": { "UEL_SYSID_SCALE": "1.0" },
+    "steps": [
+        { "command": "python", "args": ["./step1.py"], "expected": { "return_code": 0 } },
+        { "command": "python", "args": ["./step2.py"], "expected": { "return_code": 0 } }
+    ]
+}
+```
+
+### Semantics
+
+| Aspect | Behavior |
+|---|---|
+| Injection mechanism | Injected via subprocess `env`, never mutates the global `os.environ`; process-isolated and thread-safe |
+| Precedence | `os.environ` (incl. `setup.environment_variables`) < scheduler-injected (`OMP/MKL/NPROC`) < **case `env` (highest)** — case env can override `OMP_NUM_THREADS` |
+| Scope | Current case only, no cross-case pollution (unlike global `setup.environment_variables`) |
+| Placeholders | Auto-supported; `"env": {"SCALE": "{scale}"}` is substituted via `variables`/`--var` |
+| Inheritance (extends) | Auto-supported; `env` is a dict, deep-merged with child keys overriding parent |
+| Value type | Strings; numeric/boolean values are coerced with `str()` at parse time |
+
 ## Configuration Splitting
 
 When a test project grows to dozens or even hundreds of test cases, a single config file becomes hard to maintain. The configuration splitting mechanism lets you break a large file into multiple sub-files by module/feature and assemble them via `import` references, which are merged at load time automatically.
@@ -702,7 +833,7 @@ symtest run test_cases.json --error-analysis
 **xfail semantics**: Cases marked `expected_failure` that fail (`xfailed`) are _expected behavior_ and are **not** selected by `--last-failed` for rerun. However, if an xfail-marked case unexpectedly passes (`xpassed`), it is treated as a true failure and **is** selected.
 
 **How it works**:
-- After each run, the framework records each case's status in `<workspace>/.cli-test/last_run.json`
+- After each run, the framework records each case's status in `<workspace>/.symtest/last_run.json`
 - Recording uses **overwrite-update**: cases run this time get new results overwriting old ones; un-run cases retain their previous status
 - This means a fixed case won't show as "failed" in the next display
 - If the file doesn't exist (first run), `--last-failed` warns and runs all cases normally
@@ -725,7 +856,7 @@ symtest run config.json
 `--resume` is for **sequential step tests (sequence)**. It skips steps that passed in the previous run and continues directly from the failed step. Ideal for long-running multi-step cases — for example, in an FEM analysis where steps 1-3 passed (each taking tens of seconds or minutes), only step 4's assertion failed. `--resume` skips 1-3 and reruns only step 4.
 
 **How it works**:
-- After each step passes, the framework records step status in `<workspace>/.cli-test/sequence_state/<case_name>.json` and caches output to the `cache/` subdirectory
+- After each step passes, the framework records step status in `<workspace>/.symtest/sequence_state/<case_name>.json` and caches output to the `cache/` subdirectory
 - On the next `--resume`, a config hash (SHA256 of every step's command/args/expected/timeout/retry_count plus case-level expected) is computed and compared against saved state
 - Hash match → skip passed steps, rebuild `combined_output` from cache (so case-level `expected` assertions run correctly)
 - All steps pass → state file and cache automatically deleted to avoid stale data affecting subsequent runs