# freeDxecra

**Repository Path**: yanggan2021/free-dxecra

## Basic Information

- **Project Name**: freeDxecra
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-14
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FreeExecura

FreeExecura 是一个面向 Linux 开发板的 **可恢复测试编排器**，解决以下问题：

- 按 `Tdddd-案例名` 和 `Rdd-步骤名` 自动发现并排序测试用例。
- 区分稳定的 `cases/` 用例库和每次提交后复制出来的执行工作区。
- 每执行一步就写入 JSON/CSV 状态文件，重启后自动续跑。
- 通过显式依赖声明控制步骤前置条件。
- 自动检测板型（`tl3588`、`ok3568` 等），板型用例优先于通用用例。

详细设计见 [docs/架构设计.md](docs/架构设计.md)。

---

## 安装

### 目标板安装（推荐）

```bash
./install.sh   # 在目标板上以 root 执行
```

安装路径：`/opt/freeexecura/`，运行时数据：`/root/freeexecura/`，自动注册 systemd 服务。

### 仓库内使用（开发）

```bash
./freeexecura list      # 使用仓库包装器
# 或
PYTHONPATH=src python3 -m freeexecura list
```

---

## 用例库结构

```text
cases/
├── common/                         # 通用用例，所有板型通用
│   └── T1000-softhsmv2-pkcs11-smoke/
├── tl3588/                         # TL3588 专属用例
│   ├── _tl3588.sh                  # 板型辅助函数
│   └── T2000-docker-busybox-smoke/
└── ok3568/                         # OK3568 专属用例（远程执行）
    ├── _ok3568.sh
    └── T4000-remote-uname-smoke/
```

- 每个用例目录 `Tdddd-name/` 包含若干步骤文件 `Rdd-name.{sh,py}`。
- `Tdddd` 和 `Rdd` 决定全局执行顺序，数值越小越先执行。
- 支持符号链接和递归子目录分组。
- 板型用例库中的 `T` 号与 common 中不重叠时不需要去重；若重叠，板型版本优先。

---

## 快速上手

### 1. 查看当前板型和可用用例

```bash
freeexecura board          # 查看检测到的板型信息
freeexecura list           # 列出库中所有默认分组的用例
freeexecura list --group tl3588 --steps   # 显示步骤详情
```

示例输出：
```
board=tl3588
library=/opt/freeexecura/cases
groups=tl3588,common
cases=63
  T2100-ethernet-interface-inventory      tl3588  1 step
  T2150-default-gateway-ping              tl3588  1 step
  T1000-softhsmv2-pkcs11-smoke            common  3 steps
  ...
```

### 2. 查看某个用例的步骤

```bash
freeexecura show T2100
freeexecura show T2700-reboot-bootid-check
```

### 3. 提交用例到执行工作区

```bash
# 提交全部默认分组（board + common）
freeexecura submit

# 只提交指定分组
freeexecura submit --group tl3588

# 只提交指定用例（按 T 号）
freeexecura submit T2100
freeexecura submit T2100 T2150 T2700 T2710

# 提交全名也可以
freeexecura submit T2100-ethernet-interface-inventory
```

### 4. 查看执行工作区的内容

```bash
freeexecura queue           # 列出已提交的用例
freeexecura queue --steps   # 同时显示步骤
freeexecura queue --done    # 同时显示已完成并归档的用例
freeexecura dequeue T2100   # 从当前执行中移除某个用例
freeexecura clear           # 清空当前 queue 中剩余待执行内容
```

### 5. 启动执行队列

```bash
freeexecura start           # 唤醒后台 systemd 服务开始执行
```

freeexecura 服务会按顺序执行所有 `pending` 步骤，每步完成后更新状态文件。

### 6. 查看状态和生成报告

```bash
freeexecura status              # 摘要统计
freeexecura status --verbose    # 每步详情
freeexecura report              # 生成 Markdown 报告
```

### 7. 重置并重新执行

```bash
freeexecura restart             # 重新提交并启动（从头开始）
```

### 8. 从当前 queue 移除用例

```bash
freeexecura dequeue T2100
freeexecura dequeue T2100 T2150
freeexecura clear
```

