🔨 零件加工厂 (framework/business/ 目录)
- 它的作用：通俗来说，就是告诉机器人**“这个网页长什么样，上面有哪些按钮”**，以及动作规范。
- 举个例子：在 quantization_page.py 里，定义一个动作 def click_create_task(self): ，并在该方法里调用一次点击，这就像给工厂造好一个拉杆。
🎬 写剧本的导演室 (framework/scripts/ 目录)
- 它的作用：调用上面的零件，编排业务操作顺序。
- 举个例子：在 quantization_scenario.py 里写：先登录 -> 点击主菜单 -> 填名字 -> 点击确认。纯新手流水账思维！

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

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

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

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

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。

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 本体文件：

先在代码开头处注册并实例化你写的模块页面：

# 头部引用你写的剧本文件
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)

把它排队到司令部的日程计划表 run_all_scenarios 里：

# 往下翻，在原本的任务执行步骤 (如 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 就可以看见你写的机器人在飞速跑动接管云业务了！

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

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

法宝一：找不到元素？随时使用强制悬停暂停键！💥

不知道代码跑到哪卡住了？在你怀疑有坑的地方插上一句终极代码：

self.page.pause()

系统无论跑得多快，运行到这一行浏览器一定会自动暂停，并弹出调试器（Playwright Inspector 录制器），你可以直接在活体页面上观察 DOM 并模拟点按，搞清后别忘了把这行删去再接着测。

法宝二：遇到超时 Timeout，网络慢没加载出来？💥

如果你的按钮点击太快，网页还在无骨转圈或者正在“排队中”：

# 1. 纯死等（不推荐，但你作为新手急于跑通，应急时极好用）
import time; time.sleep(5) 

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

法宝三：解决层级乱跳重影错乱的“局部限制术” 💥

如果你发现网页上有几十个叫”确定“的按钮，机器人变傻点错了怎么办？缩小它的搜查圈子：

# 不要瞎搜，先明确告诉它锁定当前名字叫“下载参数”的弹窗气泡区域
dialog = self.page.locator(".p-dialog").filter(has_text="下载参数")

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

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

README.md Unescape Escape

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

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