# Flutter星图

**Repository Path**: app_36/flutter-star-chart

## Basic Information

- **Project Name**: Flutter星图
- **Description**: Flutter星图是一套面向 Flutter 组件工程的智能测试与交付系统，支持自然语言驱动测试、自动回归与可行性交付报告。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-20
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Flutter星图

`flutter_components` 是一套面向 Flutter 项目的自动化测试与交付系统，核心目标是：
**让你用更少命令跑通回归、拿到可读结论，并能在 CI 持续门禁。**

## 小白 1 分钟上手

### 1) 先做环境健康检查（不连设备）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
bash tool/testing/run_local_verification.sh
```

这条命令会依次执行：
- `flutter pub get`
- 示例单测
- fixture 报告生成
- 注释规范检查
- `dart analyze tool/testing`
- `tool/gui_pyqt5` 的 Python 单测

### 2) 再跑 1 轮真实 smoke（Android 示例）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
dart run tool/testing/run_agentic_tests.dart   --platform android   --suite smoke   --runs 1   --device-id emulator-5554   --instruction "smoke home navigation and refresh"   --with-video
```

### 3) 看结果在哪

- 运行产物：`test-artifacts/<date>/run_xxx/`
  - 核心文件：`result.json`
  - 轨迹文件：`operation_trace.jsonl`
  - 证据：`screenshots/`、`videos/`、`logs/`、`steps.json`
- 报告目录：`delivery/`
  - `test-feasibility-report.md`
  - `stability-trend.md`
  - `test-report.html`

## 核心功能与亮点

- **Agentic 自动化测试**：按 `smoke/full/explore` 执行，支持多轮稳定性样本。
- **结构化执行轨迹**：`operation_trace.jsonl` + 事件类型 + 过滤搜索 + 对比新增失败。
- **真实截图证据链**：优先使用真实截图，缺失时从本轮视频抽帧；不再使用灰色占位图误导。
- **可视化工作台（PyQt5）**「**Flutter 测试工作台**」：一键执行、轨迹回放、历史对比、HTML/JSON 导出；完整说明见 [`tool/gui_pyqt5/README.md`](tool/gui_pyqt5/README.md)，主界面示意见 [`tool/gui_pyqt5/docs/workbench_main_window.png`](tool/gui_pyqt5/docs/workbench_main_window.png)。
- **CI 门禁友好**：本地命令与 CI 工作流同源，结论口径一致。

## 最常用入口

- 测试工具链说明：[`tool/testing/README.md`](tool/testing/README.md)
- **Test Agent（WebUI / 本地 Ollama 分析）**：[`tool/test_agent/README.md`](tool/test_agent/README.md) — 快捷启动：`bash tool/test_agent/run_webui.sh`（默认 <http://127.0.0.1:8030/>）
- GUI（Flutter 测试工作台）：[`tool/gui_pyqt5/README.md`](tool/gui_pyqt5/README.md) · [界面配图](tool/gui_pyqt5/docs/workbench_main_window.png)
- 自动化测试交付指南：[`doc/zh/content/自动化测试交付指南.md`](doc/zh/content/自动化测试交付指南.md)
- Flutter App 接入指南：[`doc/zh/content/FlutterApp自动化测试功能接入指南.md`](doc/zh/content/FlutterApp自动化测试功能接入指南.md)

## 快捷命令

以下示例中的目录请替换为你本机项目根（本仓库常见为 `/Users/hujintao/Desktop/python/ai/flutter_components`）。

### 启动 Test Agent（可选）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
bash tool/test_agent/run_webui.sh
```

### 启动 GUI（Flutter 测试工作台）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
bash tool/gui_pyqt5/run_gui.sh
```

启动后若已有 `test-artifacts/**/result.json`，工作台会自动加载最近一份；界面分区与配图说明见 [`tool/gui_pyqt5/README.md`](tool/gui_pyqt5/README.md)。

### 生成交付报告（基于某次 result.json）

```bash
cd "/Users/hujintao/Desktop/python/ai/flutter_components"
dart run tool/testing/generate_delivery_reports.dart test-artifacts/<date>/run_<id>/result.json
```

## 设备准备（Android）

- 启动模拟器：`flutter emulators --launch <emulator_id>`
- 确认在线：`flutter devices`
- `--device-id` 请填 `flutter devices` 里看到的设备序列号（如 `emulator-5554`）

## 说明

- 本 README 保留“小白可用”主路径；深度排障、字段说明、CI 细节请看上面的专项文档。