- `dequeue` 会将指定用例中尚未开始的 `pending` 步骤标记为跳过。
- 如果该用例当前有步骤正在执行，当前步骤不会被强杀，只会清掉它后续尚未执行的步骤。
- `clear` 会对当前 queue 中所有未终态用例执行同样的操作。

---

## 前台单步执行

不依赖服务，直接前台运行：

```bash
# 运行一个步骤（T号/步骤号）
freeexecura start T2100/R00
```

---

## 暂停、继续、停止

```bash
freeexecura pause     # 暂停（当前步骤完成后生效）
freeexecura resume    # 继续
freeexecura stop      # 停止
```

---

## 重启续跑

FreeExecura 专为开发板设计，支持：

1. 任意步骤失败后，服务继续执行下一步（除非依赖声明为 `on_unmet=fail`）。
2. 断电/重启后，systemd 服务自动重启，加载状态文件，从中断处继续。
3. 包含 `reboot` 的测试用例（如 `T2700`、`T2710`）使用 marker 文件双阶段模式自动续跑。

---

## 历史运行记录

```bash
freeexecura runs           # 查看最近 10 次运行
freeexecura runs --limit 5
```

---

## 导入用例到库

```bash
freeexecura add /path/to/T0300-my-case --group tl3588
freeexecura add /path/to/T0300-my-case --group common --link  # 符号链接导入
```

---

## step.json 编写规范

`Rdd-name.step.json` 是步骤的可选元数据文件。推荐把“执行顺序”和“真实脚本文件名”分离开：

1. 如果脚本本身就适合叫 `R00-prepare.sh` 这种名字，可以只放物理脚本文件。
2. 如果脚本名不想带顺序号，或者想复用公共脚本，推荐使用 json-only 步骤：只写 `R00-name.step.json`，再通过 `script` 字段指定真实脚本。

最常用的完整写法如下：

```json
{
    "script": "bootenv.sh",
    "before_step": "capture-system-info.sh",
    "after_step": "capture-system-info.sh",
    "depends_on": [
        "R00",
        {"ref": "T0500/R10", "require_status": "success", "on_unmet": "skip"}
    ],
    "failure_policy": "continue-suite",
    "timeout_sec": 300,
    "retry_count": 1,
    "env": {
        "MY_FLAG": "value"
    }
}
```

### 字段说明

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `script` | 当前步骤文件本身 | 要执行的真实脚本。支持本地脚本、公共脚本、相对路径、绝对路径 |
| `before_step` | 无 | 步骤执行前运行的 hook |
| `after_step` | 无 | 步骤执行后运行的 hook |
| `depends_on` | `[前一步]` | 依赖列表。可写 `"R02"` 或完整对象 |
| `failure_policy` | `continue-suite` | 本步失败后的处理：`continue-suite` / `stop-case` / `stop-run` |
| `timeout_sec` | 无限制 | 超时秒数 |
| `retry_count` | `0` | 失败后最多重试次数 |
| `env` | `{}` | 只注入当前步骤的环境变量 |

### 脚本解析规则

`script`、`before_step`、`after_step` 统一遵循以下规则：

1. 绝对路径：直接使用。
2. 简单文件名，例如 `reboot.sh`：按 `case 目录 -> share/ -> suite 根目录` 的顺序查找。
3. 含 `/`、`./`、`../` 的相对路径：按 `当前 step.json 所在目录 -> case 目录 -> share/ -> suite 根目录` 的顺序查找。

这意味着常见场景都可以写成最简单的名字，不需要再写 `../../../share/...` 这种脆弱路径。

### 设计建议

- 板级 bootargs/boot env 修改逻辑必须留在 case 目录里，不要放进 `share/`。
- 通用 reboot 逻辑应该放进 `share/reboot.sh`，由本地脚本按名字直接调用。
- 如果只是为了把步骤名和脚本名解耦，优先用 json-only 步骤。
- 如果要给多个 case 复用同一个 hook，优先放进 `share/`，然后直接写 `capture-env.sh`、`capture-system-info.sh` 这种简单名字。
- `share/bootenv-template.sh` 只作为模板示例，不建议直接拿来当板级产线脚本。

### 推荐示例

示例 1：最简单的物理步骤文件，不需要 `step.json`

```text
T0000-demo/
└── R00-prepare.sh
```

