init

README

@@ -0,0 +1,178 @@
+# OPPO AI 能力自动化测试框架（测试用例部分）
+
+## 1. OPPO测试用例项目简介
+
+本项目旨在为 OPPO 移动设备提供一套全面的 AI 能力自动化测试解决方案。通过模拟真实用户操作，对 AI 社交、AI 办公、AI 学习、AI 影像及 AI 生活等多个核心场景的功能进行端到端验证，确保各项 AI 功能的稳定性与可靠性。
+
+## 2. 项目结构
+
+项目采用分层结构，将核心逻辑、测试用例与配置文件分离，以提高代码的可维护性与扩展性。
+
+```
+oppo/
+├── .well-known/           # 此目录存放与服务器交互的规范文件(由框架自动生成，请勿手动维护。)
+├── .pacakge/              # 此目录存放更为底层的框架封装（勿动！）
+├── assets/                # 所需的测试素材与语料均保存在此目录中(请勿使用git维护此目录)
+├── core/                  # 核心业务逻辑与辅助模块
+│   ├── album.py           # 相册操作封装
+│   ├── local_search.py    # 本地搜索功能封装
+│   ├── sound_recorder.py  # 录音机功能封装
+│   ├── ui_helper.py       # UI 交互辅助工具
+│   ├── xiaobu.py          # 小布助手交互封装
+│   └──...
+├── scenarios/             # 自动化测试用例场景
+│   ├── tc_01_social/      # AI 社交场景
+│   ├── tc_02_office/      # AI 办公场景
+│   ├── tc_03_study/       # AI 学习场景
+│   ├── tc_04_visual/      # AI 影像场景
+│   └── tc_05_daily_life/  # AI 生活场景
+├── conftest.py            # Pytest 配置文件，提供全局 Fixture
+├── pyproject.toml         # 项目配置文件 (PEP 621)，定义项目依赖与元数据
+├── README                 # 项目说明文档
+└── .env                   # 环境变量配置（请勿提交至版本库）
+```
+
+### 2.1. `core` 目录
+
+`core` 目录包含了项目所需的核心功能模块。这些模块提供了对设备原生应用（如相册、录音机）和系统级功能（如UI操作、小布助手）的原子化操作接口，为上层测试用例的编写提供稳定支持。
+
+### 2.2. `scenarios` 目录
+
+`scenarios` 目录存放所有自动化测试用例。用例根据功能领域划分为不同的子目录，每个子目录对应一个二级测试场景。用例文件（`tc_*.py`）的命名遵循统一规范。
+
+
+## 3. 测试场景概览
+
+本项目覆盖了以下五大核心 AI 测试领域：
+
+| 二级场景 | 编号前缀 | 描述 |
+| :--- | :--- | :--- |
+| AI 社交 | `tc_01` | 覆盖通话、短信、社交应用等场景下的 AI 功能。 |
+| AI 办公 | `tc_02` | 覆盖日程管理、会议、文稿处理、全局搜索等办公场景。 |
+| AI 学习 | `tc_03` | 覆盖问答、翻译、AI 教学等学习辅助功能。 |
+| AI 影像 | `tc_04` | 覆盖 AI 拍摄、图片生成与处理、视频处理等影像能力。 |
+| AI 生活 | `tc_05` | 覆盖生活问答、系统操作、出行、健康等日常应用场景。 |
+
+每个场景下的具体测试用例（三级场景）均在对应的 `tc_*.py` 文件中实现。
+
+## 4. 指标收集与发送机制
+
+本项目包含一个完整的指标收集与发送机制，用于记录和传输测试过程中的关键性能指标和测试结果。
+
+### 4.1 设计思想
+
+指标管理器（`metric_manager.py`）的设计目标是提供一个灵活且易于使用的接口，用于收集和发送各种类型的测试指标。指标管理器支持多种指标类型，包括文本、数值、图像和视频。通过`conftest.py`中的`metric` fixture，指标管理器被集成到测试框架中，使得所有测试用例可以方便地使用它。
+
+### 4.2 指标收集
+
+指标管理器提供了以下方法来收集不同类型的指标：
+
+- `add_text_metric(name: str, value: str, label: str | None = None)`: 添加文本类型的指标。
+- `add_number_metric(name: str, value: float, label: str | None = None)`: 添加数值类型的指标。
+- `add_image_metric(name: str, value: Path | str, label: str | None = None)`: 添加图像类型的指标。
+- `add_video_metric(name: str, value: Path | str, label: str | None = None)`: 添加视频类型的指标。
+
+此外，指标管理器还提供了一个`from_dict`方法，用于从字典中批量添加指标。
+
+### 4.3 指标发送
+
+在测试用例执行完成后，指标管理器会自动调用`send`方法，将收集到的所有指标发送到服务器。发送过程由`conftest.py`中的`metric` fixture管理，确保在每个测试用例结束后指标能够及时发送。
+
+### 4.4 使用示例
+
+在测试用例中，可以通过`metric` fixture来使用指标管理器。以下是一个简单的示例：
+
+```python
+import pytest
+
+@pytest.mark.meta(id="TC-0101-01", description="AI社交/语音交流/AI代接/快递")
+def test_tc_0101_01(metric):
+    metric.span(m_type="social", m_id="TC-0101-01", m_iter=1)
+    metric.add_text_metric(name="call_status", value="success", label="通话状态")
+    metric.add_number_metric(name="call_duration", value=120.5, label="通话时长")
+    metric.send()
+```
+
+在这个示例中，测试用例首先调用`span`方法开始一个新的指标收集周期，然后使用`add_text_metric`和`add_number_metric`方法添加文本和数值类型的指标，最后调用`send`方法将指标发送到服务器。
+
+## 5. 开发规范与工具配置
+
+为了确保代码质量和开发规范，项目中使用了`justfile`和`.pre-commit-config.yaml`两个重要配置文件。
+
+### 5.1 `justfile` - 本地开发任务管理
+
+`justfile` 是一个本地开发任务管理工具，类似于 Makefile，但更加简洁和易用。它定义了一系列常用开发任务及其执行命令，可以帮助你快速执行构建、清理、测试等操作。
+
+#### 当前有的主要功能
+
+- **任务分组**：任务按照功能分组，例如构建、测试、清理等。
+- **命令简化**：通过简单的命令即可执行复杂的操作。
+- **环境配置**：可以设置环境变量和默认参数。
+
+后续，你可以参考现有命令自行拓展。
+
+#### 使用示例
+
+- **执行所有测试**：
+  ```shell
+  just run
+  ```
+- **清理缓存**：
+  ```shell
+  just clean-all
+  ```
+
+### 5.2 `.pre-commit-config.yaml` - 代码质量检查
+
+`.pre-commit-config.yaml` 是 pre-commit 工具的配置文件，用于在每次提交代码前自动执行代码质量检查和格式化操作。
+加入此工具的目的是为了代码风格的一致性和代码质量。
+
+#### 主要功能
+
+- **代码检查**：使用 Ruff 进行代码风格检查和格式化。
+- **文件检查**：检查大文件、YAML 文件、TOML 文件的格式。
+- **冲突检测**：检测合并冲突。
+
+#### 使用示例
+
+- **安装 pre-commit 钩子**：
+  ```shell
+  pre-commit install
+  ```
+- **手动运行检查**：
+  ```shell
+  pre-commit run --all-files
+  ```
+
+## 6. 环境与依赖
+
+本项目使用 `uv` 作为包管理工具，所有依赖项均在 `pyproject.toml` 文件中声明。
+
+**环境设置步骤:**
+1.  确保已安装 `uv`。
+2.  在项目根目录下执行以下命令创建并激活虚拟环境：
+    ```shell
+    uv venv
+    source .venv/bin/activate
+    ```
+3.  安装项目依赖：
+    ```shell
+    uv pip install -e .
+    ```
+
+## 7. 执行测试
+
+本项目测试框架基于 `pytest` 构建。在激活虚拟环境后，可使用标准 `pytest` 命令执行测试。
+
+-   **执行所有测试:**
+    ```shell
+    pytest
+    ```
+-   **执行指定场景的测试:**
+    ```shell
+    pytest scenarios/tc_01_social/
+    ```
+-   **执行单个测试文件:**
+    ```shell
+    pytest scenarios/tc_01_social/tc_0101.py
+    ```