# playol

**Repository Path**: zqsssss/playol

## Basic Information

- **Project Name**: playol
- **Description**: api压测框架
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-11
- **Last Updated**: 2026-03-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Playol API Test

这是一个基于 `pytest` 和 `requests` 的轻量级 API 自动化与压力测试框架。它利用 `pytest-xdist` 实现高并发测试，并提供线程安全的数据记录（CSV 报告、Token 管理）功能。

## 目录结构

```
d:\playol\test\
├── config/             # 配置模块
│   ├── config.py       # 全局配置文件 (URL, Headers, 超时设置等)
│   └── __init__.py
├── core/               # 核心库
│   ├── client.py       # API 客户端 (封装 HTTP 请求逻辑)
│   ├── log_manager.py  # 日志管理
│   └── __init__.py
├── test/               # 测试脚本与 Fixtures
│   ├── check_lottery_count.py # 抽奖次数检查工具
│   ├── conftest.py     # Pytest 共享 Fixtures (CSV 报告, 文件锁, 全局配置)
│   ├── test_api.py     # 功能/冒烟测试脚本
│   ├── test_batch_lottery.py # 批量抽奖测试脚本
│   └── test_stress.py  # 压力测试脚本
├── data/               # (自动生成) 测试结果数据与 Token
├── pytest.ini          # Pytest 配置文件
├── requirements.txt    # 项目依赖文件
└── README.md           # 说明文档
```

## 核心功能

*   **标准化测试框架**: 采用业界标准的 `pytest` 框架，支持丰富的插件生态。
*   **高并发支持**: 
    *   集成 `pytest-xdist`，默认单进程，按需启用并发
    *   支持通过环境变量 `PLAYOL_TEST_WORKERS` 设置并发数
    *   可通过命令行 `-n` 参数灵活调整或禁用并发
*   **线程安全的数据管理**:
    *   **CSV 报告**: 自动生成测试结果 CSV，支持多进程安全写入（基于 `filelock`）。
    *   **唯一性保证**: 通过进程标识 + 计数器 + UUID 生成全局唯一邮箱。
*   **灵活配置**: 支持通过命令行参数（如 `--csv-prefix`）自定义报告名称。

## 快速开始

### 1. 环境准备

确保已安装 Python 3.8+，并安装依赖：

```bash
pip install -r requirements.txt
```

主要依赖包括：`pytest`, `pytest-xdist`, `requests`, `filelock`。

### 2. 配置文件 (`config/config.py`)

在运行测试前，请检查 `config/config.py` 中的配置项：

*   `REGISTER_URL` / `SIGN_IN_URL`: 目标接口地址
*   `DEFAULT_WORKERS`: `test_api` 默认任务数（可通过 `PLAYOL_DEFAULT_WORKERS` 调整）
*   `EMAIL_DOMAIN`: 注册邮箱后缀
*   `REQUEST_TIMEOUT`: 请求超时时间

**并发配置**

测试框架默认单进程执行。您可以通过以下方式启用/自定义并发：

```bash
# 方式 1: 设置测试并发数环境变量（推荐）
export PLAYOL_TEST_WORKERS=100               # Linux/Mac
set PLAYOL_TEST_WORKERS=100                  # Windows CMD
$env:PLAYOL_TEST_WORKERS=100                 # Windows PowerShell

# 方式 2: 直接在命令行指定
pytest test/test_api.py -n 100

# 方式 3: 禁用并发（调试时使用）
pytest test/test_api.py -n 0
```

**其他可用的环境变量**

除了 `PLAYOL_TEST_WORKERS`，您还可以通过环境变量覆盖配置：

```bash
PLAYOL_BASE_URL="http://your-server:8081"       # 服务器地址
PLAYOL_DEFAULT_WORKERS=200                      # 默认工作进程数
PLAYOL_REQUEST_TIMEOUT=30                       # 请求超时时间
PLAYOL_REQUEST_RETRY_COUNT=2                    # 请求重试次数（超时/连接错误）
PLAYOL_REQUEST_RETRY_BACKOFF_SECONDS=0.5        # 重试退避秒数
PLAYOL_EMAIL_DOMAIN="gmail.com"                 # 邮箱域名

# API 地址覆盖 (可选)
PLAYOL_REGISTER_URL="..."                       # 注册接口完整 URL
PLAYOL_SIGN_IN_URL="..."                        # 签到接口完整 URL
PLAYOL_LOGIN_URL="..."                          # 登录接口完整 URL
PLAYOL_LOTTERY_URL="..."                        # 抽奖接口完整 URL

# 账号与参数配置
PLAYOL_PASSWORD="your_password"                 # 默认注册密码
PLAYOL_VERIFICATION_CODE="890824"               # 默认验证码
PLAYOL_REWARD_ID="2019248309894664194"          # 奖励 ID
PLAYOL_EMAIL_PREFIX="playol"                    # 邮箱前缀
# ... 更多配置请参考 config/config.py
```

