Metadata-Version: 2.4
Name: just-go
Version: 0.1.2
Summary: Web 自动化测试框架：框架与测试代码分离，一条命令指定测试项目执行自动化测试并产出报告
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pytest>=8.3.4
Requires-Dist: pytest-rerunfailures
Requires-Dist: allure-python-commons>=2.13.5
Requires-Dist: allure-pytest>=2.13.5
Requires-Dist: loguru>=0.7.3
Requires-Dist: faker
Requires-Dist: requests
Requires-Dist: playwright

# just-go

Web 自动化测试框架：**框架与测试代码分离，一条命令跑指定测试项目，自动产出 allure 报告（含录屏、失败截图、日志）。**

```bash
pip install just-go      # 1. 安装框架
just-go install          # 2. 安装运行依赖（浏览器/报告工具/ffmpeg）
just-go init SHOP-TEST   # 3. 生成测试项目骨架
just-go run SHOP-TEST    # 4. 执行测试项目
```

框架只装一次、全局复用；测试项目单独存放、各自独立。升级框架、换机器、接入 CI，都不影响已写好的测试代码。

---

## 核心特性

| 特性 | 说明 |
| --- | --- |
| **框架与测试代码分离** | 测试项目里没有任何框架源码；框架独立安装升级，项目之间互不影响 |
| **PO 模式脚手架** | `just-go init` 一键生成 GUI / API / 全量骨架，基类下沉公共逻辑，页面/用例只写业务 |
| **同步 / 异步用例混写** | `def` 与 `async def` 任意混用，框架自动路由，无需 pytest-asyncio |
| **桌面录屏（ffmpeg）** | 基于系统 ffmpeg（gdigrab）录制整个桌面，产出 mp4 自动附到报告；`just-go install ffmpeg` 一键安装 |
| **allure 报告开箱即用** | 自动生成 HTML 报告，附失败截图、录屏、用例日志；报告工具与 Java 由 `just-go install` 自动处理 |
| **tag 用例筛选** | 项目 `tag/` 目录 + CSV 登记用例，`--tag "L1 and smoke"` 表达式筛选，支持 and/or/括号 |
| **产物可重定向** | 日志/报告/录屏默认输出在测试项目根，CI 场景用 `--output` 重定向归档 |
| **环境管理省心** | pipenv 虚拟环境自动引导；`just-go install core/playwright/allure/ffmpeg` 缺什么装什么 |

---

## 快速开始

### 1. 安装框架

```bash
pip install just-go
just-go install          # 全部运行依赖：核心库 / Chromium / allure / ffmpeg
```

> 首次执行会提示创建 pipenv 虚拟环境，按提示确认即可；后续命令自动复用。

### 2. 初始化测试项目

```bash
just-go init SHOP-TEST             # GUI 骨架（页面对象 + 页面用例），默认类型
just-go init "SHOP-API[api]"       # API 骨架（接口封装 + 接口用例）
just-go init "SHOP-ALL[all]"       # 两种都生成
```

生成的是**空白脚手架**：目录结构、配置、开发指南齐全，类名/方法名/业务逻辑由你按项目内 README 填充。

### 3. 配置被测地址

编辑测试项目的 `conftest.py`：

```python
os.environ.setdefault("JUSTGO_TEST_BASE_URL", "http://192.168.1.10:8080")  # 被测系统地址（必改）
```

### 4. 注册并运行

```bash
just-go add shop D:\ProjectCode\SHOP-TEST   # 注册项目（名字自己起）
just-go run shop                            # 执行全部用例
just-go run shop --tag "smoke and L1"       # 按 tag 筛选执行
just-go run shop --collect-only             # 只收集用例不执行
```

跑完打开项目根 `reports/` 下最新目录的 `index.html` 查看报告，录屏、失败截图、日志都在里面。

---

## 用例怎么写

`page` 是框架提供的 fixture（Playwright 页面），同步 / 异步两种写法可以混用：

```python
# 同步（默认）
def test_login(page):
    page.goto("https://example.com")
    page.fill("#user", "admin")
    assert "登录成功" in page.content()

# 异步：用例内用 await
async def test_login(page):
    await page.goto("https://example.com")
    await page.fill("#user", "admin")
    assert "登录成功" in await page.content()
```

内置断言（`from just_go import AssertCommon`）：

```python
common = AssertCommon()
common.assert_equal("ok", resp.get("status"))        # 相等
common.assert_in("手机", page_text)                  # 包含
common.assert_re_check_equal(r"\d{6}", page_text)    # 正则匹配
```

框架还提供自定义异常体系（基类 `JustGoError`），测试项目可统一捕获框架错误：

```python
from just_go import JustGoError, RequestError, RecordError

try:
    ...
except JustGoError as e:   # 捕获所有框架自定义异常
    ...
```

> 可选：用例基类声明 `metaclass=CaseControl` 可开启命名校验（用例方法名须包含用例文件名）。

---

## 录屏

- 开启：`pytest.ini` 中的 `--record=yes`（骨架默认开启，删掉该行即关闭）；
  临时开关：`just-go run shop --record=no`
- 方式：系统 ffmpeg 以 `gdigrab` 录制**整个桌面**，产出 mp4 自动附到 allure 报告
- 依赖：系统需已安装 ffmpeg 且加入 PATH

```bash
just-go install ffmpeg    # 自动安装（winget），装完需新开终端刷新 PATH
```

---

## tag 用例筛选（可选）

不用 tag 也能跑：项目没有 `tag/` 目录时，用例全部直接执行。需要筛选时：

