case-round-trip

name	case-round-trip
description	共享 page 下用例离开起点后必须 UI 返回并断言。触发：往返闭合、case round trip、复位超时、scope 共享 page。

Case Round Trip — 用例往返闭合

仅适用 Playwright + pytest。

核心规则

共享 page（scope > function 的 fixture）下，用例离开起点页后必须在末尾通过真实 UI 返回并断言；不要在复位 fixture 里做 goto 兜底。

何时适用

• 多个用例共享一个 page / browser context（class/module/session scope）
• 用例会进入"脱离门户布局"的页面（子路由、沉浸式页面、跨子域）
• 复位 fixture 依赖门户布局才有的元素（侧边栏 / 顶部 nav）

做法

1. 给每个会"脱离门户布局"的 PageObject 加 click_back_to_<landing>()，走真实 UI 返回按钮
2. 用例主断言后显式调用返回方法，并再次断言起点页加载
3. 复位 fixture 保持最简单形态（仅走门户导航），不做 goto 兜底

def test_enter_detail(self):
    self.home.click_first_item()
    detail = DetailPage(self.page)
    assert detail.is_page_loaded(), "详情页未加载"

    detail.click_back_to_home()
    assert self.home.is_page_loaded(), "返回起点页失败"

起点 is_page_loaded 的严格判据

复位 fixture 通常判断 if not start.is_page_loaded(): start.click_back_to_landing()。若 is_page_loaded() 仅校验"页面骨架可见"（title / 容器），切到其他 tab/子路由后骨架仍在 → 返回 True → 复位永不触发 → 下一用例起点错乱。

规则：起点 PageObject 的 is_page_loaded() 必须包含"当前停留在起点状态"判据（起点 tab 激活态 / 起点 URL / 起点独有内容），而不仅是"骨架存在"。

# ❌ 只校验骨架 — 切到其他 tab 后仍返回 True，复位失效
def is_page_loaded(self) -> bool:
    return self.is_visible(self.PAGE_TITLE) and self.is_visible(self.TAB_BAR)

# ✅ 加"当前在起点 tab"判据 — tab 切换后返回 False，触发复位
def is_page_loaded(self) -> bool:
    return (
        self.is_visible(self.PAGE_TITLE)
        and self.is_visible(self.TAB_BAR)
        and self.is_visible(self.LANDING_TAB_ACTIVE_MARK)   # 关键第 3 条
    )

LANDING_TAB_ACTIVE_MARK 的 selector 必须用 text= 等锁定到具体起点 tab（如 .tab.active >> text=<起点 tab 名>），否则 .active 会匹配任意激活 tab，同样失效（见 locator-strategy.md 状态类 selector 必须配 text 锁定）。

决策

跳转目标是否仍保留起点页的门户导航？
├─ 是 → 依赖复位 fixture 即可
└─ 否 → PageObject 必须提供返回方法 + 用例末尾显式返回 + 断言

❌ 反例

• 进入沉浸式页面后只断言进入，不返回 → 后续用例复位 fixture 点不到门户导航
• page.goto(<landing_url>) 绕过返回按钮 → 失去对返回按钮的回归覆盖
• if not visible: goto(...) 塞进复位 fixture → 掩盖"用例未闭合"真问题

检查清单

• 跳转目标脱离门户布局 → 本规则适用
• PageObject 提供 click_back_to_<landing>()
• 用例末尾调用返回方法并断言起点页加载
• 测试顺序打乱仍全部通过

---

项目落地参考

项目中脱离门户布局的 PageObject（需实现 click_back_to_<landing>）见 docs/pages-catalog.md 与 docs/regression-points.md（带"⚠️ 跳转目标脱离门户布局"标注的页面）。