示例 2：板级 bootenv 保持在 case 目录，reboot 走公共脚本

```text
T1030-cyclictest-rt-stress/
├── R00-bootenv.step.json
└── bootenv.sh
```

```json
{
    "script": "bootenv.sh",
    "env": {
        "FREEEXECURA_BOOTENV_MODE": "bootargs",
        "FREEEXECURA_BOOTARGS": "console=ttyFIQ0 root=/dev/mmcblk0p5 rw rootwait"
    }
}
```

`bootenv.sh` 里执行 `fw_setenv ...` 后，直接调用 `reboot.sh` 即可，不需要写路径。

示例 3：直接调用公共 hook

```json
{
    "before_step": "capture-system-info.sh",
    "after_step": "capture-env.sh"
}
```

示例 4：带跨 case 依赖的显式声明

```json
{
    "depends_on": [
        "R05",
        {"ref": "T0500/R10", "require_status": "success", "on_unmet": "fail"}
    ],
    "failure_policy": "stop-case",
    "timeout_sec": 120
}
```

### 不推荐写法

- `"script": "../../../share/reboot.sh"`：可读性差，迁移到运行快照后也更难理解。
- 把 `fw_setenv bootargs ...` 之类的板级逻辑直接做成 `share/` 公共脚本。
- 在 `step.json` 里塞过多板级分支逻辑；复杂差异应放回本地脚本。

---

## 板型检测

`freeexecura` 启动时自动检测当前板型：

1. 优先读取 `FREEEXECURA_BOARD_GROUP` 环境变量。
2. 读取 `~/freeexecura/config.json` 中的 `board_group`。
3. 从 `hostname`、`/proc/device-tree/model` 等推断。

检测到板型后，`default_groups` 自动变为 `[board, common]`，板型用例优先。

```bash
freeexecura board     # 查看检测结果
FREEEXECURA_BOARD_GROUP=tl3588 freeexecura list   # 手动指定板型
```

---

## 运行时目录

```text
~/freeexecura/
├── config.json
└── work/
    ├── current -> executions/<run-id>/   # 当前执行
    └── executions/
        └── <run-id>/
            ├── meta.json
            ├── share/            # 公共脚本与辅助函数副本
            ├── suite/            # 用例快照
            ├── done/             # 已完成用例归档（每个用例一个目录）
            └── state/
                ├── current-run.json
                ├── current-run.csv
                └── reports/
                    └── <run-id>/
                        ├── run-context.json
                        └── cases/
                            └── <case-id>-<case-name>/
                                ├── logs/
                                └── work/
```

`done/<timestamp>-<case_id>/logs/` 下的日志文件保存步骤脚本的原始 stdout/stderr 输出，不再额外写入包装头信息。
执行过程中同样会实时镜像输出到 `/dev/console`，便于在系统默认控制台或串口终端实时查看进展。

---

## 环境变量参考

| 变量 | 说明 |
|------|------|
| `FREEEXECURA_HOME` | 覆盖运行时根目录（默认 `~/freeexecura`）|
| `FREEEXECURA_LIBRARY_DIR` | 覆盖用例库路径 |
| `FREEEXECURA_BOARD_GROUP` | 覆盖板型分组 |

---

## 命令速查

| 命令 | 说明 |
|------|------|
| `board` | 查看检测到的板型信息 |
| `list [--group G] [--steps] [--verbose]` | 列出库中用例 |
| `show CASE [--group G]` | 查看某用例的步骤（只读）|
| `queue [--steps] [--done]` | 查看当前执行工作区的用例（含可选已完成归档） |
| `dequeue CASE [CASE...]` | 从当前执行中移除指定用例的剩余待执行步骤 |
| `clear` | 清空当前 queue 中剩余待执行内容 |
| `submit [CASE...] [--group G]` | 提交用例到执行工作区 |
| `start` | 启动执行队列 |
| `restart [--group G]` | 重置并重新提交执行 |
| `pause / resume / stop` | 控制执行状态 |
| `status [--verbose]` | 查看当前运行状态 |
| `report [--format] [--output]` | 生成报告 |
| `runs [--limit N]` | 历史运行列表 |
| `add SOURCE --group G` | 导入用例到库 |
| `start T0000/R00` | 前台执行单个步骤 |