**1. 建目录与 CSV**（`just-go init` 骨架自带空表）：

```
tag/
└─ module.csv            # 一个用例模块一个 CSV，与 cases/<模块>/ 对应
```

**2. 登记用例**（4 列）：

```csv
用例ID,用例级别,场景,跳过原因
1001,L1,登录,
1002,L2,订单,接口未就绪
```

- `用例ID` 与用例函数名 `test_<模块>_<用例ID>` 中的 ID 对应（如 `test_login_1001` ↔ `1001`）
- `跳过原因` 填写后该用例自动跳过
- 登记后即可筛选执行：

```bash
just-go run shop --tag "L1 and smoke"          # 逻辑与
just-go run shop --tag "L1 or L2"              # 逻辑或
just-go run shop --tag "(L1 or L2) and smoke"  # 括号组合
```

---

## 常用命令

| 命令 | 作用 |
| --- | --- |
| `just-go install [core\|playwright\|allure\|ffmpeg\|all]` | 安装/检查运行依赖（默认 all） |
| `just-go init <目录[类型]>` | 初始化测试项目骨架（gui/api/all，默认 gui） |
| `just-go add <名称> <路径>` | 注册测试项目 |
| `just-go list` | 列出已注册项目（含路径有效性标记） |
| `just-go remove <名称>` | 取消注册 |
| `just-go run <名称\|路径> [pytest参数]` | 执行测试项目，其余参数透传给 pytest（`--tag`/`--record`/`--collect-only` 等） |

---

## 配置

### 框架级（`just_go/configs/config.ini`，一般不用改）

| 配置项 | 说明 |
| --- | --- |
| `framework.browser_path` | 指定浏览器可执行文件路径（默认用 Playwright 自带 Chromium） |
| `framework.allure_path` | allure 工具路径（留空自动查找 PATH 或 `~/.just-go/allure`） |
| `run.slow_time` | 操作慢速等待毫秒数（默认 500） |
| `run.show_browser` | `True` 显示浏览器窗口 / `False` 无头运行 |

### 项目级

| 配置项 | 位置 | 说明 |
| --- | --- | --- |
| `JUSTGO_TEST_BASE_URL` | 项目 `conftest.py` | 被测系统地址（**必改**），用于页面跳转基址 + 报告环境信息 |
| `JUSTGO_TEST_CASE_BASE_URL` | 项目 `conftest.py` | 测试管理平台（如禅道）用例链接前缀（可选） |
| `--record` | 项目 `pytest.ini` | 录屏开关（默认开） |
| `config.run.slow_time` 等 | 项目 `conftest.py` | 运行时覆盖框架配置，只对本次运行生效 |
| `--output <目录>` | `just-go run` | 产物输出根目录，按 输出根/项目名 分子目录，多项目互不干扰 |

---

## 运行产物

默认输出在测试项目根下：

```
SHOP-TEST/
├─ logs/           # 运行日志（loguru，每次运行一个时间戳文件，10MB 滚动）
├─ reports/        # allure HTML 报告（每次运行一个时间戳目录）
└─ cache/          # allure 原始结果（report/）、临时录屏与截图（temp/）
```

CI / 只读目录场景：`just-go run shop --output D:\产物目录`。

---

## 环境要求

- Python 3.10+
- 浏览器：`just-go install playwright` 自动安装 Chromium
- allure 报告需 Java：`just-go install allure` 检测缺失会自动尝试安装（winget 装 Temurin JDK），装不了会给出手动下载指引
- ffmpeg：录屏必需，`just-go install ffmpeg` 自动安装（winget），或手动下载加入 PATH

> 测试项目自身的 Python 依赖（如 redis、pymysql）由项目自行安装到运行环境，框架不代管。

---

## 常见问题

**录屏没有产出 / 提示 ffmpeg 未安装？**
运行 `just-go install ffmpeg` 自动安装（winget），装完**新开终端**刷新 PATH 再跑。

**allure 报告没生成？**
`just-go install allure` 安装报告工具（需要 Java，检测缺失会自动尝试装 Temurin JDK）。
报告生成依赖 allure 工具；即使未装，allure 原始结果仍保留在 `cache/report/`。

**浏览器起不来 / 提示 playwright 相关错误？**
运行 `just-go install playwright` 安装 Chromium；若配置了 `config.ini` 的 `browser_path`，
确认该路径的浏览器可执行文件存在；无头模式看不到窗口属正常（`config.run.show_browser`）。

**用例收集数量为 0？**
`just-go init` 生成的是空白脚手架，填充前收集到 0 个用例属正常。确认用例函数名以
`test_` 开头、位于 `testpaths`（默认 `cases/`）目录下。

**用例被自动跳过？**
检查对应 `tag/<模块>/<模块名>.csv` 的「跳过原因」列是否已填写。

**`--tag` 筛选不生效？**
`--tag` 依赖 `tag/` 目录与登记数据：确认 CSV 已登记该用例（用例ID 与函数名中 ID 一致），
表达式不区分大小写，支持 `and` / `or` / 括号组合。

**想直接用 pytest 而不是 just-go run？**
可以。项目根 `conftest.py` 已声明框架插件，在项目根直接敲 `pytest` 即可，效果相同。

**导入 just_go 报 `SoftwareNotInstallError`？**
说明依赖（如 playwright）未安装到当前环境：在框架环境内运行 `just-go install`，
或确认当前 Python 与框架运行环境一致（pipenv 环境会自动引导）。
