# 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
    ```