# 🤖 Robogo 自动化测试平台 - 零基础上手指南

欢迎来到 Robogo 自动化测试项目！哪怕你之前**完全没有**学过前端、不了解自动化是怎么做的，只要你会写简单的 Python 代码，你就能跟着本文档**“像搭积木一样”**愉快地编写并执行各种复杂的自动化流水线！

## 🎯 我们的核心理念 (面向过程的 POM 分层设计)

我们把所有极其复杂的底层网络交互、浏览器驱动都全部封装和隔离了。整个项目对于业务人员来说，只有两个需要改动的地方：

1. **🔨 零件加工厂 (`framework/business/` 目录)**
   - **它的作用**：通俗来说，就是告诉机器人**“这个网页长什么样，上面有哪些按钮”**，以及动作规范。
   - **举个例子**：在 `quantization_page.py` 里，定义一个动作 `def click_create_task(self):` ，并在该方法里调用一次点击，这就像给工厂造好一个拉杆。

2. **🎬 写剧本的导演室 (`framework/scripts/` 目录)**
   - **它的作用**：调用上面的零件，编排**业务操作顺序**。
   - **举个例子**：在 `quantization_scenario.py` 里写：先登录 -> 点击主菜单 -> 填名字 -> 点击确认。纯新手流水账思维！

---

## 🚀 零基础实战：跟我 3 步写一个自动化测试

假设现在上线了一个新功能叫做“工作台 (Workbench)”，老板要求跑自动化测试：点击进入工作台 -> 点击新建 -> 填入内容并保存。

### 前往第一步：教 AI 认界面动作 (Business 层)

进到 `framework/business/` 文件夹下，新建 `workbench_page.py`。你可以直接复制下面的通用模板，只要把名字改了即可：

```python
import time
from framework.core.base_page import BasePage
from framework.core.logger import get_logger

logger = get_logger("WorkbenchPage") 

class WorkbenchPage(BasePage):
    """工作台页面能做的所有动作全写在这"""
    
    def navigate_to(self):
        """1. 进入工作台"""
        logger.info("👉 点击左侧菜单进入工作台页面...")
        self.smart_click("工作台") # ✨极简直觉型绝招：只要页面上有这几个字，它就会自动去点！
        time.sleep(2) # 留点时间给页面刷新加载
        
    def create_and_fill(self, my_text):
        """2. 点击新建，并填入内容"""
        # 点击新建按钮：寻找页面上包含'新建'的 button 把它点掉
        self.page.locator("button:has-text('新建')").click()
        time.sleep(1)
        
        # 填写弹窗中的输入框：(这里是个非常重要并且好套用的通用句式)
        # 逻辑：找包含“名称”两个字的 label(标签)，跳到它的外面直接父层(..)，再找它里面的 input 框
        input_box = self.page.locator("label").filter(has_text="名称").locator("..").locator("input").first
        
        # 写入内容
        input_box.fill(my_text)
        
        # 最后点确定
        self.page.locator("button:has-text('确定')").last.click()
        time.sleep(1)
```

*(是不是很简单？不用辛苦研究所谓底层复杂的 CSS、XPath选择器，直接根据**眼睛看到的界面的中文提示词**找元素)*

---

### 前往第二步：把动作串联成业务流流水账 (Scripts 层)

你在 `business` 层里定义好了这个页面能干嘛，现在来写流水账剧本即可。
在 `framework/scripts/` 目录下，新建 `workbench_scenario.py`。

```python
from framework.core.logger import get_logger
from framework.business.workbench_page import WorkbenchPage

logger = get_logger("WorkbenchScenario")

def run_workbench_lifecycle(wb_page: WorkbenchPage):
    """工作台生命周期全流程"""
    logger.info("🌟 准备开始测试工作台...")
    
    # 就像指挥小人一样，你把它写成一条时间线往下排编
    wb_page.navigate_to()
    
    # [进阶小窍门] 如果要避免重复重名系统报错，可以用随机模块拼凑唯一任务名
    import random
    my_test_name = f"Test_{random.randint(100, 99999)}"
    
    wb_page.create_and_fill(my_test_name)
    
    logger.info("✅ 工作台场景测试完美通过！")
```