### 3. 运行测试

所有测试均通过 `pytest` 命令执行。默认单进程执行，必要时再开启并发。

**运行功能测试 (API Test)**

适用于验证注册登录流程，或进行小规模并发测试。

```bash
# 默认单进程运行（更稳）
pytest test/test_api.py

# 指定并发数（如 50 个进程）
pytest test/test_api.py -n 50

# 单进程运行（禁用并发）
pytest test/test_api.py -n 0

# 自定义报告文件名前缀
pytest test/test_api.py --csv-prefix my_feature_test

# 通过环境变量设置默认并发数
PLAYOL_TEST_WORKERS=100 pytest test/test_api.py
```

**运行批量抽奖测试 (Batch Lottery Test)**

从 CSV 文件读取已注册账号，批量进行抽奖测试。

```bash
# 默认单进程运行，自动查找最新的 CSV 文件
pytest test/test_batch_lottery.py

# 指定 CSV 文件
pytest test/test_batch_lottery.py --csv-file data/register_records_20260207_094413.csv

# 指定并发数
pytest test/test_batch_lottery.py -n 100

# 单进程运行
pytest test/test_batch_lottery.py -n 0
```

**运行压力测试 (Stress Test)**

适用于高并发场景，批量生成账号并验证系统稳定性。

```bash
# 默认回归流会排除此文件；显式执行该文件即可运行
pytest test/test_stress.py

# 使用 200 个进程并发运行
pytest test/test_stress.py -n 200

# 限制运行特定的任务 ID (例如只运行 task_0 到 task_9)
pytest test/test_stress.py -n 10 -k "task_0 or task_1"

# 从默认流中包含 heavy 用例（stress + cleanup）
pytest --run-heavy
```

**工具脚本: 抽奖次数检查**

`test/check_lottery_count.py` 用于检查 CSV 文件中账号的剩余抽奖次数。

```bash
# 检查指定 CSV 文件中的前 10 个账号
python test/check_lottery_count.py data/register_records_20260207_094413.csv

# 检查前 100 个账号
python test/check_lottery_count.py data/register_records_20260207_094413.csv 100
```

**并发数配置优先级**

并发数的设置遵循以下优先级（从高到低）：

1. 命令行 `-n` 参数（最高优先级）
2. 环境变量 `PLAYOL_TEST_WORKERS`
3. 默认单进程

### 4. 查看结果

测试完成后，结果文件会生成在 `data/` 目录下：

*   **CSV 报告**: `data/{prefix}_{timestamp}.csv` (包含账号、密码、奖励信息、状态)

## 开发指南

### 如何新增测试

只需在 `test/` 目录下创建以 `test_` 开头的 Python 文件，并编写测试函数即可。

**示例 (`test/test_example.py`):**

```python
import pytest
from core.client import PlayolClient
from config import REGISTER_URL, SIGN_IN_URL, DEFAULT_HEADERS

# 初始化客户端
CLIENT = PlayolClient(REGISTER_URL, SIGN_IN_URL, DEFAULT_HEADERS)

# 使用 parametrize 生成多个测试任务
@pytest.mark.parametrize("i", range(10))
def test_custom_logic(i, unique_email, csv_writer):
    # 1. 准备数据 (使用 shared fixture 生成唯一 email)
    email = unique_email
    
    # 2. 执行业务逻辑
    # result = CLIENT.some_action(...)
    result = "success" 
    
    # 3. 记录结果到 CSV
    csv_writer({
        "account": email,
        "status": result,
        "custom_field": "some_value"
    })
    
    # 4. 断言
    assert result == "success"
```

### 常用 Fixtures (`test/conftest.py`)

*   `csv_writer`: 一个函数，接受字典参数，将其写入当前的 CSV 报告文件。
*   `unique_email`: 生成全局唯一邮箱（并发安全）。
*   `device_code`: 生成随机设备码。