---

### 前往第三步：向总控制台挂载你的心血！

我们的自动化引擎总指挥官叫 `DataManagementRunner` (统筹类在 `framework/business/data_management.py` 里)。所有你想随主线跑的测试，统统要去它那边排队报备。

打开 `data_management.py` 本体文件：
1. **先在代码开头处注册并实例化你写的模块页面**：
   ```python
   # 头部引用你写的剧本文件
   from framework.scripts.workbench_scenario import run_workbench_lifecycle
   from framework.business.workbench_page import WorkbenchPage
   
   ...
   # 跳转到 class DataManagement(BasePage) 的 def __init__ 方法里
   # 实例化该页面使其归中央管辖 
   self.wb = WorkbenchPage(self.page)
   ```
2. **把它排队到司令部的日程计划表 `run_all_scenarios` 里**：
   ```python
   # 往下翻，在原本的任务执行步骤 (如 6.量化工具场景) 的底下新增你的区块：
   
   # 7. 工作台测试场景 （记得数字标号）
   try:
       run_workbench_lifecycle(self.wb)
       self._safe_screenshot("workbench_pass.png") # 成功了拍照放进快照库
       logger.info("✅ 工作台场景通过")
   except Exception as e:
       logger.error(f"❌ 工作台场景失败: {e}")
       self._safe_screenshot("workbench_error.png") # 失败了保留案发现场快照以供排期追责
       errors.append(f"工作台测试: {e}")
   ```

🎉 **大功告成！终端执行 `python run_ui_tests.py` 就可以看见你写的机器人在飞速跑动接管云业务了！**

---

## 🛠️ 新手常见阻碍排查法 (三大法宝口诀)

零基础新手绝对不要害怕运行报错，这套自动化平台为你提供了超强法宝：

### 法宝一：找不到元素？随时使用强制悬停暂停键！💥
不知道代码跑到哪卡住了？在你怀疑有坑的地方插上一句终极代码：
```python
self.page.pause()
```
系统无论跑得多快，运行到这一行浏览器一定会自动暂停，并弹出调试器（Playwright Inspector 录制器），你可以直接在活体页面上观察 DOM 并模拟点按，搞清后别忘了把这行删去再接着测。

### 法宝二：遇到超时 Timeout，网络慢没加载出来？💥
如果你的按钮点击太快，网页还在无骨转圈或者正在“排队中”：
```python
# 1. 纯死等（不推荐，但你作为新手急于跑通，应急时极好用）
import time; time.sleep(5) 

# 2. 状态值智能等待（进阶推荐，极度安全，最多等 60 秒超时）
# 等待该标签可见：
self.page.locator("span, tag").filter(has_text="运行中").first.wait_for(state="visible", timeout=60000)
```

### 法宝三：解决层级乱跳重影错乱的“局部限制术” 💥
如果你发现网页上有几十个叫”确定“的按钮，机器人变傻点错了怎么办？缩小它的搜查圈子：
```python
# 不要瞎搜，先明确告诉它锁定当前名字叫“下载参数”的弹窗气泡区域
dialog = self.page.locator(".p-dialog").filter(has_text="下载参数")

# 随后！只要在 dialog 这层继续 locator，它连外面再有成百上千个确定都不会理！极大解决冲突。
dialog.locator("button:has-text('确定')").click()
```

---

> 🎉 **恭喜！** 在完全掌握上面这三步后，整个平台的扩展将任由你发挥。
> 平台最后还内嵌了**全局 Monkey 随机测试机制**（可配置拦截非法按钮）来保障系统的极限容错度。所有的 `Error` 都将成为构建企业级高覆盖率流水线的垫脚石！ —— Automated Platform Team.